Package 'patRoon'

Description

Provides an easy-to-use interface to a mass spectrometry based non-target analysis workflow. Various (open-source) tools are combined which provide algorithms for extraction and grouping of features, extraction of MS and MS/MS data, automatic formula and compound annotation and grouping related features to components. In addition, various tools are provided for e.g. data preparation and cleanup, plotting results and automatic reporting.

Package options

The following package options (see options) can be set:

• patRoon.cache.mode: A character setting the current caching mode: "save" and "load" will only save/load results to/from the cache, "both" (default) will do both and "none" to completely disable caching. This option can be changed anytime, which might be useful, for instance, to temporarily disable cached results before running a function.

• patRoon.cache.fileName: a character specifying the name of the cache file (default is ‘cache.sqlite’).

• patRoon.cache.maxEntries: a numeric specifying the maximum number of entries per cache category (default is 100000). When this limit is exceeded, the oldest entries are automatically removed.

• patRoon.MS.backends,patRoon.MS.preferIMS,patRoon.path.TDFSDK: Options related to the raw data interface.

• patRoon.threads: The number of threads to be used for parallelization. This is currently only used by the raw data interface and when the piek algorithm is used for peak detection.

• patRoon.MP.maxProcs: The maximum number of processes that should be initiated in parallel. A good starting point is the number of physical cores, which is the default as detected by detectCores. This option is only used when patRoon.MP.method="classic".

• patRoon.MP.method: Either "classic" or "future". The former is the default and uses processx to execute multiple commands in parallel. When "future" the future.apply package is used for parallelization, which is especially useful for e.g. cluster computing.

• patRoon.MP.futureSched: Sets the future.scheduling function argument for future_lapply. Only used if patRoon.MP.method="future".

• patRoon.MP.logPath: The path used for logging of output from commands executed by multiprocess. Set to FALSE to disable logging.

• patRoon.path.pwiz: The path in which the ProteoWizard binaries are installed. If unset an attempt is made to find this directory from the Windows registry and PATH environment variable.

• patRoon.path.GenForm: The path to the GenForm executable. If not set (the default) the internal GenForm binary is used. Only set if you want to override the executable.

• patRoon.path.MetFragCL: The complete file path to the MetFrag CL ‘jar’ to be used by generateCompoundsMetFrag. Example: "C:/MetFrag2.4.2-CL.jar".

• patRoon.path.MetFragCompTox: The complete file path to the CompTox database ‘csv’ file. See generateCompounds for more details.

• patRoon.path.MetFragPubChemLite: The complete file path to the PubChemLite database ‘csv’ file. See generateCompounds for more details.

• patRoon.path.SIRIUS: The directory in which the SIRIUS binaries are installed. Used by all functions that interface with SIRIUS, such as generateFormulasSIRIUS and generateCompoundsSIRIUS. Example: "C:/sirius-win64-3.5.1". Note that the location of the binaries differs for each operating system.

• patRoon.path.OpenMS: The path in which the OpenMS binaries are installed.

• patRoon.path.obabel: The path in which the OpenBabel binaries are installed.

• patRoon.path.BiotransFormer The full file path to the biotransformer ‘.jar’ command line utility. This needs to be set when generateTPsBioTransformer is used. For more details see https://bitbucket.org/djoumbou/biotransformer/src/master.

• patRoon.path.limits A path to a customized limits YAML file.

Most external dependencies are provided by patRoonExt or otherwise found in the system environment PATH variable. However, the patRoon.path.* options should be set if this fails or you want to override the location. The verifyDependencies function can be used to assess if dependencies are found.

Author(s)

Maintainer: Rick Helmus [email protected] (ORCID)

Authors:

• Rick Helmus [email protected] (ORCID)

Other contributors:

• Olaf Brock (ORCID) [contributor]

• Vittorio Albergamo (ORCID) [contributor]

• Andrea Brunner (ORCID) [contributor]

• Emma Schymanski (ORCID) [contributor]

• Bas van de Velde (ORCID) [contributor]

• Leon Saal (ORCID) [contributor]

See Also

Useful links:

• https://github.com/rickhelmus/patRoon

• Report bugs at https://github.com/rickhelmus/patRoon/issues

Description

Objects from this class are used to specify adduct information in an algorithm independent way.

Usage

adduct(...)

## S4 method for signature 'adduct'
show(object)

## S4 method for signature 'adduct'
as.character(x, format = "generic", err = TRUE)

Arguments

Methods (by generic)

• show(adduct): Shows summary information for this object.

• as.character(adduct): Converts an adduct object to a specified character format.

Slots

add,sub

A character with one or more formulas to add/subtract.

molMult

How many times the original molecule is present in this molecule (e.g. for a dimer this would be ‘⁠2⁠’). Default is ‘⁠1⁠’.

charge

The final charge of the adduct (default ‘⁠1⁠’).

See Also

as.adduct for easy creation of adduct objects and adduct utilities for other adduct functionality.

Examples

adduct("H") # [M+H]+
adduct(sub = "H", charge = -1) # [M-H]-
adduct(add = "K", sub = "H2", charge = -1) # [M+K-H2]+
adduct(add = "H3", charge = 3) # [M+H3]3+
adduct(add = "H", molMult = 2) # [2M+H]+

as.character(adduct("H")) # returns "[M+H]+"

Description

Several utility functions to work with adducts.

Usage

GenFormAdducts()

MetFragAdducts()

as.adduct(x, format = "generic", isPositive = NULL, charge = NULL, err = TRUE)

calculateIonFormula(formula, adduct)

calculateNeutralFormula(formula, adduct)

Arguments

Details

GenFormAdducts returns a table with information on adducts supported by GenForm.

MetFragAdducts returns a table with information on adducts supported by MetFrag.

as.adduct Converts an object in to an adduct object.

calculateIonFormula Converts one or more neutral formulae to adduct ions.

calculateNeutralFormula Converts one or more adduct ions to neutral formulae.

Examples

as.adduct("[M+H]+")
as.adduct("[M+H2]2+")
as.adduct("[2M+H]+")
as.adduct("[M-H]-")
as.adduct("+H", format = "genform")
as.adduct(1, isPositive = TRUE, format = "metfrag") # MetFrag adduct ID 1 --> returns [M+H]+

calculateIonFormula("C2H4O", "[M+H]+") # C2H5O
calculateNeutralFormula("C2H5O", "[M+H]+") # C2H4O

Description

Properties for the sample analyses used in the workflow and utilities to automatically generate this information.

Usage

generateAnalysisInfo(
  fromRaw = NULL,
  fromCentroid = NULL,
  fromProfile = NULL,
  fromIMS = NULL,
  convCentroid = NULL,
  convProfile = NULL,
  convIMS = NULL,
  ...
)

generateAnalysisInfoFromEnviMass(path)

Arguments

Details

In patRoon a sample analysis, or simply analysis, refers to a single MS analysis file (sometimes also called sample or file). The analysis information summarizes several properties for the analyses, and is used in various steps throughout the workflow, such as findFeatures, averaging intensities of feature groups and blank subtraction. The analysis information should be a data.frame or data.table with a set of mandatory and optional columns (described below).

generateAnalysisInfo is an utility function that automatically generates analysis information. It scans given directories for analysis files, and uses this to automatically fill in the analysis and path_* columns. This function automatically groups together analyses that are stored with different file types and formats (see further details below).

generateAnalysisInfoFromEnviMass loads analysis information from an enviMass project. Note: this funtionality has only been tested with older versions of enviMass.

Value

generateAnalysisInformation returns a data.frame with automatically generated analysis information.

Mandatory analysis information columns

The following columns should be present in the analysis information:

• path_raw, path_centroid, path_profile, path_ims Specifies the directory path for the raw, centroided, profile and IMS data, respectively. See below for more details. At least one column should not be empty for each row.

• analysis the file name without extension and without directory path. Must be unique across all table rows.

• replicate name of the replicate. Used to group analyses together that are replicates of each other. Thus, the replicate column for all analyses considered to be belonging to the same replicate should have an equal (but unique) value. Used for e.g. averaging and filter.

• blank all analyses within this replicate are used by the featureGroups method of filter for blank subtraction. Multiple entries can be entered by separation with a comma. May be empty ("") if no blank subtraction is desired.

Analysis paths, file types and file formats

Depending on the workflow step, different file types for the same analysis may be required.

• raw Specifies the directory to raw HRMS files (e.g. ‘.raw’, ‘.d’). This is used by e.g. conversion of raw MS data and the OpenTIMS backend.

• centroid Specifies the directory to centroided and exported HRMS files (‘.mzML’, ‘.mzXML’). These files are required by most feature finding algorithms.

• profile Specifies the directory to exported but not centroided (i.e. profile) HRMS data files (‘.mzML’, ‘.mzXML’). This is currently only used by findFeaturesSAFD.

• ims Specifies the directory to exported IMS-HRMS data (‘.mzML’). This is required in IMS workflows, unless raw IMS-HRMS data is directly loaded with the OpenTIMS backend. See e.g. assignMobilities for more details.

Some workflows may require multiple file formats for a same file type. In this case, the file formats should be stored within the same directory specified by the respective path_* column. For instance, if feature finding algorithms from OpenMS and enviPick are mixed then centroided ‘.mzML’ and ‘.mzXML’ files are needed, and files with both file formats must be stored in the directory specified by path_centroid.

If non-raw data files are not yet present and should be exported by MS file conversion, then path_centroid, path_profile and path_ims should specify the desired destination paths of the converted files.

Optional columns and sample metadata

The following columns may need to be present:

• conc a numeric value specifying the 'concentration' for the analysis. This can be actually any kind of numeric value such as exposure time, dilution factor or anything else which may be used to form a linear relationship. This is used by the as.data.table method if regression=TRUE. As of patRoon version 3.0, any other column than "conc" can be used by setting its name with the regression argument.

• norm_conc a numeric value specifying the normalization concentration for the analysis. See the ⁠Feature intensity normalization⁠ section in the featureGroups documentation) for more details.

Any other columns that are present will be added to the features and featureGroups objects as metadata. This metadata can be used e.g. in various plotting and data subsetting functions.

Description

Various parsing and plotting functions for the analysisInfo data.frame.

Usage

## S4 method for signature 'data.frame'
getTICs(obj, retentionRange = NULL, MSLevel = 1)

## S4 method for signature 'data.frame'
getBPCs(obj, retentionRange = NULL, MSLevel = 1)

## S4 method for signature 'data.frame'
plotTICs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'data.frame'
plotBPCs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'data.table'
plotTICs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'data.table'
plotBPCs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments

Functions

• getTICs(data.frame): Obtain the total ion chromatogram/s (TICs) of the analyses.

• getBPCs(data.frame): Obtain the base peak chromatogram/s (BPCs) of the analyses.

• plotTICs(data.frame): Plots the TICs of the analyses.

• plotBPCs(data.frame): Plots the BPCs of the analyses.

• plotBPCs(data.table): Plots the BPCs of the analyses.

Use of raw HRMS data

