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’
Rsession 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 dependenciesThe 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: containspatRoonand its dependencies (including their dependencies) with versions that were tested against the latestpatRoonversion. This repository is used for the patRoon bundle, and only available for Windows systems.- r-universe: contains a snapshot of the latest version of
patRoonand 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 dependenciesMore 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,
patRoonExtdoes 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 binariesThese 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 throughpatRoonExt. Hence, this mechanism can be used to use specific versions not available thoughpatRoonExt. However, this also means that you need to ensure that options are unset when you prefer that tools are used throughpatRoonExt.
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')
|
| RAMClustR | no | yes |
install.packages('RAMClustR')
|
|
| 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')
|
|
| 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('kruvelab/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")