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.checkCentroided: If set to TRUE (the default) then the analyses files are verified to be centroided before loading any MS data. While these checks are optimized and cached, it may be useful to set this option to FALSE when processing very large numbers of analyses.

• 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.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. are installed in different subdirectories for each location inside this differs for each operating system

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

• patRoon.path.pngquant: The path of the pngquant binary that is used when optimizing ‘.png’ plots generated by reportHTML (with optimizePng set to TRUE). If the binary can be located through the PATH environment variable this option can remain empty. Note that some of the functionality of reportHTML only locates the binary through the PATH environment variable, hence, it is recommended to set up PATH instead.

• 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.

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)

Other contributors:

• Olaf Brock (ORCID) [contributor]

• Vittorio Albergamo (ORCID) [contributor]

• Andrea Brunner (ORCID) [contributor]

• Emma Schymanski (ORCID) [contributor]

• Bas van de Velde (ORCID) [contributor]

See Also

Useful links:

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

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

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,
  ...
)

## 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,
  specSimParams = getDefSpecSimParams(),
  mincex = 0.9,
  xlim = NULL,
  ylim = NULL,
  maxMolSize = c(0.2, 0.4),
  molRes = c(100, 100),
  ...
)

## S4 method for signature 'compounds'
consensus(
  obj,
  ...,
  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,
  specSimParams = getDefSpecSimParams(),
  mincex = 0.9,
  xlim = NULL,
  ylim = NULL,
  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,
  ...,
  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.

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.

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 6(18)

See Also

The featureAnnotations base class for more relevant methods and generateCompounds.

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(
  paths,
  groups = "",
  blanks = "",
  concs = NULL,
  norm_concs = NULL,
  formats = MSFileFormats()
)

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. This information should be in a data.frame, with the following columns:

• path the full path to the directory of the analysis.

• analysis the file name without extension. Must be unique, even if the path is different.

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

• blank all analyses within this replicate group are used by the featureGroups method of filter for blank subtraction. Multiple entries can be entered by separation with a comma.

• 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.

• 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.

Most workflows steps work with ‘mzXML’ and ‘mzML’ file formats. However, some algorithms only support support one format (e.g. findFeaturesOpenMS, findFeaturesEnviPick) or a proprietary format (findFeaturesBruker). To mix such algorithms in the same workflow, the analyses should be present in all required formats within the same directory as specified by the path column.

Each analysis should only be specified once in the analysis information, even if multiple file formats are available. The path and analysis columns are internally used by patRoon to automatically find the path of analysis files with the required format.

The group column is mandatory and needs to be non-empty for each analysis. The blank column should also be present, however, this may be empty ("") for analyses where no blank subtraction should occur. The conc column is only required when obtaining regression information is desired with the as.data.table method. Similarly, the norm_conc is only necessary for the normInts method.

generateAnalysisInfo is an utility function that automatically generates a data.frame with analysis information. It scans the directories specified from the paths argument for analyses, and uses this to automatically fill in the analysis and path columns. Furthermore, this function also correctly handles analyses which are available in multiple formats.

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

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,
  colourBy = c("none", "analyses", "rGroups"),
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'data.frame'
plotBPCs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  colourBy = c("none", "analyses", "rGroups"),
  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.

Author(s)

Ricardo Cunha, [email protected]

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 = 0.005,
  ctype = "EIC",
  mtype = "MS",
  polarity = "both",
  bgsubtr = FALSE,
  fragpath = "",
  name = NULL,
  hideDA = TRUE,
  close = FALSE,
  save = close
)

addAllDAEICs(
  fGroups,
  mzWindow = 0.005,
  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

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

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(),
  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 = 6,
  mzWindow = 0.002,
  overWrite = FALSE
)