The raw data interface of patRoon is used by these functions to process HRMS (or IMS-HRMS) data. Please see its documentation for more information on the supported formats and available configuration options.

Author(s)

Ricardo Cunha ([email protected]) and Rick Helmus ([email protected])

Description

Assigns ion mobility and CCS values to the candidates in a compounds object.

Usage

## S4 method for signature 'compounds'
assignMobilities(
  obj,
  fGroups,
  IMS = TRUE,
  from = NULL,
  matchFromBy = "InChIKey1",
  overwrite = FALSE,
  adduct = NULL,
  CCSParams = NULL,
  prefCalcChemProps = TRUE,
  neutralChemProps = FALSE,
  virtualenv = "patRoon-C3SDB"
)

## S4 method for signature 'compoundsSet'
assignMobilities(obj, fGroups, IMS = TRUE, from = NULL, ...)

Arguments

Details

The assignMobilities method for compounds is used to (1) add predicted or known IMS data to annotation candidates and (2) convert (previously added) mobility <–> CCS values. Internally, the assignMobilities method for suspects is used to perform these operations, please see its documentation for more details.

If both adduct specific and non-adduct specific mobility and CCS data is available (and not NA), then the non-adduct specific data is assigned to the compound candidate. Otherwise, data corresponding to the adduct argument or the adduct assigned to the feature group is taken. The filter method can be used to filter out candidates with deviating IMS data.

Sets workflows

In a sets workflow the calculations are performed and stored independently for each set, as adducts, charges and m/z values typically differ.

The from argument may be a list that specifies the from values for each set. This is primarily intended when tables are used to set from.

Note

SIRIUS does currently not report InChIKey values, hence, matchFromBy="InChIKey" is not supported in this case.

If compound annotation is performed with generateCompoundsMetFrag with database="pubchemlite" then CCS data is already added, provided the local database has it. If you want to overwrite this data, set overwrite=TRUE.

See Also

The assignMobilities method for suspects.

Description

Various approaches to assign mobilities to features and perform CCS conversions.

Usage

## S4 method for signature 'featureGroups'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe"
)

## S4 method for signature 'featureGroupsSet'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe"
)

## S4 method for signature 'featureGroupsScreening'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe",
  fromSuspects = FALSE,
  IMSMatchParams = NULL
)

## S4 method for signature 'featureGroupsScreeningSet'
assignMobilities(
  obj,
  mobPeakParams = NULL,
  chromPeakParams = NULL,
  EIMParams = getDefEIMParams(),
  EICParams = getDefEICParams(),
  peakRTWindow = defaultLim("retention", "narrow"),
  fallbackEIC = TRUE,
  calcArea = "integrate",
  mobWindow = defaultLim("mobility", "medium"),
  scoreWeights = c(mobility = 1, intensity = 1),
  CCSParams = NULL,
  parallel = "maybe",
  fromSuspects = FALSE,
  IMSMatchParams = NULL
)

Arguments

Details

The assignMobilities method function for features is used (1) to assign Ion Mobility values and (2) calculate CCS values from these mobilities.

In patRoon, two approaches are supported to assign mobilities to features: direct and post assignment (DMA and PMA). With the DMA the mobility values are directly assigned during feature detection. This is currently only supported by the piek and greedy algorithms or by importing feature data. With PMA, the mobility values are assigned after feature detection and grouping (and possibly other steps such as filtering). Thus, the PMA approach is supported by all available feature detection algorithms in patRoon. The PMA approach is further described below. Only the CCS conversion functionality of assignMobilities should be used in PMA mobility assignment workflows.

The assignment of CCS values is controlled by the CCSParams argument (see above).

In suspect screening workflows assignMobilities also assigns reference mobility and CCS values to suspect hits, and can filter hits if IMSMatchParams is set. This is similarly performed as screenSuspects, please see its documentation for more details.

Post mobility assignment

The post assignment of mobilities occurs in the following steps:

1. Extracted ion mobilograms (EIMs) are generated for all features and subjected to automatic peak detection to obtain mobility peaks.

2. The detected mobility peaks in an EIM are then used to form IMS features. These features inherit their LC-MS properties (RT, m/z, etc) from the corresponding IMS precursor, i.e. the feature for which the EIM was created. The mobility peak centroids and ranges are used to assign IMS data to the IMS features. Multiple mobility peaks within the same EIM result in multiple IMS features, and each are linked to the same IMS precursor. The linkage is especially useful to keep a relation between e.g. protomers.

3. LC-MS properties such as the area, intensity and RTs are (optionally) updated by re-integration of detected peaks from mobility filtered extracted ion chromatograms. If peak detection is disabled or fails, then the intensity and areas can be estimated directly from raw EIC data (fallbackEIC argument).

4. Any IMS features that could not be re-integrated (either by peak detection or EIC fallback) are removed.

5. The feature grouping is updated: the IMS features with close mobilities (defined by mobWindow) within a feature group are split-off into new feature groups and linked to the original IMS precursor feature group. This is performed by the greedy grouping algorithm. LC-MS properties and most other data such as feature group qualities and scores (calculatePeakQualities), adduct annotations (e.g. selectIons), predicted concentrations and toxicities (calculateConcs and calculateTox) and internal standards for intensity normalization (normInts) are copied from the IMS precursors to the IMS feature groups.

Note that re-running assignMobilities will first remove any existing IMS features.

Suspect screening workflows

In suspect screening workflows the fromSuspects arguments can be set to alternatively perform mobility assignment directly from the suspect list data (replacing Steps 1-2). The feature mobility is simply assigned from the suspect data and the mobility range is derived from the mobWindow argument. Relationships with IMS precursors (Step 2) are similarly formed. An advantage of this approach is that no mobility peak detection is needed, which may useful for low intensity features where this could be difficult. Setting fromSuspects=TRUE is primarily intended for workflows where (1) the mobility of a suspect is accurately known upfront or (2) IMS data should only be used as a rough filtering step for feature data. In the latter case accurate feature mobility assignment is not of interest and the suspect IMS data is typically not accurately known (e.g. predicted), hence, for these workflows the tolerance specified by mobWindow should be increased.

With fromSuspects=TRUE no mobility peak detection is performed, hence, the actual presence of the feature is only verified in Step 3. For this reason, falling back to EIC data (fallbackEIC argument) is never performed for IMS features from suspects, and chromPeakParams must always be defined to allow chromatographic peak detection.

If both fromSuspects and mobPeakParams are set, regular mobility assignment (Steps 1-2) is performed for features without suspect hit. If multiple suspects were assigned to a feature group then suspect data is never used to form IMS features.

IMS features

The features (and feature groups) with IMS properties are referred to IMS features (and IMS feature groups). These are referred to orphans if their link to the original IMS precursor is removed (in post workflows, see previous section) or non-existent (direct workflows). The formation of orphans in post workflows typically occurs by removal of IMS precursors by subsetting or filtering operations.

Most data-processing functionality, such as subsetting, plotting, filtering, etc., allows to selectively operate either on the IMS features, their IMS precursors, both or either the precursor or orphans (controlled by the IMS argument to the corresponding functions).

Use of raw HRMS data

The raw data interface of patRoon is used by assignMobilities to process HRMS (or IMS-HRMS) data. Please see its documentation for more information on the supported formats and available configuration options.

Sets workflows

Mobility assignment in a sets workflow is equivalent to non-sets workflows. However, currently there is no (known) way to relate mobilities across MS polarities (+/- mode). Thus, IMS features will always be formed for each set separately. However, IMS precursors will still be grouped across polarities (like a non-IMS workflow) and their links to IMS features can therefore be used to relate IMS features across MS polarities.

Description

Adds calculated mobility and/or CCS data to a suspect list.

Usage

## S4 method for signature 'data.table'
assignMobilities(
  obj,
  from = NULL,
  matchFromBy = "InChIKey1",
  overwrite = FALSE,
  adducts = c("[M+H]+", "[M-H]-", NA),
  predictAdductOnly = TRUE,
  CCSParams = NULL,
  prepareChemProps = TRUE,
  prefCalcChemProps = TRUE,
  neutralChemProps = FALSE,
  virtualenv = "patRoon-C3SDB"
)

## S4 method for signature 'data.frame'
assignMobilities(obj, ...)

Arguments

Details

The assignMobilities method for suspect lists is used to (1) add IMS data to suspects from predictions or library data and (2) convert (previously added) mobility <–> CCS values. These steps are controlled by the from and CCSParams arguments, respectively.

Mobility and CCS values assigned in the suspect list are either adduct specific or not. Adduct specific values are preferred, as the 'correct' value can be automatically selected during suspect screening based on the adduct assigned to the feature (or passed as the adduct argument to screenSuspects). The non-adduct specific values are typically used when the corresponding adduct for the mobility/CCS value is unknown (or not of interest). These values get precedence over adduct specific values. The adduct specific values are stored in mobility_<adduct> and CCS_<adduct> columns, where <adduct> is the adduct name (e.g. [M+H]+, [M-H]-). The mobility and CCS columns store any non-adduct specific values. The adducts argument ultimately defines the use of adduct and non-adduct specific values.

The mobility <–> CCS conversions occur both ways, i.e. missing CCS values will be converted from mobility values and vice versa. If adduct specific values are converted then the charge value used for these calculations is taken from the corresponding adduct. For non-adduct specific values the charge is taken from the adduct specified in suspect list if present, or from the default charge specified in CCSParams otherwise.

Validating and calculating chemical properties

Chemical properties such as SMILES, InChIKey and formulae in the suspect data (if prepareChemProps=TRUE) and from data (if a table) are automatically validated and calculated if missing/invalid.

The internal validation/calculation process performs the following steps:

• Validation of SMILES, InChI, InChIKey and formula data (if present). Invalid entries will be set to NA.

• If neutralChemProps=TRUE then chemical data (SMILES, formulae etc.) is neutralized by (de-)protonation (using the --neutralized option of OpenBabel). An additional column molNeutralized is added to mark those molecules that were neutralized. Note that neutralization requires either SMILES or InChI data to be available.

• The SMILES and InChI data are used to calculate missing or invalid SMILES, InChI, InChIKey and formula data. If prefCalcChemProps=TRUE then existing InChIKey and formula data is overwritten by calculated values whenever possible.

• The chemical formulae which were not calculated are verified and normalized. This process may be time consuming, and is potentially largely avoided by setting prefCalcChemProps=TRUE.

• Neutral masses are calculated for missing values (prefCalcChemProps=FALSE) or whenever possible (prefCalcChemProps=TRUE).

Note that calculation of formulae for molecules that are isotopically labelled is currently only supported for deuterium (2H) elements.

This functionality relies heavily on OpenBabel, please make sure it is installed.

References

OBoyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR (2011). “Open Babel: An open chemical toolbox.” Journal of Cheminformatics, 3(1). doi:10.1186/1758-2946-3-33.

