featureSpectra {xcms} | 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 selected 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.

In contrast to the `chromPeakSpectra()` function, selecting a `method` different than `"all"` will not return a single spectrum per feature, but one spectrum per chromatographic peak assigned to the feature.

Note also that `msLevel = 1L` is only supported for `return.type = "List"` or `return.type = "Spectra"`.

### Usage

    featureSpectra(
      x,
      msLevel = 2L,
      expandRt = 0,
      expandMz = 0,
      ppm = 0,
      skipFilled = FALSE,
      return.type = c("MSpectra", "Spectra", "list", "List"),
      features = character(),
      ...
    )

### Arguments

`x` | XCMSnExp object with feature defitions available.
`msLevel` | `integer(1)` defining whether MS1 or MS2 spectra should be returned. `msLevel = 1` is currently only supported for `return.type` being `"Spectra"` or `"List"`.
`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 result type. Defaults to `return.type = "MSpectra"` but `return.type = "Spectra"` or `return.type = "List"` are preferred. See below for more information.
`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"`.
`...` | additional arguments to be passed along to `chromPeakSpectra()`, such as `method`.

### Value

parameter `return.type` allow to specify the type of the returned object:

- `return.type = "MSpectra"`: a MSpectra object with elements being Spectrum objects. The result objects contains all spectra for all features. Metadata column `"feature_id"` provides the ID of the respective feature (i.e. its rowname in `featureDefinitions()`).

- `return.type = "Spectra"`: a `Spectra` object (defined in the `Spectra` package). The result contains all spectra for all features. Metadata column `"feature_id"` provides the ID of the respective feature (i.e. its rowname in `featureDefinitions()`.

- `return.type = "list"`: `list` of `list`s that are either of length 0 or contain Spectrum2 object(s) within the m/z-rt range. The length of the list matches the number of features.

- `return.type = "List"`: `List` of length equal to the number of features with MS level `msLevel` is returned with elements being either `NULL` (no spectrum found) or a `Spectra` object.

### Author(s)

Johannes Rainer

[Package xcms version 3.16.1 Index]