## S4 method for signature 'featureGroups'
checkFeatures(
  fGroups,
  session = "checked-features.yml",
  EICParams = getDefEICParams(),
  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.

Note

The topMost and topMostByRGroup EIC parameters (EICParams) 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

Functionality to compare feature groups and make a consensus.

Usage

comparison(..., groupAlgo, groupArgs = list(rtalign = FALSE))

## S4 method for signature 'featureGroups'
comparison(..., groupAlgo, groupArgs = list(rtalign = FALSE))

## S4 method for signature 'featureGroupsComparison,missing'
plot(x, retMin = FALSE, ...)

## S4 method for signature 'featureGroupsComparison'
plotVenn(obj, which = NULL, ...)

## S4 method for signature 'featureGroupsComparison'
plotUpSet(obj, which = NULL, ...)

## S4 method for signature 'featureGroupsComparison'
plotChord(obj, addSelfLinks = FALSE, addRetMzPlots = TRUE, ...)

## S4 method for signature 'featureGroupsComparison'
consensus(
  obj,
  absMinAbundance = NULL,
  relMinAbundance = NULL,
  uniqueFrom = NULL,
  uniqueOuter = FALSE,
  verifyAnaInfo = TRUE
)

## S4 method for signature 'featureGroupsSet'
comparison(..., groupAlgo, groupArgs = list(rtalign = FALSE))

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

Arguments

Details

Feature groups objects originating from differing feature finding and/or grouping algorithms (or their parameters) may be compared to assess their output and generate a consensus.

The comparison method generates a featureGroupsComparison object from given feature groups objects, which in turn may be used for (visually) comparing presence of feature groups and generating a consensus. Internally, this function will collapse each feature groups object to pseudo features objects by averaging their retention times, m/z values and intensities, where each original feature groups object becomes an 'analysis'. All pseudo features are then grouped using regular feature grouping algorithms so that a comparison can be made.

plot generates an m/z vs retention time plot.

plotVenn plots a Venn diagram outlining unique and shared feature groups between up to five compared feature groups.

plotUpSet plots an UpSet diagram outlining unique and shared feature groups.

plotChord plots a chord diagram to visualize the distribution of feature groups.

consensus combines all compared feature groups and averages their retention, m/z and intensity data. Not yet supported for sets workflows.

Value

comparison returns a featureGroupsComparison object.

plotVenn (invisibly) returns a list with the following fields:

• gList the gList object that was returned by the utilized VennDiagram plotting function.

• areas The total area for each plotted group.

• intersectionCounts The number of intersections between groups.

The order for the areas and intersectionCounts fields is the same as the parameter order from the used plotting function (see e.g. draw.pairwise.venn and draw.triple.venn).

consensus returns a featureGroups object with a consensus from the compared feature groups.

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.

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 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 group 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.

Csárdi G, Nepusz T, Traag V, Horvát Sz, Zanini F, Noom D, Müller K (2024). _igraph: Network Analysis and Visualization in R_. doi:10.5281/zenodo.7682609 <https://doi.org/10.5281/zenodo.7682609>, R package version 2.1.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)

## S4 method for signature 'componentsTPs'
filter(
  obj,
  ...,
  retDirMatch = FALSE,
  minSpecSim = NULL,
  minSpecSimPrec = NULL,
  minSpecSimBoth = 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.

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

Csárdi G, Nepusz T, Traag V, Horvát Sz, Zanini F, Noom D, Müller K (2024). _igraph: Network Analysis and Visualization in R_. doi:10.5281/zenodo.7682609 <https://doi.org/10.5281/zenodo.7682609>, R package version 2.1.1, <https://CRAN.R-project.org/package=igraph>.

See Also

components for other relevant methods and generateComponents

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)

## 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'
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(rtWindow = 5), ...)

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

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

## 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'
unset(obj, set)

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.

• 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

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 topMostByRGroup EIC parameters are ignored unless the components are from homologous series.

See Also

generateComponents

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 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

Conversion of MS analysis files between several open and closed data formats.

Usage

MSFileFormats(algorithm = "pwiz", vendor = FALSE)

convertMSFiles(
  files = NULL,
  outPath = NULL,
  dirs = TRUE,
  anaInfo = NULL,
  from = NULL,
  to = "mzML",
  overWrite = FALSE,
  algorithm = "pwiz",
  centroid = algorithm != "openms",
  filters = NULL,
  extraOpts = NULL,
  PWizBatchSize = 1
)

Arguments