Schymanski EL, Kondić T, Neumann S, Thiessen PA, Zhang J, Bolton EE (2021). “Empowering large chemical knowledge bases for exposomics: PubChemLite meets MetFrag.” Journal of Cheminformatics, 13(1). ISSN 1758-2946. doi:10.1186/s13321-021-00489-0. http://dx.doi.org/10.1186/s13321-021-00489-0.

Elapavalore A, Ross DH, Grouès V, Aurich D, Krinsky AM, Kim S, Thiessen PA, Zhang J, Dodds JN, Baker ES, Bolton EE, Xu L, Schymanski EL (2025). “PubChemLite Plus Collision Cross Section (CCS) Values for Enhanced Interpretation of Nontarget Environmental Data.” Environmental Science & Technology Letters, 12(2), 166–174. ISSN 2328-8930. doi:10.1021/acs.estlett.4c01003. http://dx.doi.org/10.1021/acs.estlett.4c01003.

Ross DH, Cho JH, Xu L (2020). “Breaking Down Structural Diversity for Comprehensive Prediction of Ion-Neutral Collision Cross Sections.” Analytical Chemistry, 92(6), 4548–4557. ISSN 1520-6882. doi:10.1021/acs.analchem.9b05772. http://dx.doi.org/10.1021/acs.analchem.9b05772.

Description

Miscellaneous utility functions which interface with Bruker DataAnalysis

Usage

showDataAnalysis()

setDAMethod(anaInfo, method, close = TRUE)

revertDAAnalyses(anaInfo, close = TRUE, save = close)

recalibrarateDAFiles(anaInfo, close = TRUE, save = close)

getDACalibrationError(anaInfo)

addDAEIC(
  analysis,
  path,
  mz,
  mzWindow = defaultLim("mz", "medium"),
  ctype = "EIC",
  mtype = "MS",
  polarity = "both",
  bgsubtr = FALSE,
  fragpath = "",
  name = NULL,
  hideDA = TRUE,
  close = FALSE,
  save = close
)

addAllDAEICs(
  fGroups,
  mzWindow = defaultLim("mz", "medium"),
  ctype = "EIC",
  bgsubtr = FALSE,
  name = TRUE,
  onlyPresent = TRUE,
  hideDA = TRUE,
  close = FALSE,
  save = close
)

Arguments

Details

These functions communicate directly with Bruker DataAnalysis to provide various functionality, such as calibrating and exporting data and adding chromatographic traces. For this the RDCOMClient package is required to be installed.

showDataAnalysis makes a hidden DataAnalysis window visible again. Most functions using DataAnalysis will hide the window during processing for efficiency reasons. If the window remains hidden (e.g. because there was an error) this function can be used to make it visible again. This function can also be used to start DataAnalysis if it is not running yet.

setDAMethod Sets a given DataAnalysis method (‘.m’ file) to a set of analyses. NOTE: as a workaround for a bug in DataAnalysis, this function will save(!), close and re-open any analyses that are already open prior to setting the new method. The close argument only controls whether the file should be closed after setting the method (files are always saved).

revertDAAnalyses Reverts a given set of analyses to their unprocessed raw state.

recalibrarateDAFiles Performs automatic mass recalibration of a given set of analyses. The current method settings for each analyses will be used.

getDACalibrationError is used to obtain the standard deviation of the current mass calibration (in ppm).

addDAEIC adds an Extracted Ion Chromatogram (EIC) or other chromatographic trace to a given analysis which can be used directly with DataAnalysis.

addAllDAEICs adds Extracted Ion Chromatograms (EICs) for all features within a featureGroups object.

Value

getDACalibrationError returns a data.frame with a column of all analyses (named analysis) and their mass error (named error).

See Also

analysis-information

Description

Returns the adducts supported by the C3SDB Python package.

Usage

C3SDBAdducts()

Description

Several utility functions for caching workflow data. The most important function is clearCache; other functions are primarily for internal use.

Usage

makeHash(..., checkDT = TRUE)

makeFileHash(..., length = Inf)

loadCacheData(category, hashes, dbArg = NULL, simplify = TRUE, fixDTs = TRUE)

saveCacheData(category, data, hash, dbArg = NULL)

clearCache(what = NULL, file = NULL, vacuum = TRUE)

Arguments

Details

makeHash Make a hash string of given arguments.

makeFileHash Generates a hash from the contents of one or more files.

loadCacheData Loads cached data from a database.

saveCacheData caches data in a database.

clearCache will either remove one or more tables within the cache sqlite database or simply wipe the whole cache file. Removing tables will VACUUM the database (unless vacuum=FALSE), which may take some time for large cache files.

Description

Utility functions to convert between mobility and CCS data.

Usage

convertMobilityToCCS(mobility, mz, CCSParams, charge = NULL)

convertCCSToMobility(ccs, mz, CCSParams, charge = NULL)

Arguments

Description

These functions provide interactive utilities to explore and review workflow data using a shiny graphical user interface (GUI). In addition, unsatisfactory data (e.g. noise identified as a feature and unrelated feature groups in a component) can easily be selected for removal.

Usage

checkFeatures(
  fGroups,
  session = "checked-features.yml",
  EICParams = getDefEICParams(),
  EIMParams = getDefEIMParams(),
  clearSession = FALSE
)

checkComponents(
  components,
  fGroups,
  session = "checked-components.yml",
  EICParams = getDefEICParams(),
  clearSession = FALSE
)

## S4 method for signature 'components'
checkComponents(
  components,
  fGroups,
  session = "checked-components.yml",
  EICParams = getDefEICParams(),
  clearSession = FALSE
)

importCheckFeaturesSession(
  sessionIn,
  sessionOut,
  fGroups,
  rtWindow = defaultLim("retention", "narrow"),
  mzWindow = defaultLim("mz", "narrow"),
  mobWindow = defaultLim("mobility", "narrow"),
  overwrite = FALSE
)

## S4 method for signature 'featureGroups'
checkFeatures(
  fGroups,
  session = "checked-features.yml",
  EICParams = getDefEICParams(),
  EIMParams = getDefEIMParams(),
  clearSession = FALSE
)

getMCTrainData(fGroups, session)

predictCheckFeaturesSession(fGroups, session, model = NULL, overwrite = FALSE)

Arguments

Details

The data selected for removal is stored in sessions. These are ‘YAML’ files to allow easy external manipulation. The sessions can be used to restore the selections that were made for data removal when the GUI tool is executed again. Furthermore, functionality is provided to import and export sessions. To actually remove the data the filter method should be used with the session file as input.

checkComponents is used to review components and their feature groups contained within. A typical use case is to verify that peaks from features that were annotated as related adducts and/or isotopes are correctly aligned.

importCheckFeaturesSession is used to import a session file that was generated from a different featureGroups object. This is useful to avoid re-doing manual interpretation of chromatographic peaks when, for instance, feature group data is re-created with different parameters.

checkFeatures is used to review chromatographic information for feature groups. Its main purpose is to assist in reviewing the quality of detected feature (groups) and easily select unwanted data such as features with poor peak shapes or noise.

getMCTrainData converts a session created by checkFeatures to a data.frame that can be used by the MetaClean to train a new model. The output format is comparable to that from getPeakQualityMetrics.

predictCheckFeaturesSession Uses ML data from MetaClean to predict the quality (Pass/Fail) of feature group data, and converts this to a session which can be reviewed with checkFeatures and used to remove unwanted feature groups by filter.

Value

A dataframe with the class predictions as well as the associated probabilities for each EIC as returned by the MetaClean::getPredicitons function. The dataframe has the four columns: EIC, Pred_Class, Pred_Prob_Pass, Pred_Prob_Fail.

Use of raw HRMS data

The raw data interface of patRoon is used by these functions to process HRMS (or IMS-HRMS) data. Please see its documentation for more information on the supported formats and available configuration options.

Note

The topMost and topMostByReplicate EIC parameters are ignored.

checkComponents: Some componentization algorithms (e.g. generateComponentsNontarget and generateComponentsTPs) may output components where the same feature group in a component is present multiple times, for instance, when multiple TPs are matched to the same feature group. If such a feature group is selected for removal, then all of its result in the component will be marked for removal.

getMCTrainData only uses session data for selected feature groups. Selected features for removal are ignored, as this is not supported by MetaClean.

References

Chetnik K, Petrick L, Pandey G (2020). “MetaClean: a machine learning-based classifier for reduced false positive peak detection in untargeted LC-MS metabolomics data.” Metabolomics, 16(11). doi:10.1007/s11306-020-01738-3.

Description

Parameters for clustering data such as mass spectra and mobilograms.

Details

Different functionality within patRoon uses clustering to group similar data together, for instance, to average mass spectra. A fast C++ backend based on Rcpp is used to perform the clustering.

The clustering can be configured by the method and window parameter. The following clustering methods are available:

• "hclust": uses hierarchical clustering to find similar data points (using hclust-cpp, which is based on the fastcluster package).

• "distance_point": uses a maximum distance between adjacent sorted data points to form clusters.

• "distance_mean": uses a maximum distance between the mean of the current cluster and the next sorted data point to form clusters.

• "bin": uses a simple binning approach to cluster data points.

The hclust method may give more accurate results and was the default prior to patRoon 3.0, but is more computationally demanding and generally unsuitable for IMS workflows due to excessive use of RAM. The distance_* methods are now default and suit most cases.

The window parameter defines the clustering tolerance. For method="hclust" this corresponds to the cluster height, for method="distance_*" methods this value sets the maximum distance between compared data and for method="bin" it corresponds to the bin width. Too small windows will prevent clustering close data points (e.g. resulting in split mass peaks in averaged spectra), whereas too big windows may cluster unrelated data points together (e.g. resulting in mass inaccuracies).

Source

Averaging of mass spectra was originally based on algorithms from the msProcess R package (now archived on CRAN).

References

Eddelbuettel D (2013). Seamless R and C++ Integration with Rcpp. Springer, New York. doi:10.1007/978-1-4614-6868-4. ISBN 978-1-4614-6867-7.

Eddelbuettel D, Balamuta J (2018). “Extending R with C++: A Brief Introduction to Rcpp.” The American Statistician, 72(1), 28-36. doi:10.1080/00031305.2017.1375990.

Eddelbuettel D, François R (2011). “Rcpp: Seamless R and C++ Integration.” Journal of Statistical Software, 40(8), 1–18. doi:10.18637/jss.v040.i08.

Eddelbuettel D, Francois R, Allaire J, Ushey K, Kou Q, Russell N, Ucar I, Bates D, Chambers J (2026). Rcpp: Seamless R and C++ Integration. R package version 1.1.1-1.1, https://www.rcpp.org.

Müllner D (2013). “fastcluster: Fast Hierarchical, Agglomerative Clustering Routines for R and Python.” Journal of Statistical Software, 53(9), 1–18. doi:10.18637/jss.v053.i09.

Description

Contains data for feature groups that are related in some way. These components commonly include adducts, isotopes and homologues.

Usage

componentTable(obj)

componentInfo(obj)

findFGroup(obj, fGroup)

expandForIMS(obj, ...)

## S4 method for signature 'components'
componentTable(obj)

