2.3 Regular R installation

A ‘regular’ installation involves installing patRoon and its dependencies using the local installation of R. This section outlines available tools to do this mostly automatically using the auxiliary patRoonInst and patRoonExt R packages, as well as instructions to perform the complete installation manually.

NOTE It is highly recommended to perform installation steps in a ‘clean’ R session to avoid errors when installing or upgrading packages. As such it is recommended to close all open (R Studio) sessions and open a plain R console to perform the installation.

2.3.1 Automatic installation

The patRoonInst auxiliary package simplifies the installation process. This package automatically installs all R package dependencies, including those unavailable from regular repositories such as CRAN and BiocConductor. Furthermore, patRoonInst installs patRoonExt, an R package that bundles most common dependencies external to the R environment (e.g. MetFrag, OpenMS etc).

The first step is to install patRoonInst:

install.packages("patRoonInst", repos = c('https://rickhelmus.r-universe.dev', 'https://cloud.r-project.org'))

# or alternatively, from GitHub
install.packages("remotes") # run this in case the remotes (or devtools) package is not yet installed
remotes::install_github("rickhelmus/patRoonInst")

Then to perform an installation or update:

patRoonInst::install() # install patRoon and any missing dependencies
patRoonInst::update() # update patRoon and its dependencies

The installation can be customized in various ways. Firstly, the repositories used to download R packages can be customized through the origin argument. The following options are currently available:

patRoonDeps: contains patRoon and its dependencies (including their dependencies) with versions that were tested against the latest patRoon version. This repository is used for the patRoon bundle, and only available for Windows systems.
r-universe: contains a snapshot of the latest version of patRoon and its direct dependencies.
“regular”: in this case packages will be sourced directly from CRAN/BioConductor or GitHub. This means that suitable build tools (e.g. Rtools on Windows) need to be available during installation.

The default on Windows systems is patRoonDeps, and r-universe otherwise. Note that both repositories only provide packages for recent R versions.

Other installation customizations include which packages will be installed (or updated), and installing all packages to an isolated R library. Some examples:

# install from r-universe
patRoonInst::install(origin = "runiverse")
# only install patRoon, without optional dependencies and directly from GitHub
patRoonInst::install(origin = "regular", pkgs = "patRoon")
# full installation, except two selected packages
patRoonInst::install(ignorePkgs = c("nontarget", "MetaClean"))
# full installation, but exclude 'big' optional dependencies such as example data (patRoonData)
patRoonInst::install(ignorePkgs = "big")
# install everything to an isolated R library (use .libPaths() to use it)
patRoonInst::install(lib.loc = "~/patRoon-lib")

Besides installing and updating packages, it is also possible to synchronize them with the selected repository using the sync() function. This is mostly the same as update(), but can also downgrade packages to ensure their versions exactly match that of the repository. This is currently only supported for the patRoonDeps repository. Furthermore, as synchronization may involve downgrading it is intended for environments that are primarily used for patRoon, such as the bundle and isolated R libraries. Synchronization can be performed for all or only direct dependencies:

patRoonInst::sync(allDeps = TRUE) # synchronize all dependencies
patRoonInst::sync(allDeps = FALSE) # synchronize only direct dependencies

More options are available to customize the installation, see the reference manual (?patRoonInst::install) for more details.

2.3.2 Manual installation

A manual installation starts with installing external dependencies, followed by R dependencies and patRoon itself.

2.3.2.1 External (non-R) dependencies

patRoon interfaces with various software tools that are external to R. A complete overview is given in the table below

Dependency	Remarks
Java JDK	Mandatory for e.g. plotting structures and using MetFrag.
OpenBabel	Highly recommend Used by e.g. suspect screening to automatically validate and calculate chemical properties such as InChIs and formulae. While optional, highly recommended.
Rtools	May be necessary on Window when installing `patRoon` and its `R` dependencies (discussed later).
ProteoWizard	Needed for automatic data-pretreatment (e.g. data file conversion and centroiding, Bruker users may use DataAnalysis integration instead).
OpenMS	Recommended. Used for e.g. finding and grouping features.
MetFrag CL	Recommended. Used for annotation with MetFrag.
MetFrag CompTox DB	Database files necessary for usage of the CompTox database with MetFrag. Note that a recent version of MetFrag (>=2.4.5) is required. Note that the lists with additions for smoking metadata and wastewater metadata are also supported.
MetFrag PubChemLite DB	Database file needed to use PubChemLite with MetFrag.
MetFrag PubChem OECD PFAS DB	Database file to use the OECD PFAS database with MetFrag.
SIRIUS	For obtaining feature data and formula and/or compound annotation.
BioTransformer	For prediction of transformation products. See the BioTransformer page for installation details. If you have trouble compiling the jar file you can download it from here.
SAFD	For finding features with SAFD. Please follow all the installation on the SAFD webpage.
pngquant	Used to reduce size of HTML reports (only legacy interface), definitely optional.

Most of these dependencies are optional and only needed if their algorithms are used during the workflow.

2.3.2.1.1 Installation via `patRoonExt`

The patRoonExt auxiliary package automatizes the installation of most common external dependencies. For installation, just run:

install.packages("remotes") # run this if remotes (or devtools) is not already installed
remotes::install_github("rickhelmus/patRoonExt")

NOTE Make sure you have an active internet connection since several files will be downloaded during the installation of patRoonExt.

Note that when you do an automated patRoon installation this package is automatically installed. See the project page for more details, including ways to customize which software tools will be installed.

NOTE Currently, patRoonExt does not install ProteoWizard due to license restrictions, and some tools, such as OpenMS and OpenBabel, are only installed on Windows systems. See the next section to install any missing tools manually.