Details

MSFileFormats returns a character with all supported input formats (see below).

convertMSFiles converts the data format of an analysis to another. It uses tools from ProteoWizard (msConvert command), OpenMS (FileConverter command) or Bruker DataAnalysis to perform the conversion. Supported input and output formats include ‘mzXML’, ‘.mzML’ and several vendor formats, depending on which algorithm is used.

Parallelization

convertMSFiles (except if algorithm="bruker") uses multiprocessing to parallelize computations. Please see the parallelization section in the handbook for more details and patRoon options for configuration options.

Conversion formats

Possible output formats (to argument) are mzXML and mzML.

Possible input formats (from argument) depend on the algorithm that was chosen and may include:

• thermo: Thermo ‘.RAW’ files (only algorithm="pwiz").

• bruker: Bruker ‘.d’, ‘.yep’, ‘.baf’ and ‘.fid’ files (only algorithm="pwiz" or algorithm="bruker").

• agilent: Agilent ‘.d’ files (only algorithm="pwiz").

• ab: AB Sciex ‘.wiff’ files (only algorithm="pwiz").

• waters Waters ‘.RAW’ files (only algorithm="pwiz").

• mzXML/mzML: Open format ‘.mzXML’/‘.mzML’ files (only algorithm="pwiz" or algorithm="openms").

Note that the actual supported file formats of ProteoWizard depend on how it was installed (see here).

References

Rost HL, Sachsenberg T, Aiche S, Bielow C, Weisser H, Aicheler F, Andreotti S, Ehrlich H, Gutenbrunner P, Kenar E, Liang X, Nahnsen S, Nilse L, Pfeuffer J, Rosenberger G, Rurik M, Schmitt U, Veit J, Walzer M, Wojnar D, Wolski WE, Schilling O, Choudhary JS, Malmstrom L, Aebersold R, Reinert K, Kohlbacher O (2016). “OpenMS: a flexible open-source software platform for mass spectrometry data analysis.” Nature Methods, 13(9), 741–748. doi:10.1038/nmeth.3959.

Chambers MC, Maclean B, Burke R, Amodei D, Ruderman DL, Neumann S, Gatto L, Fischer B, Pratt B, Egertson J, Hoff K, Kessner D, Tasman N, Shulman N, Frewen B, Baker TA, Brusniak M, Paulse C, Creasy D, Flashner L, Kani K, Moulding C, Seymour SL, Nuwaysir LM, Lefebvre B, Kuhlmann F, Roark J, Rainer P, Detlev S, Hemenway T, Huhmer A, Langridge J, Connolly B, Chadick T, Holly K, Eckels J, Deutsch EW, Moritz RL, Katz JE, Agus DB, MacCoss M, Tabb DL, Mallick P (2012). “A cross-platform toolkit for mass spectrometry and proteomics.” Nature Biotechnology, 30(10), 918–920. doi:10.1038/nbt.2377.

Examples

## Not run: 
# Use FileConverter of OpenMS to convert between open mzXML/mzML format
convertMSFiles("standard-1.mzXML", to = "mzML", algorithm = "openms")

# Convert all Thermo .RAW files in the analyses/raw directory to mzML and
# store the files in analyses/mzml. During conversion files are centroided by
# the peakPicking filter and only MS 1 data is kept.
convertMSFiles("analyses/raw", "analyses/mzml", dirs = TRUE, from = "thermo",
               centroid = "vendor", filters = "msLevel 1")

## End(Not run)

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.

Usage

getDefEICParams(...)

Arguments

Details

To configure the creation of extracted ion chromatograms (EICs) several parameters exist:

• rtWindow Retention time (in seconds) that will be subtracted/added to respectively the minimum and maximum retention time of the feature. Thus, setting this value to ‘⁠>0⁠’ will 'zoom out' on the retention time axis.

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

• topMostByRGroup If set to TRUE and topMost is set: only create EICs for the top most features in each replicate group. For instance, when topMost=1 and topMostByRGroup=TRUE, then EICs will be plotted for the most intense feature of each replicate group.

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

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

• mzExpWindow To create EICs for analyses in which no feature was found, the m/z value is derived from the min/max values of all features in the feature group. The value of mzExpWindow further expands this window.

• 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.

These parameters are passed as a named list as the EICParams argument to functions that use EICs. The getDefEICParams function can be used to generate such parameter list with defaults.

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

## S4 method for signature 'featureGroups,missing'
plot(
  x,
  colourBy = c("none", "rGroups", "fGroups"),
  onlyUnique = FALSE,
  retMin = FALSE,
  showLegend = TRUE,
  col = NULL,
  pch = NULL,
  ...
)

## S4 method for signature 'featureGroups'
plotInt(
  obj,
  average = FALSE,
  normalized = FALSE,
  xnames = TRUE,
  showLegend = FALSE,
  pch = 20,
  type = "b",
  lty = 3,
  col = NULL,
  plotArgs = NULL,
  linesArgs = NULL
)

## S4 method for signature 'featureGroupsSet'
plotInt(
  obj,
  average = FALSE,
  normalized = FALSE,
  xnames = !sets,
  showLegend = sets,
  pch = 20,
  type = "b",
  lty = 3,
  col = NULL,
  plotArgs = NULL,
  linesArgs = NULL,
  sets = FALSE
)

## S4 method for signature 'featureGroups'
plotChord(
  obj,
  addSelfLinks = FALSE,
  addRetMzPlots = TRUE,
  average = FALSE,
  outerGroups = NULL,
  addIntraOuterGroupLinks = FALSE,
  ...
)

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

## S4 method for signature 'featureGroups'
plotVenn(obj, which = NULL, ...)

## S4 method for signature 'featureGroupsSet'
plotVenn(obj, which = NULL, ..., sets = FALSE)

## S4 method for signature 'featureGroups'
plotUpSet(obj, which = NULL, nsets = length(which), nintersects = NA, ...)

## S4 method for signature 'featureGroups'
plotVolcano(
  obj,
  FCParams,
  showLegend = TRUE,
  averageFunc = mean,
  normalized = FALSE,
  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, ...)

Arguments

Details

plot Generates an m/z vs retention time plot for all featue groups. Optionally highlights unique/overlapping presence amongst replicate groups.

plotInt Generates a line plot for the (averaged) intensity of feature groups within all analyses

plotChord Generates a chord diagram which can be used to visualize shared presence of feature groups between analyses or replicate groups. In addition, analyses/replicates sharing similar properties (e.g. location, age, type) may be grouped to enhance visualization between these 'outer groups'.

plotChroms Plots extracted ion chromatograms (EICs) of feature groups.

plotVenn plots a Venn diagram (using VennDiagram) outlining unique and shared feature groups between up to five replicate groups.

plotUpSet plots an UpSet diagram (using the upset function) outlining unique and shared feature groups between given replicate groups.

plotVolcano Plots Fold change data in a 'Volcano plot'.

plotGraph generates an interactive network plot which is used to explore internal standard (IS) assignments to each feature group. This requires the availability of IS assignments, see the documentation for normInts for details. The graph is rendered with visNetwork.

Value

plotVenn (invisibly) returns a list with the following fields:

• gList the gList object that was returned by the utilized VennDiagram plotting function.

• areas The total area for each plotted group.

• intersectionCounts The number of intersections between groups.

The order for the areas and intersectionCounts fields is the same as the parameter order from the used plotting function (see e.g. draw.pairwise.venn and draw.triple.venn).

plotGraph returns the result of visNetwork.

Sets workflows

The following methods are changed or with new functionality:

• plotVenn and plotInt allow to handle data per set. See the sets argument description.

• plotGraph only plots data per set, and requires the set argument to be set.

Author(s)

Rick Helmus <[email protected]> and Ricardo Cunha <[email protected]> (plotTICs and plotBPCs functions)

References

Gu, Z. (2014) circlize implements and enhances circular visualization in R. Bioinformatics.

Conway JR, Lex A, Gehlenborg N (2017). “UpSetR: an R package for the visualization of intersecting sets and their properties.” Bioinformatics, 33(18), 2938-2940. doi:10.1093/bioinformatics/btx364, http://dx.doi.org/10.1093/bioinformatics/btx364.

Lex A, Gehlenborg N, Strobelt H, Vuillemot R, Pfister H (2014). “UpSet: Visualization of Intersecting Sets.” IEEE Transactions on Visualization and Computer Graphics, 20(12), 1983–1992. doi:10.1109/tvcg.2014.2346248.

See Also

featureGroups-class, groupFeatures

Description

Holds information for all feature group annotations.

Usage

## S4 method for signature 'featureAnnotations'
annotations(obj)

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

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

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

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

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

## S4 method for signature 'featureAnnotations'
as.data.table(
  x,
  fGroups = NULL,
  fragments = FALSE,
  countElements = NULL,
  countFragElements = NULL,
  OM = FALSE,
  normalizeScores = "none",
  excludeNormScores = defaultExclNormScores(x)
)

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

## S4 method for signature 'featureAnnotations'
filter(
  obj,
  minExplainedPeaks = NULL,
  scoreLimits = NULL,
  elements = NULL,
  fragElements = NULL,
  lossElements = NULL,
  topMost = NULL,
  OM = FALSE,
  negate = FALSE
)

## S4 method for signature 'featureAnnotations'
plotVenn(obj, ..., labels = NULL, vennArgs = NULL)

## S4 method for signature 'featureAnnotations'
plotUpSet(
  obj,
  ...,
  labels = NULL,
  nsets = length(list(...)) + 1,
  nintersects = NA,
  upsetArgs = NULL
)

Arguments

Details

This class stores annotation data for feature groups, such as molecular formulae, SMILES identifiers, compound names etc. The class of objects that are generated by formula and compound annotation (generateFormulas and generateCompounds) are based on this class.

Value

as.data.table returns a data.table.

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

filter returns a filtered featureAnnotations object.

plotVenn (invisibly) returns a list with the following fields:

• gList the gList object that was returned by the utilized VennDiagram plotting function.

• areas The total area for each plotted group.

• intersectionCounts The number of intersections between groups.

The order for the areas and intersectionCounts fields is the same as the parameter order from the used plotting function (see e.g. draw.pairwise.venn and draw.triple.venn).

Methods (by generic)

• annotations(featureAnnotations): Accessor for the groupAnnotations slot.

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

• length(featureAnnotations): Obtain total number of candidates.

• x[i: Subset on feature groups.

• x[[i: Extracts annotation data for a feature group.

• $: Extracts annotation data for a feature group.

• as.data.table(featureAnnotations): Generates a table with all annotation data for each feature group and other information such as element counts.

• delete(featureAnnotations): Completely deletes specified annotations.

• filter(featureAnnotations): Provides rule based filtering for feature group annotations. Useful to eliminate unlikely candidates and speed up further processing.

• plotVenn(featureAnnotations): plots a Venn diagram (using VennDiagram) outlining unique and shared candidates of up to five different featureAnnotations objects.

• plotUpSet(featureAnnotations): plots an UpSet diagram (using the upset function) outlining unique and shared candidates between different featureAnnotations objects.

Slots

groupAnnotations

A list with for each annotated feature group a data.table with annotation data. Use the annotations method for access.

scoreTypes

A character with all the score types present in this object.

scoreRanges

The minimum and maximum score values of all candidates for each feature group. Used for normalization.

Source

Calculation of the aromaticity index (AI) and related double bond equivalents (DBE_AI) is performed as described in Koch 2015. Formula classification is performed by the rules described in Abdulla 2013. Filtering of OM related molecules is performed as described in Koch 2006 and Kujawinski 2006. (see references).

S4 class hierarchy

• workflowStep

  • featureAnnotations

    • formulas

      • formulasConsensus

      • formulasSet

      • formulasUnset

      • formulasSIRIUS

    • compounds

      • compoundsConsensus

      • compoundsMF

      • compoundsSet

      • compoundsUnset

      • compoundsSIRIUS

References

Koch BP, Dittmar T (2015). “From mass to structure: an aromaticity index for high-resolution mass data of natural organic matter.” Rapid Communications in Mass Spectrometry, 30(1), 250–250. doi:10.1002/rcm.7433.

Abdulla HA, Sleighter RL, Hatcher PG (2013). “Two Dimensional Correlation Analysis of Fourier Transform Ion Cyclotron Resonance Mass Spectra of Dissolved Organic Matter: A New Graphical Analysis of Trends.” Analytical Chemistry, 85(8), 3895–3902. doi:10.1021/ac303221j.

Koch BP, Dittmar T (2006). “From mass to structure: an aromaticity index for high-resolution mass data of natural organic matter.” Rapid Communications in Mass Spectrometry, 20(5), 926–932. doi:10.1002/rcm.2386.

Kujawinski EB, Behn MD (2006). “Automated Analysis of Electrospray Ionization Fourier Transform Ion Cyclotron Resonance Mass Spectra of Natural Organic Matter.” Analytical Chemistry, 78(13), 4363–4373. doi:10.1021/ac0600306.

Conway JR, Lex A, Gehlenborg N (2017). “UpSetR: an R package for the visualization of intersecting sets and their properties.” Bioinformatics, 33(18), 2938-2940. doi:10.1093/bioinformatics/btx364, http://dx.doi.org/10.1093/bioinformatics/btx364.

Lex A, Gehlenborg N, Strobelt H, Vuillemot R, Pfister H (2014). “UpSet: Visualization of Intersecting Sets.” IEEE Transactions on Visualization and Computer Graphics, 20(12), 1983–1992. doi:10.1109/tvcg.2014.2346248.

See Also

formulas-class and compounds-class

The derived formulas and compounds classes.

Description

This class is used for comparing different featureGroups objects.

Usage

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

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

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

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

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

Arguments

Details

Objects from this class are returned by comparison.

Methods (by generic)

• names(featureGroupsComparison): Obtain the labels that were given to each compared feature group.

• length(featureGroupsComparison): Number of feature groups objects that were compared.

• x[i: Subset on labels that were assigned to compared feature groups.

• x[[i: Extract a featureGroups object by its label.

• $: Extract a compound table for a feature group.

Slots

fGroupsList

A list of featureGroups object that were compared

comparedFGroups

A pseudo featureGroups object containing grouped feature groups.

Description

Returns chromatographic peak quality and score names for features and/or feature groups.

Usage

featureQualityNames(feat = TRUE, group = TRUE, scores = FALSE, totScore = TRUE)

Arguments

Description

Holds information for all features present within a set of analysis.

Usage

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

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

## S4 method for signature 'features'
featureTable(obj)

## S4 method for signature 'features'
analysisInfo(obj)

## S4 method for signature 'features'
analyses(obj)

## S4 method for signature 'features'
replicateGroups(obj)

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

## S4 method for signature 'features'
filter(
  obj,
  absMinIntensity = NULL,
  relMinIntensity = NULL,
  retentionRange = NULL,
  mzRange = NULL,
  mzDefectRange = NULL,
  chromWidthRange = NULL,
  qualityRange = NULL,
  negate = FALSE
)

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

## S4 method for signature 'features,ANY,missing'
x[[i]]

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

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

## S4 method for signature 'features'
calculatePeakQualities(obj, weights, flatnessFactor, parallel = TRUE)

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

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

## S4 method for signature 'features'
plotTICs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  colourBy = c("none", "analyses", "rGroups"),
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'features'
plotBPCs(
  obj,
  retentionRange = NULL,
  MSLevel = 1,
  retMin = FALSE,
  title = NULL,
  colourBy = c("none", "analyses", "rGroups"),
  showLegend = TRUE,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'featuresSet'
sets(obj)

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

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

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

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

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

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

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

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

Arguments

Details

This class provides a way to store intensity, retention times, m/z and other data for all features in a set of analyses. The class is virtual and derived objects are created by 'feature finders' such as findFeaturesOpenMS, findFeaturesXCMS and findFeaturesBruker.

Value

featureTable: A list containing a data.table for each analysis with feature data

analysisInfo: A data.frame containing a column with analysis name (analysis), its path (path), and other columns such as replicate group name (group) and blank reference (blank).

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

calculatePeakQualities returns a modified object amended with peak qualities and scores.

Methods (by generic)

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

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

• featureTable(features): Get table with feature information

• analysisInfo(features): Get analysis information

• analyses(features): returns a character vector with the names of the analyses for which data is present in this object.

• replicateGroups(features): returns a character vector with the names of the replicate groups for which data is present in this object.

• as.data.table(features): Returns all feature data in a table.

• filter(features): Performs common rule based filtering of features. Note that this (and much more) functionality is also provided by the filter method defined for featureGroups. However, filtering a features object may be useful to avoid grouping large amounts of features.

• x[i: Subset on analyses.

• x[[i: Extract a feature table for an analysis.

• $: Extract a feature table for an analysis.

• delete(features): Completely deletes specified features.

• calculatePeakQualities(features): Calculates peak qualities for each feature. This uses MetaClean R package to calculate the following metrics: ⁠Apex-Boundary Ratio⁠, ⁠FWHM2Base⁠, ⁠Jaggedness⁠, ⁠Modality⁠, ⁠Symmetry⁠, ⁠Gaussian Similarity⁠, ⁠Sharpness⁠, ⁠Triangle Peak Area Similarity Ratio⁠ and ⁠Zig-Zag index⁠. Please see the MetaClean publication (referenced below) for more details. For each metric, an additional score is calculated by normalizing all feature values (unless the quality metric definition has a fixed range) and scale from ‘⁠0⁠’ (worst) to ‘⁠1⁠’ (best). Then, a ⁠totalScore⁠ for each feature is calculated by the (weighted) sum of all score values.

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

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

• plotTICs(features): Plots the TICs of the analyses.

• plotBPCs(features): Plots the BPCs of the analyses.

Slots

features

List of features per analysis file. Use the featureTable method for access.

analysisInfo

Analysis group information. Use the analysisInfo method for access.

S4 class hierarchy

• workflowStep

  • features

    • featuresSet

    • featuresUnset

    • featuresFromFeatGroups

    • featuresConsensus

    • featuresBruker

    • featuresEnviPick

    • featuresKPIC2

    • featuresOpenMS

    • featuresSAFD

    • featuresSIRIUS

    • featuresBrukerTASQ

    • featuresXCMS

    • featuresXCMS3

Sets workflows

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

The following methods are specifically defined for sets workflows:

• sets Returns the set names for this object.

• unset Converts the object data for a specified set into a 'non-set' object (featuresUnset), which allows it to be used in 'regular' workflows. The adduct annotations for the selected set (e.g. as passed to makeSet) are used to convert all feature masses to ionic m/z values.

The following methods are changed or with new functionality:

• filter and the subset operator ([) have specific arguments to choose/filter by (feature presence in) sets. See the sets argument description.

Note

For calculatePeakQualities: sometimes MetaClean may return NA for the ⁠Gaussian Similarity⁠ metric, in which case it will be set to ‘⁠0⁠’.

Author(s)

Rick Helmus <[email protected]> and Ricardo Cunha <[email protected]> (getTICs, getBPCs, plotTICs and plotBPCs functions)

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.

See Also

findFeatures

Description

Automatically find features.

Usage

findFeatures(analysisInfo, algorithm, ..., verbose = TRUE)

Arguments

Details

Several functions exist to collect features (i.e. retention and MS information that represent potential compounds) from a set of analyses. All 'feature finders' return an object derived from the features base class. The next step in a general workflow is to group and align these features across analyses with groupFeatures. Note that some feature finders have a plethora of options which sometimes may have a large effect on the quality of results. Fine-tuning parameters is therefore important, and the optimum is largely dependent upon applied analysis methodology and instrumentation.

findFeatures is a generic function that will find features by one of the supported algorithms. The actual functionality is provided by algorithm specific functions such as findFeaturesOpenMS and findFeaturesXCMS. While these functions may be called directly, findFeatures provides a generic interface and is therefore usually preferred.

Value

An object of a class which is derived from features.

Note

In most cases it will be necessary to centroid your MS input files. The only exception is Bruker, however, you will still need centroided ‘mzXML’/‘mzML’ files for e.g. plotting chromatograms. In this case the centroided MS files should be stored in the same directory as the raw Bruker ‘.d’ files. The convertMSFiles function can be used to centroid data.

See Also

The features output class and its methods and the algorithm specific functions: findFeaturesBruker, findFeaturesOpenMS, findFeaturesXCMS, findFeaturesXCMS3, findFeaturesEnviPick, findFeaturesSIRIUS, findFeaturesKPIC2, findFeaturesSAFD

Description

Uses the 'Find Molecular Features' (FMF) algorithm of Bruker DataAnalysis vendor software to find features.

Usage

findFeaturesBruker(
  analysisInfo,
  doFMF = "auto",
  startRange = 0,
  endRange = 0,
  save = TRUE,
  close = save,
  verbose = TRUE
)

Arguments

Details

This function uses Bruker to automatically find features. This function is called when calling findFeatures with algorithm="bruker".

The resulting 'compounds' are transferred from DataAnalysis and stored as features.

This algorithm only works with Bruker data files (.d extension) and requires Bruker DataAnalysis and the RDCOMClient package to be installed. Furthermore, DataAnalysis combines multiple related masses in a feature (e.g. isotopes, adducts) but does not report the actual (monoisotopic) mass of the feature. Therefore, it is simply assumed that the feature mass equals that of the highest intensity mass peak.

Value

An object of a class which is derived from features.

Note

If any errors related to DCOM appear it might be necessary to terminate DataAnalysis (note that DataAnalysis might still be running as a background process). The ProcessCleaner application installed with DataAnalayis can be used for this.

See Also

findFeatures for more details and other algorithms.

Description

Uses the enviPickwrap function from the enviPick R package to extract features.

Usage

findFeaturesEnviPick(analysisInfo, ..., parallel = TRUE, verbose = TRUE)

Arguments

Details

This function uses enviPick to automatically find features. This function is called when calling findFeatures with algorithm="envipick".

The input MS data files need to be centroided. The convertMSFiles function can be used to centroid data.

Value

An object of a class which is derived from features.

Note

The analysis files must be in the mzXML format.

See Also

findFeatures for more details and other algorithms.

Description

Uses the KPIC2 R package to extract features.

Usage

findFeaturesKPIC2(
  analysisInfo,
  kmeans = TRUE,
  level = 1000,
  ...,
  parallel = TRUE,
  verbose = TRUE
)

Arguments

Details

This function uses KPIC2 to automatically find features. This function is called when calling findFeatures with algorithm="kpic2".

The MS files should be in the mzML or mzXML format.

The input MS data files need to be centroided. The convertMSFiles function can be used to centroid data.

Value

An object of a class which is derived from features.

References

Ji H, Zeng F, Xu Y, Lu H, Zhang Z (2017). “KPIC2: An Effective Framework for Mass Spectrometry-Based Metabolomics Using Pure Ion Chromatograms.” Analytical Chemistry, 89(14), 7631–7640. doi:10.1021/acs.analchem.7b01547.

See Also

findFeatures for more details and other algorithms.

Description

uses the FeatureFinderMetabo TOPP tool (see http://www.openms.de) to find features.

Usage

findFeaturesOpenMS(
  analysisInfo,
  noiseThrInt = 1000,
  chromSNR = 3,
  chromFWHM = 5,
  mzPPM = 10,
  reEstimateMTSD = TRUE,
  traceTermCriterion = "sample_rate",
  traceTermOutliers = 5,
  minSampleRate = 0.5,
  minTraceLength = 3,
  maxTraceLength = -1,
  widthFiltering = "fixed",
  minFWHM = 1,
  maxFWHM = 30,
  traceSNRFiltering = FALSE,
  localRTRange = 10,
  localMZRange = 6.5,
  isotopeFilteringModel = "metabolites (5% RMS)",
  MZScoring13C = FALSE,
  useSmoothedInts = TRUE,
  extraOpts = NULL,
  intSearchRTWindow = 3,
  useFFMIntensities = FALSE,
  verbose = TRUE
)

Arguments