## S4 method for signature 'components'
componentInfo(obj)

## S4 method for signature 'components'
groupNames(obj)

## S4 method for signature 'components'
length(x)

## S4 method for signature 'components'
names(x)

## S4 method for signature 'components'
show(object)

## S4 method for signature 'components,ANY,ANY,missing'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'components,ANY,ANY'
x[[i, j]]

## S4 method for signature 'components'
x$name

## S4 method for signature 'components'
delete(obj, i = NULL, j = NULL, ...)

## S4 method for signature 'components'
as.data.table(x)

## S4 method for signature 'components'
expandForIMS(obj, fGroups)

## S4 method for signature 'components'
filter(
  obj,
  size = NULL,
  adducts = NULL,
  isotopes = NULL,
  rtIncrement = NULL,
  mzIncrement = NULL,
  checkComponentsSession = NULL,
  negate = FALSE,
  verbose = TRUE
)

## S4 method for signature 'components'
findFGroup(obj, fGroup)

## S4 method for signature 'components'
plotSpectrum(obj, index, markFGroup = NULL, xlim = NULL, ylim = NULL, ...)

## S4 method for signature 'components'
plotChroms(obj, index, fGroups, EICParams = getDefEICParams(window = 5), ...)

## S4 method for signature 'components'
consensus(obj, ...)

## S4 method for signature 'componentsCamera'
expandForIMS(obj, ...)

## S4 method for signature 'componentsFeatures'
show(object)

## S4 method for signature 'componentsCliqueMS'
expandForIMS(obj, ...)

## S4 method for signature 'componentsSet'
show(object)

## S4 method for signature 'componentsSet,ANY,ANY,missing'
x[i, j, ..., sets = NULL, drop = TRUE]

## S4 method for signature 'componentsSet'
filter(obj, ..., negate = FALSE, sets = NULL)

## S4 method for signature 'componentsSet'
delete(obj, i = NULL, j = NULL, ...)

## S4 method for signature 'componentsSet'
consensus(obj, ...)

## S4 method for signature 'componentsSet'
expandForIMS(obj, fGroups)

## S4 method for signature 'componentsSet'
unset(obj, set)

## S4 method for signature 'componentsNT'
expandForIMS(obj, ...)

## S4 method for signature 'componentsNTSet'
expandForIMS(obj, ...)

## S4 method for signature 'componentsOpenMS'
expandForIMS(obj, ...)

## S4 method for signature 'componentsRC'
expandForIMS(obj, ...)

Arguments

Details

components objects are obtained from generateComponents.

Value

delete returns the object for which the specified data was removed.

consensus returns a components object that is produced by merging multiple specified components objects.

Methods (by generic)

• componentTable(components): Accessor method for the components slot of a components class. Each component is stored as a data.table.

• componentInfo(components): Accessor method for the componentInfo slot of a components class.

• groupNames(components): returns a character vector with the names of the feature groups for which data is present in this object.

• length(components): Obtain total number of components.

• names(components): Obtain the names of all components.

• show(components): Show summary information for this object.