2.3.2.1.2 Manually installing and configuring external tools

Download the tools manually from the linked sources shown in the table above, and subsequently install (or extract) them. You may need to configure their file paths afterwards (OpenMS, OpenBabel and ProteoWizard are often found automatically). To configure the file locations you should set some global package options with the options() R function, for instance:

options(patRoon.path.pwiz = "C:/ProteoWizard") # location of ProteoWizard installation folder
options(patRoon.path.SIRIUS = "C:/sirius-win64-3.5.1") # directory with the SIRIUS binaries
options(patRoon.path.OpenMS = "/usr/local/bin") # directory with the OpenMS binaries
options(patRoon.path.pngquant = "~/pngquant") # directory containing pngquant binary
options(patRoon.path.MetFragCL = "~/MetFragCommandLine-2.4.8.jar") # full location to the jar file
options(patRoon.path.MetFragCompTox = "C:/CompTox_17March2019_SelectMetaData.csv") # full location to desired CompTox CSV file
options(patRoon.path.MetFragPubChemLite = "~/PubChemLite_exposomics_20220429.csv") # full location to desired PubChemLite CSV file
options(patRoon.path.MetFragPubChemLite = "~/PubChem_OECDPFAS_largerPFASparts_20220324") # full location to PFAS DB (NOTE: configured like PubChemLite)
options(patRoon.path.BioTransformer = "~/biotransformer/biotransformer-3.0.0.jar")
options(patRoon.path.obabel = "C:/Program Files/OpenBabel-3.0.0") # directory with OpenBabel binaries

These commands have to be executed every time you start a new R session (e.g. as part of your script). However, it is probably easier to add them to your ~/.Rprofile file so that they are executed automatically when you start R. If you don’t have this file yet you can simply create it yourself (for more information see e.g. this SO answer).

NOTE The tools that are configured through the options() described above will override any tools that were also installed through patRoonExt. Hence, this mechanism can be used to use specific versions not available though patRoonExt. However, this also means that you need to ensure that options are unset when you prefer that tools are used through patRoonExt.

2.3.2.2 Installing patRoon and its R dependencies

The table below lists all the R packages that are involved in the installation of patRoon.

package	comments	patRoonDeps	r-universe	regular installation
CAMERA	Mandatory	no	no	`BiocManager::install('CAMERA')`
RDCOMClient	Only for windows	no	no	`remotes::install_github('BSchamberger/RDCOMClient')`
InterpretMSSpectrum	Dependency of RAMClustR	no	yes	`remotes::install_github('cran/InterpretMSSpectrum@1.3.3')`
RAMClustR		no	yes	`remotes::install_github('cbroeckl/RAMClustR@e005614')`
enviPick		no	yes	`remotes::install_github('blosloos/enviPick')`
nontargetData	Dependency of nontarget	no	yes	`remotes::install_github('blosloos/nontargetData')`
nontarget		no	yes	`remotes::install_github('blosloos/nontarget')`
ropls	Dependency of KPIC	no	no	`BiocManager::install('ropls')`
KPIC		no	yes	`remotes::install_github('rickhelmus/KPIC2')`
qlcMatrix	Dependency of cliqueMS	no	yes	`remotes::install_github('cysouw/qlcMatrix')`
cliqueMS		no	yes	`remotes::install_github('rickhelmus/cliqueMS')`
BiocStyle	Dependency of MetaClean	no	no	`BiocManager::install('BiocStyle')`
Rgraphviz	Dependency of MetaClean	no	no	`BiocManager::install('Rgraphviz')`
fastAdaboost	Dependency of MetaClean	no	yes	`remotes::install_github('souravc83/fastAdaboost')`
MetaClean		no	yes	`remotes::install_github('KelseyChetnik/MetaClean')`
MetaCleanData		no	no	`remotes::install_github('KelseyChetnik/MetaCleanData')`
splashR		no	yes	`remotes::install_github('berlinguyinca/spectra-hash')`
MS2Tox		no	no	`remotes::install_github('kruvelab/MS2Tox@main')`
MS2Quant		no	yes	`remotes::install_github('drewszabo/MS2Quant@main')`
patRoonData		no	no	`remotes::install_github('rickhelmus/patRoonData')`
patRoonExt		no	no	`remotes::install_github('rickhelmus/patRoonExt')`
patRoon		no	yes	`remotes::install_github('rickhelmus/patRoon@master')`

Note that only the CAMERA installation is mandatory, the rest involves installation of optional packages. If you are unsure which you need then you can always install the packages at a later stage.

The last three columns of the table provide hints on the availability from the patRoonDeps, r-universe and original regular sources (the sources were discussed previously). Note that you may need to install remotes, BiocManager and Rtools if packages are installed from their regular source. Some examples are shown below:

# Install patRoon (and its mandatory dependencies) from patRoonDeps
install.packages("patRoon", repos = "https://rickhelmus.github.io/patRoonDeps", type = "binary")

# Install KPIC2 from r-universe
install.packages("KPIC", repos = c('https://rickhelmus.r-universe.dev', 'https://cloud.r-project.org'))

# Install the mandatory CAMERA package (will be installed automatically if using patRoonDeps/r-universe)
install.packages("BiocManager") # execute this if 'BiocManager' is not yet installed
BiocManager::install("CAMERA")

# Install patRoonData from GitHub
install.packages("remotes") # execute this if remotes (or devtools) is not yet installed
remotes::install_github("rickhelmus/patRoonData")

2.3.3 Verifying the installation

After the installation is completed, you may need to restart R. Afterwards, the verifyDependencies() function can be used to see if patRoon can find all its dependencies:

patRoon::verifyDependencies()