Base features class

Source: R/features.R, R/features-set.R, R/features-bruker.R, and 7 more

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

# S4 method for features
length(x)

# S4 method for features
show(object)

# S4 method for features
featureTable(obj)

# S4 method for features
analysisInfo(obj)

# S4 method for features
analyses(obj)

# S4 method for features
replicateGroups(obj)

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

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

# S4 method for features,ANY,missing,missing
[(x, i, j, ..., drop = TRUE)

# S4 method for features,ANY,missing
[[(x, i)

# S4 method for features
$(x, name)

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

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

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

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

# S4 method for 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 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 featuresSet
sets(obj)

# S4 method for featuresSet
show(object)

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

# S4 method for featuresSet,ANY,missing,missing
[(x, i, ..., sets = NULL, drop = TRUE)

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

# S4 method for featuresSet
unset(obj, set)

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

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

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

Arguments

obj, x, object

features object to be accessed

absMinIntensity, relMinIntensity

Minimum absolute/relative intensity for features to be kept. The relative intensity is determined from the feature with highest intensity (within the same analysis). Set to 0 or NULL to skip this step.

retentionRange, mzRange, mzDefectRange, chromWidthRange

Range of retention time (in seconds), m/z, mass defect (defined as the decimal part of m/z values) or chromatographic peak width (in seconds), respectively. Features outside this range will be removed. Should be a numeric vector with length of two containing the min/max values. The maximum can be Inf to specify no maximum range. Set to NULL to skip this step.

qualityRange

Used to filter features by their peak qualities/scores (see calculatePeakQualities). Should be a named list with min/max ranges for each quality/score to be filtered (the featureQualityNames function can be used to obtain valid names). Example: qualityRange=list(ModalityScore=c(0.3, Inf), SymmetryScore=c(0.5, Inf)). Set to NULL to ignore.

negate

If set to TRUE then filtering operations are performed in opposite manner.

i, j

For [/[[: A numeric or character value which is used to select analyses by their index or name, respectively (for the order/names see analyses()).

For [: Can also be logical to perform logical selection (similar to regular vectors). If missing all analyses are selected.

For [[: should be a scalar value.

For delete: The data to remove from. i are the analyses as numeric index, logical or character, j the features as numeric index (row) of the feature. If either is NULL then data for all is removed. j may also be a function: it will be called for each analysis, with the feature table (a data.table), the analysis name and any other arguments passed as ... to delete. The return value of this function specifies the feature indices (rows) to be removed (specified as an integer or logical vector).

...

For delete: passed to the function specified as j.

For sets workflow methods: further arguments passed to the base features method.

drop

ignored.

name

The analysis name (partially matched).

weights

A named numeric vector that defines the weight for each score to calculate the totalScore. The names of the vector follow the score names. Unspecified weights are defaulted to 1. Example: weights=c(ApexBoundaryRatioScore=0.5, GaussianSimilarityScore=2).

flatnessFactor

Passed to MetaClean as the flatness.factor argument to calculateJaggedness and calculateModality.

parallel

If set to TRUE then code is executed in parallel through the futures package. Please see the parallelization section in the handbook for more details.

MSLevel

Integer vector with the ms levels (i.e., 1 for MS1 and 2 for MS2) to obtain TIC traces.

retMin

Plot retention time in minutes (instead of seconds).

title

Character string used for title of the plot. If NULL a title will be automatically generated.

colourBy

Sets the automatic colour selection: "none" for a single colour or "analyses"/"rGroups" for a distinct colour per analysis or analysis replicate group.

showLegend

Plot a legend if TRUE.

xlim, ylim

Sets the plot size limits used by plot. Set to NULL for automatic plot sizing.

sets

(sets workflow) For [ and filter: a character with name(s) of the sets to keep (or remove if negate=TRUE).

set

(sets workflow) The name of the set.

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.

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.

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.

Note

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

S4 class hierarchy

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.

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

Author

Ricardo Cunha, cunha@iuta.de