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 ID of each chromatographic peak (i.e. its row name in chromPeaks) and each feature (i.e., its row name in featureDefinitions) are available in the returned Spectra() with spectra variables "peak_id" and "feature_id", respectively.

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

## 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"`.

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 "peak_id" and "feature_id" define to which chromatographic peak or feature each individual spectrum is associated with.