formulas-class: Formula annotations class

In rickhelmus/patRoon: Workflows for Mass-Spectrometry Based Non-Target Analysis

Formula annotations class

Description

Contains data of generated chemical formulae for given feature groups.

Usage

## S4 method for signature 'formulas'
annotations(obj, features = FALSE)

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

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

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

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

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

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

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

## S4 method for signature 'formulas'
plotSpectrum(
  obj,
  index,
  groupName,
  analysis = NULL,
  MSPeakLists,
  title = NULL,
  specSimParams = getDefSpecSimParams(),
  mincex = 0.9,
  xlim = NULL,
  ylim = NULL,
  ...
)

## S4 method for signature 'formulas'
plotScores(
  obj,
  index,
  groupName,
  analysis = NULL,
  normalizeScores = "max",
  excludeNormScores = defaultExclNormScores(obj)
)

## S4 method for signature 'formulas'
consensus(
  obj,
  ...,
  absMinAbundance = NULL,
  relMinAbundance = NULL,
  uniqueFrom = NULL,
  uniqueOuter = FALSE,
  rankWeights = 1,
  labels = NULL
)

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

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

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

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

## S4 method for signature 'formulasSet'
plotSpectrum(
  obj,
  index,
  groupName,
  analysis = NULL,
  MSPeakLists,
  title = NULL,
  specSimParams = getDefSpecSimParams(),
  mincex = 0.9,
  xlim = NULL,
  ylim = NULL,
  perSet = TRUE,
  mirror = TRUE,
  ...
)

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

## S4 method for signature 'formulasSet'
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 'formulasSet'
unset(obj, set)

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

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

Arguments