• x[i: Subset on components/feature groups.

• x[[i: Extracts a component table, optionally filtered by a feature group.

• $: Extracts a component table by component name.

• delete(components): Completely deletes specified (parts of) components.

• as.data.table(components): Returns all component data in a table.

• expandForIMS(components): Expands the components data for IMS feature groups. See the ⁠IMS expansion⁠ section below.

• filter(components): Provides rule based filtering for components.

• findFGroup(components): Returns the component id(s) to which a feature group belongs.

• plotSpectrum(components): Plot a pseudo mass spectrum for a single component.

• plotChroms(components): Plot an extracted ion chromatogram (EIC) for all feature groups within a single component.

• consensus(components): Generates a consensus from multiple components objects. At this point results are simply combined and no attempt is made to merge similar components.

Slots

components

List of all components in this object. Use the componentTable method for access.

componentInfo

A data.table containing general information for each component. Use the componentInfo method for access.

S4 class hierarchy

• workflowStep

  • components

    • componentsCamera

    • componentsFeatures

      • componentsCliqueMS

      • componentsOpenMS

    • componentsClust

      • componentsIntClust

      • componentsSpecClust

    • componentsSet

      • componentsNTSet

    • componentsUnset

    • componentsNT

      • componentsNTUnset

    • componentsRC

    • componentsTPs

IMS expansion

In IMS workflows with post mobility assignment (see assignMobilities), specifically when the assignment occurs after generation of the components, it may be desired to copy the results of the IMS precursors to the IMS feature groups. For instance, for components from intensity clusters or TPs one could assume that results for IMS feature groups will be largely the same as their IMS precursors. The expandForIMS method function is used to expand the original components object by adding in IMS feature groups with data copied from their IMS precursors.

Currently, only components generated with generateComponentsIntClust, generateComponentsSpecClust and generateComponentsTPs support this operation.

Sets workflows

The componentsSet class is applicable for sets workflows. This class is derived from components and therefore largely follows the same user interface.

The following methods are specifically defined for sets workflows:

• All the methods from base class workflowStepSet.

• unset Converts the object data for a specified set into a 'non-set' object (componentsUnset), which allows it to be used in 'regular' workflows. Only the components in the specified set are kept.

The following methods are changed or with new functionality:

• filter and the subset operator ([) Can be used to select components that are only present for selected sets.

Note

filter Applies only those filters for which a component has data available. For instance, filtering by adduct will only filter any results within a component if that component contains adduct information.

For plotChroms: The topMost and topMostByReplicate EIC parameters are ignored unless the components are from homologous series.

See Also

generateComponents

Description

This base class is derived from components and is used to store components resulting from hierarchical clustering information, for instance, generated by generateComponentsIntClust and generateComponentsSpecClust.

Usage

## S4 method for signature 'componentsClust'
delete(obj, ...)

## S4 method for signature 'componentsClust'
clusters(obj)

## S4 method for signature 'componentsClust'
cutClusters(obj)

## S4 method for signature 'componentsClust'
clusterProperties(obj)

## S4 method for signature 'componentsClust'
treeCut(obj, k = NULL, h = NULL)

## S4 method for signature 'componentsClust'
treeCutDynamic(obj, maxTreeHeight, deepSplit, minModuleSize)

## S4 method for signature 'componentsClust,missing'
plot(
  x,
  pal = "Paired",
  numericLabels = TRUE,
  colourBranches = length(x) < 50,
  showLegend = length(x) < 20,
  ...
)

## S4 method for signature 'componentsClust'
plotSilhouettes(obj, kSeq, pch = 16, type = "b", ...)

Arguments

Methods (by generic)

• clusters(componentsClust): Accessor method to the clust slot, which was generated by hclust.

• cutClusters(componentsClust): Accessor method to the cutClusters slot. Returns a vector with cluster membership for each candidate (format as cutree).

• clusterProperties(componentsClust): Returns a list with properties on how the clustering was performed.

• treeCut(componentsClust): Manually (re-)cut the dendrogram.

• treeCutDynamic(componentsClust): Automatically (re-)cut the dendrogram using the cutreeDynamicTree function from dynamicTreeCut.

• plot(x = componentsClust, y = missing): generates a dendrogram from a given cluster object and optionally highlights resulting branches when the cluster is cut.

• plotSilhouettes(componentsClust): Plots the average silhouette width when the clusters are cut by a sequence of k numbers. The k value with the highest value (marked in the plot) may be considered as the optimal number of clusters.

Slots

distm

Distance matrix that was used for clustering (obtained with daisy).

clust

Object returned by hclust.

cutClusters

A list with assigned clusters (same format as what cutree returns).

gInfo

The groupInfo of the feature groups object that was used.

properties

A list containing general properties and parameters used for clustering.

altered

Set to TRUE if the object was altered (e.g. filtered) after its creation.

IMS workflows

When components are re-made by treeCut or treeCutDynamic any expanded data should be re-added by calling expandForIMS.

S4 class hierarchy

• components

  • componentsClust

    • componentsIntClust

    • componentsSpecClust

Note

The intensity values for components (used by plotSpectrum) are set to a dummy value (1) as no single intensity value exists for this kind of components.

When the object is altered (e.g. by filtering or subsetting it), methods that need the original clustered data such as plotting methods do not work anymore and stop with an error.

References

Schollee JE, Bourgin M, von Gunten U, McArdell CS, Hollender J (2018). “Non-target screening to trace ozonation transformation products in a wastewater treatment train including different post-treatments.” Water Research, 142, 267–278. doi:10.1016/j.watres.2018.05.045.

See Also

components and generateComponents

Description

This class is derived from componentsClust and is used to store hierarchical clustering information from intensity profiles of feature groups.

Usage

plotHeatMap(obj, ...)

## S4 method for signature 'componentsIntClust'
plotHeatMap(
  obj,
  interactive = FALSE,
  col = NULL,
  margins = c(6, 2),
  cexCol = 1,
  ...
)

## S4 method for signature 'componentsIntClust'
plotInt(
  obj,
  index,
  pch = 20,
  type = "b",
  lty = 3,
  col = NULL,
  plotArgs = NULL,
  linesArgs = NULL
)

Arguments

Details

Objects from this class are generated by generateComponentsIntClust

Value

plotHeatMap returns the same as heatmap.2 or heatmaply.

Methods (by generic)

• plotHeatMap(componentsIntClust): draws a heatmap using the heatmap.2 or heatmaply function.

• plotInt(componentsIntClust): makes a plot for all (normalized) intensity profiles of the feature groups within a given cluster.

Slots

clusterm

Numeric matrix with normalized feature group intensities that was used for clustering.

S4 class hierarchy

• componentsClust

  • componentsIntClust

Note

When the object is altered (e.g. by filtering or subsetting it), methods that need the original clustered data such as plotting methods do not work anymore and stop with an error.

See Also

componentsClust for other relevant methods and generateComponents

Description

This class is derived from components and is used to store results from unsupervised homolog detection with the nontarget package.

Usage

## S4 method for signature 'componentsNT'
plotGraph(obj, onlyLinked = TRUE, width = NULL, height = NULL)

## S4 method for signature 'componentsNTSet'
plotGraph(obj, onlyLinked = TRUE, set, ...)

## S4 method for signature 'componentsNTSet'
unset(obj, set)

Arguments

Details

Objects from this class are generated by generateComponentsNontarget

Value

plotGraph returns the result of visNetwork.

Methods (by generic)

• plotGraph(componentsNT): Plots an interactive network graph for linked homologous series (i.e. series with (partial) overlap which could not be merged). The resulting graph can be browsed interactively and allows quick inspection of series which may be related. The graph is constructed with the igraph package and rendered with visNetwork.

Slots

homol

A list with homol objects for each replicate as returned by homol.search

Sets workflows

The componentsNTSet class is applicable for sets workflows. This class is derived from componentsNT and therefore largely follows the same user interface.

The following methods are specifically defined for sets workflows:

• All the methods from base class workflowStepSet.

• unset Converts the object data for a specified set into a 'non-set' object (componentsNTUnset), which allows it to be used in 'regular' workflows. Only the components in the specified set are kept. Furthermore, the component names are restored to non-set specific names (see generateComponents for more details).

The following methods are changed or with new functionality:

• plotGraph Currently can only create graph networks from one set (specified by the set argument).

Note that the componentsNTSet class does not have a homol slot. Instead, the setObjects method can be used to access this data for a specific set.

References

Loos M, Singer H (2017). “Nontargeted homologue series extraction from hyphenated high resolution mass spectrometry data.” Journal of Cheminformatics, 9(1). doi:10.1186/s13321-017-0197-z.

Loos M, Gerber C, Corona F, Hollender J, Singer H (2015). “Accelerated Isotope Fine Structure Calculation Using Pruned Transition Trees.” Analytical Chemistry, 87(11), 5738-5744. https://pubs.acs.org/doi/abs/10.1021/acs.analchem.5b00941.

Antonov M, Csárdi G, Horvát S, Müller K, Nepusz T, Noom D, Salmon M, Traag V, Welles BF, Zanini F (2023). “igraph enables fast and robust network analysis across programming languages.” arXiv preprint arXiv:2311.10260. doi:10.48550/arXiv.2311.10260.

Csárdi G, Nepusz T (2006). “The igraph software package for complex network research.” InterJournal, Complex Systems, 1695. https://igraph.org.

Csárdi G, Nepusz T, Traag V, Horvát S, Zanini F, Noom D, Müller K, Schoch D, Salmon M (2026). igraph: Network Analysis and Visualization in R. doi:10.5281/zenodo.7682609. R package version 2.3.1, https://CRAN.R-project.org/package=igraph.

See Also

components and generateComponents

Description

This class is derived from componentsClust and is used to store components from feature groups that were clustered based on their MS/MS similarities.

Details

Objects from this class are generated by generateComponentsSpecClust

S4 class hierarchy

• componentsClust

  • componentsSpecClust

Note

When the object is altered (e.g. by filtering or subsetting it), methods that need the original clustered data such as plotting methods do not work anymore and stop with an error.

See Also

componentsClust for other relevant methods and generateComponents

Description

This class is derived from components and is used to store components that result from linking feature groups that are (predicted to be) parents with feature groups that (are predicted to be) transformation products. For more details, see generateComponentsTPs.

Usage

## S4 method for signature 'componentsTPs'
as.data.table(x, candidates = FALSE)

## S4 method for signature 'componentsTPs'
filter(
  obj,
  ...,
  retDirMatch = FALSE,
  minSpecSim = NULL,
  minSpecSimPrec = NULL,
  minSpecSimBoth = NULL,
  minTotFragMatches = NULL,
  minTotNLMatches = NULL,
  minFragMatches = NULL,
  minNLMatches = NULL,
  formulas = NULL,
  verbose = TRUE,
  negate = FALSE
)

## S4 method for signature 'componentsTPs'
plotGraph(obj, onlyLinked = TRUE, width = NULL, height = NULL)

Arguments

Value

filter returns a filtered componentsTPs object.

plotGraph returns the result of visNetwork.

Methods (by generic)

• as.data.table(componentsTPs): Returns all component data as a data.table.

• filter(componentsTPs): Provides various rule based filtering options to clean and prioritize TP data.

• plotGraph(componentsTPs): Plots an interactive network graph for linked components. Components are linked with each other if one or more transformation products overlap. The graph is constructed with the igraph package and rendered with visNetwork.

Slots

fromTPs

A logical that is TRUE when the componentization was performed with transformationProducts data (i.e. the TPs argument was not NULL).

parentsFromScreening

A logical that is TRUE when the parents were obtained from screening data.

TPsFromScreening

A logical that is TRUE when the TPs were obtained from screening data.

S4 class hierarchy

• components

  • componentsTPs

Note

The intensity values for components (used by plotSpectrum) are set to a dummy value (1) as no single intensity value exists for this kind of components.

References

Antonov M, Csárdi G, Horvát S, Müller K, Nepusz T, Noom D, Salmon M, Traag V, Welles BF, Zanini F (2023). “igraph enables fast and robust network analysis across programming languages.” arXiv preprint arXiv:2311.10260. doi:10.48550/arXiv.2311.10260.

Csárdi G, Nepusz T (2006). “The igraph software package for complex network research.” InterJournal, Complex Systems, 1695. https://igraph.org.

Csárdi G, Nepusz T, Traag V, Horvát S, Zanini F, Noom D, Müller K, Schoch D, Salmon M (2026). igraph: Network Analysis and Visualization in R. doi:10.5281/zenodo.7682609. R package version 2.3.1, https://CRAN.R-project.org/package=igraph.

See Also

components for other relevant methods and generateComponents

Description

Contains data for compound annotations for feature groups.

Usage

addFormulaScoring(
  compounds,
  formulas,
  updateScore = FALSE,
  formulaScoreWeight = 1
)

## S4 method for signature 'compounds'
defaultExclNormScores(obj)

## S4 method for signature 'compounds'
show(object)

## S4 method for signature 'compounds'
identifiers(compounds)

## S4 method for signature 'compounds'
filter(
  obj,
  minExplainedPeaks = NULL,
  minScore = NULL,
  minFragScore = NULL,
  minFormulaScore = NULL,
  scoreLimits = NULL,
  IMSRangeParams = NULL,
  IMSMatchParams = NULL,
  ...
)

## S4 method for signature 'compounds'
addFormulaScoring(
  compounds,
  formulas,
  updateScore = FALSE,
  formulaScoreWeight = 1
)

## S4 method for signature 'compounds'
getMCS(obj, index, groupName)

## S4 method for signature 'compounds'
plotStructure(obj, index, groupName, width = 500, height = 500)

## S4 method for signature 'compounds'
plotScores(
  obj,
  index,
  groupName,
  normalizeScores = "max",
  excludeNormScores = defaultExclNormScores(obj),
  onlyUsed = TRUE
)

## S4 method for signature 'compounds'
annotatedPeakList(
  obj,
  index,
  groupName,
  MSPeakLists,
  formulas = NULL,
  onlyAnnotated = FALSE
)

## S4 method for signature 'compounds'
plotSpectrum(
  obj,
  index,
  groupName,
  MSPeakLists,
  formulas = NULL,
  plotStruct = FALSE,
  title = NULL,
  normalized = "multiple",
  specSimParams = getDefSpecSimParams(),
  mincex = 0.9,
  xlim = NULL,
  ylim = NULL,
  showLegend = TRUE,
  maxMolSize = c(0.2, 0.4),
  molRes = c(100, 100),
  ...
)

## S4 method for signature 'compounds'
consensus(
  obj,
  ...,
  MSPeakLists,
  specSimParams = getDefSpecSimParams(removePrecursor = TRUE),
  absMinAbundance = NULL,
  relMinAbundance = NULL,
  uniqueFrom = NULL,
  uniqueOuter = FALSE,
  rankWeights = 1,
  labels = NULL
)

## S4 method for signature 'compoundsSet'
show(object)

## S4 method for signature 'compoundsSet'
delete(obj, i, j, ...)

## S4 method for signature 'compoundsSet,ANY,missing,missing'
x[i, j, ..., sets = NULL, updateConsensus = FALSE, drop = TRUE]

## S4 method for signature 'compoundsSet'
filter(obj, ..., sets = NULL, updateConsensus = FALSE, negate = FALSE)

## S4 method for signature 'compoundsSet'
plotSpectrum(
  obj,
  index,
  groupName,
  MSPeakLists,
  formulas = NULL,
  plotStruct = FALSE,
  title = NULL,
  normalized = "multiple",
  specSimParams = getDefSpecSimParams(),
  mincex = 0.9,
  xlim = NULL,
  ylim = NULL,
  showLegend = TRUE,
  maxMolSize = c(0.2, 0.4),
  molRes = c(100, 100),
  perSet = TRUE,
  mirror = TRUE,
  ...
)

## S4 method for signature 'compoundsSet'
addFormulaScoring(
  compounds,
  formulas,
  updateScore = FALSE,
  formulaScoreWeight = 1
)

## S4 method for signature 'compoundsSet'
annotatedPeakList(obj, index, groupName, MSPeakLists, formulas = NULL, ...)

## S4 method for signature 'compoundsSet'
consensus(
  obj,
  ...,
  MSPeakLists,
  specSimParams = getDefSpecSimParams(removePrecursor = TRUE),
  absMinAbundance = NULL,
  relMinAbundance = NULL,
  uniqueFrom = NULL,
  uniqueOuter = FALSE,
  rankWeights = 1,
  labels = NULL,
  filterSets = FALSE,
  setThreshold = 0,
  setThresholdAnn = 0,
  setAvgSpecificScores = FALSE
)

## S4 method for signature 'compoundsSet'
unset(obj, set)

## S4 method for signature 'compoundsConsensusSet'
unset(obj, set)

## S4 method for signature 'compoundsSIRIUS'
delete(obj, i = NULL, j = NULL, ...)

Arguments

Details

compounds objects are obtained from compound generators. This class is derived from the featureAnnotations class, please see its documentation for more methods and other details.

Value

addFormulaScoring returns a compounds object updated with formula scoring.

getMCS returns an rcdk molecule object (IAtomContainer).

consensus returns a compounds object that is produced by merging multiple specified compounds objects.

Methods (by generic)

• defaultExclNormScores(compounds): Returns default scorings that are excluded from normalization.

• show(compounds): Show summary information for this object.

• identifiers(compounds): Returns a list containing for each feature group a character vector with database identifiers for all candidate compounds. The list is named by feature group names, and is typically used with the identifiers option of generateCompoundsMetFrag.

• filter(compounds): Provides rule based filtering for generated compounds. Useful to eliminate unlikely candidates and speed up further processing. Also see the featureAnnotations method.

• addFormulaScoring(compounds): Adds formula ranking data from a formulas object as an extra compound candidate scoring (formulaScore column). The formula score for each compound candidate is between ‘⁠0-1⁠’, where zero means no match with any formula candidates, and one means that the compound candidate's formula is the highest ranked.

• getMCS(compounds): Calculates the maximum common substructure (MCS) for two or more candidate structures for a feature group. This method uses the get.mcs function from rcdk.

• plotStructure(compounds): Plots a structure of a candidate compound using the rcdk package. If multiple candidates are specified (i.e. by specifying a vector for index) then the maximum common substructure (MCS) of the selected candidates is drawn.

• plotScores(compounds): Plots a barplot with scoring of a candidate compound.

• annotatedPeakList(compounds): Returns an MS/MS peak list annotated with data from a given candidate compound for a feature group.

• plotSpectrum(compounds): Plots an annotated spectrum for a given candidate compound for a feature group. Two spectra can be compared by specifying a two-sized vector for the index and groupName arguments.

• consensus(compounds): Generates a consensus of results from multiple objects. In order to rank the consensus candidates, first each of the candidates are scored based on their original ranking (the scores are normalized and the highest ranked candidate gets value ‘⁠1⁠’). The (weighted) mean is then calculated for all scorings of each candidate to derive the final ranking (if an object lacks the candidate its score will be ‘⁠0⁠’). The original rankings for each object is stored in the rank columns.

Slots

MS2QuantMeta

Metadata from MS2Quant filled in by predictRespFactors.

(sets workflow) A named list with the metadata stored for each set.

setThreshold,setThresholdAnn,setAvgSpecificScores

(sets workflow) A copy of the equally named arguments that were passed when this object was created by generateCompounds.

origFGNames

(sets workflow) The original (order of) names of the featureGroups object that was used to create this object.

IMS workflows

In IMS workflows, reference IMS data to candidates can be assigned with assignMobilities method function. Furthermore, CCS values may be assigned directly to candidates with generateCompounds if database="pubchemlite".

This data can be used to prioritize candidates with the IMSMatchParams and IMSRangeParams filters.

S4 class hierarchy

• featureAnnotations

  • compounds

    • compoundsConsensus

    • compoundsMF

    • compoundsSet

      • compoundsConsensusSet

    • compoundsUnset

    • compoundsSIRIUS

Source

Subscripting of formulae for plots generated by plotSpectrum is based on the chemistry2expression function from the ReSOLUTION package.

Sets workflows

The compoundsSet class is applicable for sets workflows. This class is derived from compounds and therefore largely follows the same user interface.

The following methods are specifically defined for sets workflows:

• All the methods from base class workflowStepSet.

• unset Converts the object data for a specified set into a 'non-set' object (compoundsUnset), which allows it to be used in 'regular' workflows. Only the annotation results that are present in the specified set are kept (based on the set consensus, see below for implications).

The following methods are changed or with new functionality:

• filter and the subset operator ([) Can be used to select data that is only present for selected sets. Depending on the updateConsenus, both either operate on set consensus or original data (see below for implications).

• annotatedPeakList Returns a combined annotation table with all sets.

• plotSpectrum Is able to highlight set specific mass peaks (perSet and mirror arguments).

• consensus Creates the algorithm consensus based on the original annotation data (see below for implications). Then, like the sets workflow method for generateCompounds, a consensus is made for all sets, which can be controlled with the setThreshold and setThresholdAnn arguments. The candidate coverage among the different algorithms is calculated for each set (e.g. coverage-positive column) and for all sets (coverage column), which is based on the presence of a candidate in all the algorithms from all sets data. The consensus method for sets workflow data supports the filterSets argument. This controls how the algorithm consensus abundance filters (absMinAbundance/relMinAbundance) are applied: if filterSets=TRUE then the minimum of all coverage set specific columns is used to obtain the algorithm abundance. Otherwise the overall coverage column is used. For instance, consider a consensus object to be generated from two objects generated by different algorithms (e.g. SIRIUS and MetFrag), which both have a positive and negative set. Then, if a candidate occurs with both algorithms for the positive mode set, but only with the first algorithm in the negative mode set, relMinAbundance=1 will remove the candidate if filterSets=TRUE (because the minimum relative algorithm abundance is ‘⁠0.5⁠’), while filterSets=FALSE will not remove the candidate (because based on all sets data the candidate occurs in both algorithms).

• addFormulaScoring Adds the formula scorings to the original data and re-creates the annotation set consensus (see below for implications).

Two types of annotation data are stored in a compoundsSet object:

1. Annotations that are produced from a consensus between set results (see generateCompounds).

2. The 'original' annotation data per set, prior to when the set consensus was made. This includes candidates that were filtered out because of the thresholds set by setThreshold and setThresholdAnn. However, when filter or subsetting ([) operations are performed, the original data is also updated.

In most cases the first data is used. However, in a few cases the original annotation data is used (as indicated above), for instance, to re-create the set consensus. It is important to realize that the original annotation data may have additional candidates, and a newly created set consensus may therefore have 'new' candidates. For instance, when the object consists of the sets "positive" and "negative" and setThreshold=1 was used to create it, then compounds[, sets = "positive", updateConsensus = TRUE] may now have additional candidates, i.e. those that were not present in the "negative" set and were previously removed due to the consensus threshold filter.

Note

The values ranges in the scoreLimits slot, which are used for normalization of scores, are based on the original scorings when the compounds were generated (prior to employing the topMost filter to generateCompounds).

References

Guha R (2007). “Chemical Informatics Functionality in R.” Journal of Statistical Software, 18(6).

See Also

The featureAnnotations base class for more relevant methods and generateCompounds.

Description

Perform hierarchical clustering of structure candidates based on chemical similarity and obtain overall structural information based on the maximum common structure (MCS).

Usage

makeHCluster(obj, method = "complete", ...)

## S4 method for signature 'compounds'
makeHCluster(
  obj,
  method,
  fpType = "extended",
  fpSimMethod = "tanimoto",
  maxTreeHeight = 1,
  deepSplit = TRUE,
  minModuleSize = 1
)

Arguments

Details

Often many possible chemical structure candidates are found for each feature group when performing compound annotation. Therefore, it may be useful to obtain an overview of their general structural properties. One strategy is to perform hierarchical clustering based on their chemical (dis)similarity, for instance, using the Tanimoto score. The resulting clusters can then be characterized by evaluating their maximum common substructure (MCS).

makeHCluster performs hierarchical clustering of all structure candidates for each feature group within a compounds object. The resulting dendrograms are automatically cut using the cutreeDynamicTree function from the dynamicTreeCut package. The returned compoundsCluster object can then be used, for instance, for plotting dendrograms and MCS structures and manually re-cutting specific clusters.

Value

makeHCluster returns an compoundsCluster object.

Source

The methodology applied here has been largely derived from ‘chemclust.R’ from the metfRag package and the package vignette of rcdk.

References

Guha R (2007). “Chemical Informatics Functionality in R.” Journal of Statistical Software, 18(6).

See Also

compoundsCluster

Description

Objects from this class are used to store hierarchical clustering data of candidate structures within compounds objects.

Usage

## S4 method for signature 'compoundsCluster'
clusters(obj)

## S4 method for signature 'compoundsCluster'
cutClusters(obj)

## S4 method for signature 'compoundsCluster'
clusterProperties(obj)

## S4 method for signature 'compoundsCluster'
groupNames(obj)

## S4 method for signature 'compoundsCluster'
length(x)

## S4 method for signature 'compoundsCluster'
lengths(x, use.names = TRUE)

## S4 method for signature 'compoundsCluster'
show(object)

## S4 method for signature 'compoundsCluster,ANY,missing,missing'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'compoundsCluster'
treeCut(obj, k = NULL, h = NULL, groupName)

## S4 method for signature 'compoundsCluster'
treeCutDynamic(obj, maxTreeHeight, deepSplit, minModuleSize, groupName)

## S4 method for signature 'compoundsCluster,missing'
plot(
  x,
  ...,
  groupName,
  pal = "Paired",
  colourBranches = lengths(x)[groupName] < 50,
  showLegend = lengths(x)[groupName] < 20
)

## S4 method for signature 'compoundsCluster'
getMCS(obj, groupName, cluster)

## S4 method for signature 'compoundsCluster'
plotStructure(
  obj,
  groupName,
  cluster,
  width = 500,
  height = 500,
  withTitle = TRUE
)

## S4 method for signature 'compoundsCluster'
plotSilhouettes(obj, kSeq, groupName, pch = 16, type = "b", ...)

Arguments

Details

Objects from this type are returned by the compounds method for makeHCluster.

Value

cutTree and cutTreeDynamic return the modified compoundsCluster object.

getMCS returns an rcdk molecule object (IAtomContainer).

Methods (by generic)

• clusters(compoundsCluster): Accessor method to the clusters slot. Returns a list that contains for each feature group an object as returned by hclust.

• cutClusters(compoundsCluster): Accessor method to the cutClusters slot. Returns a list that contains for each feature group a vector with cluster membership for each candidate (format as cutree).

• clusterProperties(compoundsCluster): Returns a list with properties on how the clustering was performed.

• groupNames(compoundsCluster): returns a character vector with the names of the feature groups for which data is present in this object.

• length(compoundsCluster): Returns the total number of clusters.

• lengths(compoundsCluster): Returns a vector with the number of clusters per feature group.

• show(compoundsCluster): Show summary information for this object.

• x[i: Subset on feature groups.

• treeCut(compoundsCluster): Manually (re-)cut a dendrogram that was generated for a feature group.

• treeCutDynamic(compoundsCluster): Automatically (re-)cut a dendrogram that was generated for a feature group using the cutreeDynamicTree function from dynamicTreeCut.

• plot(x = compoundsCluster, y = missing): Plot the dendrogram for clustered compounds of a feature group. Clusters are highlighted using dendextend.

• getMCS(compoundsCluster): Calculates the maximum common substructure (MCS) for all candidate structures within a specified cluster. This method uses the get.mcs function from rcdk.

• plotStructure(compoundsCluster): Plots the maximum common substructure (MCS) for all candidate structures within a specified cluster.

• plotSilhouettes(compoundsCluster): Plots the average silhouette width when the clusters are cut by a sequence of k numbers. The k value with the highest value (marked in the plot) may be considered as the optimal number of clusters.

Slots

clusters

A list with hclust objects for each feature group.

dists

A list with distance matrices for each feature group.

SMILES

A list containing a vector with SMILES for all candidate structures per feature group.

cutClusters

A list with assigned clusters for all candidates per feature group (same format as what cutree returns).

properties

A list containing general properties and parameters used for clustering.

Description

Returns an overview of scorings may be applied to rank candidate compounds.

Usage

compoundScorings(
  algorithm = NULL,
  database = NULL,
  includeSuspectLists = TRUE,
  onlyDefault = FALSE,
  includeNoDB = TRUE
)

Arguments

Value

A data.frame with information on which scoring terms are used, what their algorithm specific name is and other information such as to which database they apply and short remarks.

See Also

generateCompounds

Description

This class is derived from compounds and contains additional specific MetFrag data.

Usage

settings(compoundsMF)

## S4 method for signature 'compoundsMF'
settings(compoundsMF)

Arguments

Details

Objects from this class are generated by generateCompoundsMetFrag

Methods (by generic)

• settings(compoundsMF): Accessor method for the settings slot.

Slots

settings

A list with all general configuration settings passed to MetFrag. Feature specific items (e.g. spectra and precursor masses) are not contained in this list.

S4 class hierarchy

• compounds

  • compoundsMF

References

Ruttkies C, Schymanski EL, Wolf S, Hollender J, Neumann S (2016). “MetFrag relaunched: incorporating strategies beyond in silico fragmentation.” Journal of Cheminformatics, 8(1). doi:10.1186/s13321-016-0115-9.

See Also

compounds and generateCompoundsMetFrag

Description

This class is derived from compounds and contains additional specific SIRIUS data.

Details

Objects from this class are generated by generateCompoundsSIRIUS

Slots

fingerprints

A list with for each feature group result a data.table containing fingerprints obtained with CSI:FingerID.

S4 class hierarchy

• compounds

  • compoundsSIRIUS

References

Duhrkop K, Fleischauer M, Ludwig M, Aksenov AA, Melnik AV, Meusel M, Dorrestein PC, Rousu J, Bocker S (2019). “SIRIUS 4: a rapid tool for turning tandem mass spectra into metabolite structure information.” Nature Methods, 16(4), 299–302. doi:10.1038/s41592-019-0344-8.

Duhrkop K, Bocker S (2015). “Fragmentation Trees Reloaded.” In Przytycka TM (ed.), Research in Computational Molecular Biology, 65–79. ISBN 978-3-319-16706-0.

Duhrkop K, Shen H, Meusel M, Rousu J, Bocker S (2015). “Searching molecular structure databases with tandem mass spectra using CSI:FingerID.” Proceedings of the National Academy of Sciences, 112(41), 12580–12585. doi:10.1073/pnas.1509788112.

Bocker S, Letzel MC, Liptak Z, Pervukhin A (2008). “SIRIUS: decomposing isotope patterns for metabolite identification.” Bioinformatics, 25(2), 218–224. doi:10.1093/bioinformatics/btn603.

See Also

compounds and generateCompoundsSIRIUS

Description

Returns the default adducts and their probabilities when the OpenMS algorithm is used for componentization.

Usage

defaultOpenMSAdducts(ionization)

Arguments

Details

See the potentialAdducts argument of generateComponentsOpenMS for more details.

Description

Parameters for creation of extracted ion chromatograms and mobilograms.

Usage

getDefEICParams(...)

getDefEIMParams(..., IMS = getLimIMS())

Arguments

Details

The following parameters exist to configure the creation of extracted ion chromatograms (EICs) and extracted ion mobilograms (EIMs):

• window A value that is subtracted or added to the minimum and maximum retention time (EICs) or mobility (EIMs) of the feature. Thus, setting this value to ‘⁠>0⁠’ will 'zoom out' on the x-axis of a chromatogram or mobilogram. Defaults to defaultLim("retention", "wide") (EICs) or defaultLim("mobility", "wide") (EIMs) (see limits).

• topMost Only create EICs/EIMs for this number of top most intense features. If NULL then EICs/EIMs are created for all features.

• topMostByReplicate If set to TRUE and topMost is set: only create EICs/EIMs for the top most features in each replicate. For instance, when topMost=1 and topMostByReplicate=TRUE, then only the most intense feature of each replicate is considered.

• onlyPresent If TRUE then EICs/EIMs are created only for analyses in which a feature was detected, if onlyPresent=FALSE then data is generated for all analyses. The latter is handy to evaluate if a peak was 'missed' during peak detection or removed during e.g. filtering.

• mzExpMobWindow (IMS workflow) Additional m/z tolerance on top of the feature limits. This is for IMS workflows where features were detected from centroided LC-MS like data, while EICs/EIMs are generated from raw IMS data. In this case the feature m/z limits were derived from centroided data, which typically has smaller m/z deviations across scans compared to IMS data. The mzExpMobWindow parameter sets an additional m/z tolerance to specifically handle this case. Defaults to defaultLim("mz", "default") (see limits).

• minIntensityIMS (IMS workflow) Raw intensity threshold for IMS data. This is primarily intended to speed up raw data processing.

if onlyPresent=FALSE then the following parameters are also relevant:

• mzExpWindow,mobExpWindow To create EICs or EIMs for analyses in which no feature was found, the m/z or mobility value is derived from the min/max values of all features in the feature group. The value of mzExpWindow and mobExpWindow further expands this window to allow a greater tolerance. Defaults to defaultLim("mz", "very_narrow") and defaultLim("mobility", "very_narrow") (see limits).

• setsAdductPos,setsAdductNeg (sets workflow) In sets workflows the adduct must be known to calculate the ionized m/z. If a feature is completely absent in a particular set then it follows no adduct annotations are available and the value of setsAdductPos (positive ionization data) or setsAdductNeg (negative ionization data) will be used instead.

The following additional parameters exist specifically for EICs (EICParams):

• gapFactor Bruker TIMS data (and maybe others?) seem to omit zero intensity scans, which will lead to time gaps between spectra and incorrect EICs. To determine a time gap, the gapFactor is multiplied with the median of time differences between scans. If a gap is detected, then appropriate zero intensity points are added to the EIC. Set to 0 to disable this.

The following additional parameters exist specifically for EIMs (EIMParams):

• maxRTWindow Maximum retention time window (seconds, +/- feature retention time) in which mobilograms are collected and averaged. Defaults to defaultLim("retention", "very_narrow") (see limits).

• smooth The smoothing method that is applied to the EIM. Can be "none" for no smoothing, "sg" for Savitzky-Golay (using signal)) or "ma" for centered moving average (same algorithm as used by findFeaturesPiek).

• smLength The smoothing length. If smooth="sg" then this is passed as the n argument to the signal::sgolayfilt function.

• sgOrder The smoothing order for Savitzky-Golay. Passed as the p argument to the signal::sgolayfilt function.

These parameters are passed as a named list as the EICParams or EIMParams argument to functions that work with EIC or EIM data. The getDefEICParams and getDefEIMParams functions generate such parameter list with defaults.

Description

Basic rule based filtering of feature groups.

Usage

replicateSubtract(fGroups, replicates, threshold = 0)

## S4 method for signature 'featureGroups'
filter(
  obj,
  absMinIntensity = NULL,
  relMinIntensity = NULL,
  preAbsMinIntensity = NULL,
  preRelMinIntensity = NULL,
  absMinMaxIntensity = NULL,
  relMinMaxIntensity = NULL,
  absMinAnalyses = NULL,
  relMinAnalyses = NULL,
  absMinReplicates = NULL,
  relMinReplicates = NULL,
  absMinFeatures = NULL,
  relMinFeatures = NULL,
  absMinReplicateAbundance = NULL,
  relMinReplicateAbundance = NULL,
  absMinConc = NULL,
  relMinConc = NULL,
  absMaxTox = NULL,
  relMaxTox = NULL,
  absMinConcTox = NULL,
  relMinConcTox = NULL,
  maxReplicateIntRSD = NULL,
  blankThreshold = NULL,
  retentionRange = NULL,
  mzRange = NULL,
  mzDefectRange = NULL,
  chromWidthRange = NULL,
  featQualityRange = NULL,
  groupQualityRange = NULL,
  replicates = NULL,
  IMS = NULL,
  withIMSPrecursor = FALSE,
  IMSRangeParams = NULL,
  results = NULL,
  removeBlanks = FALSE,
  removeISTDs = FALSE,
  checkFeaturesSession = NULL,
  predAggrParams = getDefPredAggrParams(),
  removeNA = FALSE,
  negate = FALSE,
  applyIMS = "both"
)

## S4 method for signature 'featureGroupsSet'
filter(
  obj,
  ...,
  negate = FALSE,
  applyIMS = "both",
  sets = NULL,
  absMinSets = NULL,
  relMinSets = NULL
)

## S4 method for signature 'featureGroups'
replicateSubtract(fGroups, replicates, threshold = 0)

Arguments

Details

filter performs common rule based filtering of feature groups such as blank subtraction, minimum intensity and minimum replicate abundance. Removing of features occurs by zeroing their intensity values. Furthermore, feature groups that are left completely empty (i.e. all intensities are zero) will be automatically removed.

replicateSubtract removes feature groups present in a given set of replicates (unless intensities are above a given threshold). The replicates that are subtracted will be removed.

Value

A filtered featureGroups object. Feature groups that are filtered away have their intensity set to zero. In case a feature group is not present in any of the analyses anymore it will be removed completely.

Sets workflows

The following methods are changed or with new functionality:

• filter has specific arguments to filter by (feature presence in) sets. See the argument descriptions.

• Important: the mzRange, mzDefectRange and IMSRangeParams filters use neutral feature masses, whereas non-sets workflows use m/z values. Hence, adjust accordingly to avoid (slightly) different results!

Filter order

When multiple arguments are specified to filter, multiple filters are applied in sequence. Since some of these filters may affect each other, choosing their order correctly may be important for effective data filtering. For instance, when an intensity filter removes features from blank analyses, a subsequent blank filter may not adequately perform blank subtraction. Similarly, when intensity and blank filters are executed after the replicate abundance filter it may be necessary to ensure minimum replicate abundance again as the intensity and blank filters may have removed some features within a replicate.

With this in mind, filters (if specified) occur in the following order:

1. Features/feature groups selected for removal by the session specified by checkFeaturesSession.

2. Pre-Intensity filters (i.e. preAbsMinIntensity and preRelMinIntensity).

3. Chromatography and mass filters (i.e retentionRange, mzRange, mzDefectRange, chromWidthRange, featQualityRange and groupQualityRange).

4. Replicate abundance filters (i.e. absMinReplicateAbundance, relMinReplicateAbundance and maxReplicateIntRSD).

5. Blank filter (i.e. blankThreshold).

6. Intensity filters (i.e. absMinIntensity and relMinIntensity).

7. Replicate abundance filters (2nd time, only if previous filters affected results).

8. Minimum-maximum intensity filters (i.e. absMinMaxIntensity and relMinMaxIntensity).

9. General abundance filters (i.e. absMinAnalyses, relMinAnalyses, absMinReplicates, relMinReplicates, absMinFeatures, relMinFeatures), absMinConc, relMinConc, absMaxTox and relMaxTox.

10. Replicate filter (i.e. replicates), results filter (i.e. results) and blank analyses / internal standard removal (i.e. removeBlanks=TRUE / removeISTDs=TRUE).

If another filtering order is desired then filter should be called multiple times with only one filter argument at a time.

See Also

featureGroups-class and groupFeatures

Description

Automatic optimization of feature finding and grouping parameters through Design of Experiments (DoE).

Usage

optimizeFeatureGrouping(
  features,
  algorithm,
  ...,
  templateParams = list(),
  paramRanges = list(),
  maxIterations = 50,
  maxModelDeviation = 0.1,
  parallel = TRUE
)

generateFGroupsOptPSet(algorithm, ...)

getDefFGroupsOptParamRanges(algorithm)

optimizeFeatureFinding(
  anaInfo,
  algorithm,
  ...,
  templateParams = list(),
  paramRanges = list(),
  isoIdent = if (algorithm == "openms") "OpenMS" else "IPO",
  checkPeakShape = "none",
  CAMERAOpts = list(),
  maxIterations = 50,
  maxModelDeviation = 0.1,
  parallel = TRUE
)

generateFeatureOptPSet(algorithm, ...)

getDefFeaturesOptParamRanges(algorithm, method = "centWave")

Arguments

Details

Many different parameters exist that may affect the output quality of feature finding and grouping. To avoid time consuming manual experimentation, functionality is provided to largely automate the optimization process. The methodology, which uses design of experiments (DoE), is based on the excellent Isotopologue Parameter Optimization (IPO) R package. The functionality of this package is directly integrated in patRoon. Some functionality was added or changed, however, the principle algorithm workings are nearly identical.

Compared to IPO, the following functionality was added or changed:

• The code was made more generic in order to include support for other feature finding/grouping algorithms (e.g. OpenMS, enviPick, XCMS3).

• The methodology of FeatureFinderMetabo (OpenMS) may be used to find isotopes.

• The maxModelDeviation parameter was added to potentially avoid suboptimal results (issue discussed here).

• The use of multiple 'parameter sets' (discussed below) which, for instance, allow optimizing qualitative paremeters more easily (see ⁠examples⁠).

• More consistent optimization code for feature finding/grouping.

• More consistent output using S4 classes (i.e. optimizationResult class).

• Parallelization is performed via the future package instead of BiocParallel. If this is enabled (parallel=TRUE) then any parallelization supported by the feature finding or grouping algorithm is disabled.

Value

The optimizeFeatureFinding and optimizeFeatureGrouping return their results in a optimizationResult object.

Parameter sets

Which parameters should be optimized is determined by a parameter set. A set is defined by a named list containing the minimum and maximum starting range for each parameter that should be tested. For instance, the set list(chromFWHM = c(5, 10), mzPPM = c(5, 15)) specifies that the chromFWHM and mzPPM parameters (used by OpenMS feature finding) should be optimized within a range of ‘⁠5⁠’-‘⁠10⁠’ and ‘⁠5⁠’-‘⁠15⁠’, respectively. Note that this range may be increased or decreased after a DoE iteration in order to find a better optimum. The absolute limits are controlled by the paramRanges function argument.

Multiple parameter sets may be specified (i.e. through the ... function argument). In this situation, the optimization algorithm is repeated for each set, and the final optimum is determined from the parameter set with the best response. The templateParams function argument may be useful in this case to define a template for each parameter set. Actual parameter sets are then constructed by joining each parameter set with the set specified for templateParams. When a parameter is defined in both a regular and template set, the parameter in the regular set takes precedence.

Parameters that should not be optimized but still need to be set for the feature finding/grouping functions should also be defined in a (template) parameter set. Which parameters should be optimized is determined whether its value is specified as a vector range or a single fixed value. For instance, when a set is defined as list(chromFWHM = c(5, 10), mzPPM = 5), only the chromFWHM parameter is optimized, whereas mzPPM is kept constant at ‘⁠5⁠’.

Using multiple parameter sets with differing fixed values allows optimization of qualitative values (see examples below).

The parameters specified in parameter sets are directly passed through the findFeatures or groupFeatures functions. Hence, grouping and retention time alignment parameters used by XCMS should (still) be set through the groupArgs and retcorArgs parameters.

NOTE: For XCMS3, which normally uses parameter classes for settings its options, the parameters must be defined in a named list like any other algorithm. The set parameters are then used passed to the constructor of the right parameter class object (e.g. CentWaveParam, ObiwarpParam). For grouping/alignment sets, these parameters need to be specified in nested lists called groupParams and retAlignParams, respectively (similar to groupArgs/retcorArgs for algorithm="xcms"). Finally, the underlying XCMS method to be used should be defined in the parameter set (i.e. by setting the method field for feature parameter sets and the groupMethod and retAlignMethod for grouping/aligning parameter sets). See the examples below for more details.

NOTE: Similar to IPO, the peakwidth and prefilter parameters for XCMS feature finding should be split in two different values:

• The minimum and maximum ranges for peakwidth are optimized by setting min_peakwidth and max_peakwidth, respectively.

• The k and I parameters contained in prefilter are split in prefilter and value_of_prefilter, respectively.

Similary, for KPIC2, the following parameters should be split:

• the width parameter (feature optimization) is optimized by specifying the min_width and max_width parameters.

• the tolerance and weight parameters (feature grouping optimization) are optimized by setting mz_tolerance/rt_tolerance and mz_weight/rt_weight parameters, respectively.

Functions

The optimizeFeatureFinding and optimizeFeatureGrouping are the functions to be used to optimize parameters for feature finding and grouping, respectively. These functions are analogous to optimizeXcmsSet and optimizeRetGroup from IPO.

The generateFeatureOptPSet and generateFGroupsOptPSet functions may be used to generate a parameter set for feature finding and grouping, respectively. Some algorithm dependent default parameter optimization ranges will be returned. These functions are analogous to getDefaultXcmsSetStartingParams and getDefaultRetGroupStartingParams from IPO. However, unlike their IPO counterparts, these functions will not output default fixed values. The generateFGroupsOptPSet will only generate defaults for density grouping if algorithm="xcms".

The getDefFeaturesOptParamRanges and getDefFGroupsOptParamRanges return the default absolute optimization parameter ranges for feature finding and grouping, respectively. These functions are useful if you want to set the paramRanges function argument.

Potential suboptimal results by optimization model

After each experiment iteration an optimimum parameter set is found by generating a model containing the tested parameters and their responses. Sometimes the actual response from the parameters derived from the model is actually signficantly lower than expected. When the response is lower than the maximum reponse found during the experiment, the parameters belonging to this experimental maximum may be choosen instead. The maxModelDeviation argument sets the maximum deviation in response between the modelled and experimental maxima. The value is relative: ‘⁠0⁠’ means that experimental values will always be favored when leading to improved responses, whereas 1 will effectively disable this procedure (and return to 'regular' IPO behaviour).

Source

The code and methodology is a direct adaptation from the IPO R package.

References

Libiseller G, Dvorzak M, Kleb U, Gander E, Eisenberg T, Madeo F, Neumann S, Trausinger G, Sinner F, Pieber T, Magnes C (2015). “IPO: a tool for automated optimization of XCMS parameters.” BMC Bioinformatics, 16(1). doi:10.1186/s12859-015-0562-8.

Examples

# example data from patRoonData package
dataDir <- patRoonData::exampleDataPath()
anaInfo <- generateAnalysisInfo(dataDir)
anaInfo <- anaInfo[1:2, ] # only focus on first two analyses (e.g. training set)

# optimize mzPPM and chromFWHM parameters
ftOpt <- optimizeFeatureFinding(anaInfo, "openms", list(mzPPM = c(5, 10), chromFWHM = c(4, 8)))

# optimize chromFWHM and isotopeFilteringModel (a qualitative parameter)
ftOpt2 <- optimizeFeatureFinding(anaInfo, "openms",
                                 list(isotopeFilteringModel = "metabolites (5% RMS)"),
                                 list(isotopeFilteringModel = "metabolites (2% RMS)"),
                                 templateParams = list(chromFWHM = c(4, 8)))

# perform grouping optimization with optimized features object
fgOpt <- optimizeFeatureGrouping(optimizedObject(ftOpt), "xcms",
                                 list(groupArgs = list(bw = c(22, 28)),
                                      retcorArgs = list(method = "obiwarp")))

# same, but using the XCMS3 interface
fgOpt2 <- optimizeFeatureGrouping(optimizedObject(ftOpt), "xcms3",
                                  list(groupMethod = "density", groupParams = list(bw = c(22, 28)),
                                       retAlignMethod = "obiwarp"))


# plot contour of first parameter set/DoE iteration
plot(ftOpt, paramSet = 1, DoEIteration = 1, type = "contour")

# generate parameter set with some predefined and custom parameters to be
# optimized.
pSet <- generateFeatureOptPSet("openms", chromSNR = c(3, 9),
                               useSmoothedInts = FALSE)

Description

Various plotting functions for feature group data.

Usage

plotMobilograms(obj, ...)

## S4 method for signature 'featureGroups,missing'
plot(
  x,
  groupBy = NULL,
  onlyUnique = FALSE,
  retMin = FALSE,
  showLegend = TRUE,
  IMS = "maybe",
  col = NULL,
  pch = NULL,
  ...
)

## S4 method for signature 'featureGroups'
plotInt(
  obj,
  average = FALSE,
  averageFunc = mean,
  areas = FALSE,
  normalized = FALSE,
  xBy = NULL,
  xNames = TRUE,
  groupBy = "fGroups",
  regression = FALSE,
  showLegend = FALSE,
  IMS = "maybe",
  pch = 20,
  type = if (regression) "p" else "b",
  lty = 3,
  xlim = NULL,
  ylim = NULL,
  col = NULL,
  plotArgs = NULL,
  linesArgs = NULL
)

## S4 method for signature 'featureGroups'
plotChord(
  obj,
  addSelfLinks = FALSE,
  addRetMzPlots = TRUE,
  aggregate = FALSE,
  groupBy = NULL,
  addIntraOuterGroupLinks = FALSE,
  IMS = "maybe",
  ...
)

## S4 method for signature 'featureGroups'
plotChroms(
  obj,
  analysis = analyses(obj),
  groupName = names(obj),
  retMin = FALSE,
  showPeakArea = FALSE,
  showFGroupRect = TRUE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  annotate = c("none", "ret", "mz", "mob"),
  intMax = "eic",
  EICParams = getDefEICParams(),
  showProgress = FALSE,
  IMS = "maybe",
  xlim = NULL,
  ylim = NULL,
  EICs = NULL,
  ...
)

## S4 method for signature 'featureGroups'
plotChroms3D(
  obj,
  analysis = analyses(obj),
  groupName = names(obj),
  dim3 = "mz",
  retMin = FALSE,
  showLimits = TRUE,
  rtWindow = defaultLim("retention", "medium"),
  mzWindow = defaultLim("mz", "medium"),
  mobWindow = defaultLim("mobility", "medium"),
  gridSize = 50,
  title = NULL,
  ...
)

## S4 method for signature 'featureGroupsSet'
plotChroms3D(obj, analysis = analyses(obj), ...)

## S4 method for signature 'featureGroups'
plotMobilograms(
  obj,
  analysis = analyses(obj),
  groupName = names(obj),
  showPeakArea = FALSE,
  showFGroupRect = TRUE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  annotate = c("none", "ret", "mz", "mob"),
  EIMParams = getDefEIMParams(),
  showProgress = FALSE,
  xlim = NULL,
  ylim = NULL,
  EIMs = NULL,
  ...
)

## S4 method for signature 'featureGroups'
plotVenn(obj, which = NULL, aggregate = TRUE, IMS = "maybe", ...)

## S4 method for signature 'featureGroups'
plotUpSet(
  obj,
  which = NULL,
  aggregate = TRUE,
  IMS = "maybe",
  nsets = NULL,
  nintersects = NA,
  ...
)

## S4 method for signature 'featureGroups'
plotVolcano(
  obj,
  FCParams,
  showLegend = TRUE,
  averageFunc = mean,
  normalized = FALSE,
  IMS = "maybe",
  col = NULL,
  pch = 19,
  ...
)

## S4 method for signature 'featureGroups'
plotGraph(obj, onlyPresent = TRUE, width = NULL, height = NULL)

## S4 method for signature 'featureGroupsSet'
plotGraph(obj, onlyPresent = TRUE, set, ...)

## S4 method for signature 'featureGroups'
plotTICs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'featureGroups'
plotBPCs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  groupBy = NULL,
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments