featureSpectra: Extract spectra associated with features
In sneumann/xcms: LC-MS and GC-MS Data Analysis

featureSpectra

R Documentation

Extract spectra associated with features

Description

This function returns spectra associated with the identified features in the input object. By default, spectra are returned for all features (from all MS levels), but parameter features allows to specify/select features for which the result should be returned. Parameter msLevel allows to define whether MS level 1 or 2 spectra should be returned. For msLevel = 1L all MS1 spectra within the retention time range of each chromatographic peak (in that respective data file) associated with a feature are returned. Note that for samples in which no peak was identified (or even filled-in) no spectra are returned. For msLevel = 2L all MS2 spectra with a retention time within the retention time range and their precursor m/z within the m/z range of any chromatographic peak of a feature are returned.

See also chromPeakSpectra() (used internally to extract spectra for each chromatographic peak of a feature) for additional information, specifically also on parameter method. By default (method = "all") all spectra associated with any of the chromatographic peaks of a feature are returned. With any other option for method, a single spectrum per chromatographic peak will be returned (hence multiple spectra per feature).

The information from featureDefinitions for each feature can be included in the returned Spectra() object using the featureColumns parameter. This is useful for keeping details such as the median retention time (rtmed) or median m/z (mzmed). The columns will retain their names as specified in the featureDefinitions object, prefixed by "feature_" (e.g., "feature_mzmed"). Additionally, the feature ID (i.e., the row name of the feature in the featureDefinitions data.frame) is always added as a metadata column named "feature_id".

See also chromPeakSpectra(), as it supports a similar parameter for including columns from the chromatographic peaks in the returned spectra object. These parameters can be used in combination to include information from both the chromatographic peaks and the features in the returned Spectra(). The peak ID (i.e., the row name of the peak in the chromPeaks matrix) is added as a metadata column named "chrom_peak_id".

Usage

featureSpectra(object, ...)

## S4 method for signature 'XcmsExperiment'
featureSpectra(
  object,
  msLevel = 2L,
  expandRt = 0,
  expandMz = 0,
  ppm = 0,
  skipFilled = FALSE,
  return.type = c("Spectra", "List"),
  features = character(),
  featureColumns = c("rtmed", "mzmed"),
  ...
)

## S4 method for signature 'XCMSnExp'
featureSpectra(
  object,
  msLevel = 2L,
  expandRt = 0,
  expandMz = 0,
  ppm = 0,
  skipFilled = FALSE,
  return.type = c("MSpectra", "Spectra", "list", "List"),
  features = character(),
  ...
)

Arguments

`object`	XcmsExperiment or XCMSnExp object with feature defitions.
`...`	additional arguments to be passed along to `chromPeakSpectra()`, such as `method`.
`msLevel`	`integer(1)` defining the MS level of the spectra that should be returned.
`expandRt`	`numeric(1)` to expand the retention time range of each peak by a constant value on each side.
`expandMz`	`numeric(1)` to expand the m/z range of each peak by a constant value on each side.
`ppm`	`numeric(1)` to expand the m/z range of each peak (on each side) by a value dependent on the peak's m/z.
`skipFilled`	`logical(1)` whether spectra for filled-in peaks should be reported or not.
`return.type`	`character(1)` defining the type of result object that should be returned.
`features`	`character`, `logical` or `integer` allowing to specify a subset of features in `featureDefinitions` for which spectra should be returned (providing either their ID, a logical vector same length than `nrow(featureDefinitions(x))` or their index in `featureDefinitions(x)`). This parameter overrides `skipFilled` and is only supported for `return.type` being either `"Spectra"` or `"List"`.
`featureColumns`	`character` vector with the names of the columns from `featureDefinitions` that should be added to the returned spectra object. The columns will be named as they are written in the `featureDefinitions` object with the prefix `⁠"feature_⁠`. Defaults to `c("mzmed", "rtmed")`.

Value

The function returns either a Spectra() (for return.type = "Spectra") or a List of Spectra (for return.type = "List"). For the latter, the order and the length matches parameter features (or if no features is defined the order of the features in featureDefinitions(object)).

Spectra variables "chrom_peak_id" and "feature_id" define to which chromatographic peak or feature each individual spectrum is associated with.