obj, x, object	The formulas object.
features	If TRUE returns formula data for features, otherwise for feature groups.
i, j	For [[: If both i and j are specified then i specifies the analysis and j the feature group of the feature for which annotations should be returned. Otherwise i specifies the feature group for which group annotations should be returned. i/j can be specified as integer index or as a character name. Otherwise passed to the featureAnnotations method.
...	For plotSpectrum: Further arguments passed to plot. For delete: passed to the function specified as j. For consensus: Any further (and unique) formulas objects. \setsPassedArgs 1formulas
fGroups, fragments, countElements, countFragElements, OM	Passed to the featureAnnotations method.
normalizeScores	A character that specifies how normalization of annotation scorings occurs. Either "none" (no normalization), "max" (normalize to max value) or "minmax" (perform min-max normalization). Note that normalization of negative scores (e.g. output by SIRIUS) is always performed as min-max. Furthermore, currently normalization for compounds takes the original min/max scoring values into account when candidates were generated. Thus, for compounds scoring, normalization is not affected when candidate results were removed after they were generated (e.g. by use of filter).
excludeNormScores	A character vector specifying any compound scoring names that should not be normalized. Set to NULL to normalize all scorings. Note that whether any normalization occurs is set by the excludeNormScores argument. For compounds: By default score and individualMoNAScore are set to mimic the behavior of the MetFrag web interface.
average	If set to TRUE an 'average formula' is generated for each feature group by combining all elements from all candidates and averaging their amounts. This obviously leads to non-existing formulae, however, this data may be useful to deal with multiple candidate formulae per feature group when performing elemental characterization. Setting this to TRUE disables reporting of most other data.
index	The candidate index (row). For plotSpectrum two indices can be specified to compare spectra. In this case groupName and analysis (if not NULL) should specify values for the spectra to compare.
groupName	The name of the feature group (or feature groups when comparing spectra) to which the candidate belongs.
analysis	A character specifying the analysis (or analyses when comparing spectra) for which the annotated spectrum should be plotted. If NULL then annotation results for the complete feature group will be plotted.
MSPeakLists	The MSPeakLists object that was used to generate the candidate
onlyAnnotated	Set to TRUE to filter out any peaks that could not be annotated.
title	The title of the plot. Set to NULL for an automatically generated title.
specSimParams	A named list with parameters that influence the calculation of MS spectra similarities. See the spectral similarity parameters documentation for more details.
mincex	The formula annotation labels are automatically scaled. The mincex argument forces a minimum cex value for readability.
xlim, ylim	Sets the plot size limits used by plot. Set to NULL for automatic plot sizing.
absMinAbundance, relMinAbundance	Minimum absolute or relative (‘⁠0-1⁠’) abundance across objects for a result to be kept. For instance, relMinAbundance=0.5 means that a result should be present in at least half of the number of compared objects. Set to ‘⁠NULL⁠’ to ignore and keep all results. Limits cannot be set when uniqueFrom is not NULL.
uniqueFrom	Set this argument to only retain formulas that are unique within one or more of the objects for which the consensus is made. Selection is done by setting the value of uniqueFrom to a logical (values are recycled), numeric (select by index) or a character (as obtained with algorithm(obj)). For logical and numeric values the order corresponds to the order of the objects given for the consensus. Set to NULL to ignore.
uniqueOuter	If uniqueFrom is not NULL and if uniqueOuter=TRUE: only retain data that are also unique between objects specified in uniqueFrom.
rankWeights	A numeric vector with weights of to calculate the mean ranking score for each candidate. The value will be re-cycled if necessary, hence, the default value of ‘⁠1⁠’ means equal weights for all considered objects.
labels	A character with names to use for labelling. If NULL labels are automatically generated.
sets	\setsWF A character with name(s) of the sets to keep (or remove if negate=TRUE). Note: if updateConsensus=FALSE then the setCoverage column of the annotation results is not updated.
updateConsensus	\setsWF If TRUE then the annonation consensus among set results is updated. See the ⁠Sets workflows⁠ section for more details.
drop	Passed to the featureAnnotations method.
negate	Passed to the featureAnnotations method.
perSet, mirror	\setsWF If perSet=TRUE then the set specific mass peaks are annotated separately. Furthermore, if mirror=TRUE (and there are two sets in the object) then a mirror plot is generated.
filterSets	\setsWF Controls how algorithms concensus abundance filters are applied. See the ⁠Sets workflows⁠ section below.
setThreshold, setThresholdAnn	\setsWF Thresholds used to create the annotation set consensus. See generateFormulas.
setAvgSpecificScores	\setsWF If TRUE then set specific annotation scores (e.g. MS/MS and isotopic pattern match scores) are averaged for the set consensus. See generateFormulas.
set	\setsWF The name of the set.

Details

formulas objects are obtained with generateFormulas. This class is derived from the featureAnnotations class, please see its documentation for more methods and other details.

Value

annotations returns a list containing for each feature group (or feature if features=TRUE) a data.table with an overview of all generated formulae and other data such as candidate scoring and MS/MS fragments.

consensus returns a formulas object that is produced by merging results from multiple formulas objects.

Methods (by generic)

• annotations(formulas): Accessor method to obtain generated formulae.

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

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

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

• x[[i: Extracts a formula table, either for a feature group or for features in an analysis.

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

• annotatedPeakList(formulas): Returns an MS/MS peak list annotated with data from a given candidate formula.

• plotSpectrum(formulas): Plots an annotated spectrum for a given candidate formula of a feature or feature group. Two spectra can be compared by specifying a two-sized vector for the index, groupName and (if desired) analysis arguments.

• plotScores(formulas): Plots a barplot with scoring of a candidate formula.

• consensus(formulas): 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

featureFormulas

A list with all generated formulae for each analysis/feature group. Use the annotations method for access.

setThreshold,setThresholdAnn,setAvgSpecificScores

\setsWF

A copy of the equally named arguments that were passed when this object was created by generateFormulas.

origFGNames

\setsWF

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

S4 class hierarchy

• featureAnnotations

  • formulas

    • formulasConsensus

    • formulasSet

      • formulasConsensusSet

    • formulasUnset

    • formulasSIRIUS

Source

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

Sets workflows

\setsWFClass

formulasSetformulas

\setsWFNewMethodsSO

formulasUnsetOnly the annotation results that are present in the specified set are kept (based on the set consensus, see below for implications).

\setsWFChangedMethods \item

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

\item

annotatedPeakList Returns a combined annotation table with all sets.

\item

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

\item

consensus Creates the algorithm consensus based on the original annotation data (see below for implications). Then, like the sets workflow method for generateFormulas, 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 GenForm), 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).

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

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

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 formulas[, 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.

See Also

The featureAnnotations base class for more relevant methods and generateFormulas.

rickhelmus/patRoon documentation built on Nov. 22, 2024, 3:11 p.m.