chromPeakSpectra {xcms} | R Documentation

## Extract spectra associated with chromatographic peaks

### Description

Extract (MS1 or MS2) spectra from an XCMSnExp object for each identified chromatographic peak. The function returns by default spectra for chromatographic peaks of all MS levels, but parameter `peaks` allows to restrict the result to selected chromatographic peaks. For `msLevel = 1L` (only supported for `return.type = "Spectra"` or `return.type = "List"`) MS1 spectra within the retention time boundaries (in the file in which the peak was detected) are returned. For `msLevel = 2L` MS2 spectra are returned for a chromatographic peak if their precursor m/z is within the retention time and m/z range of the chromatographic peak. Parameter `method` allows to define whether all or a single spectrum should be returned:

- `method = "all"`: (default): return all spectra for each peak.

- `method = "closest_rt"`: return the spectrum with the retention time closest to the peak's retention time (at apex).

- `method = "closest_mz"`: return the spectrum with the precursor m/z closest to the peaks's m/z (at apex); only supported for `msLevel = 2L`.

- `method = "signal"`: return the spectrum with the sum of intensities most similar to the peak's apex signal (`"maxo"`); only supported for `msLevel = 2L`.

- `method = "largest_tic"`: return the spectrum with the largest total signal (sum of peaks intensities).

- `method = "largest_bpi"`: return the spectrum with the largest peak intensity (maximal peak intensity).

Parameter `return.type` allows to specify the type of the result object. Please use `return.type = "Spectra"` or `return.type = "List"`, `return.type = "list"` or the default `return.type = "MSpectra"` will be deprecated (also, they do not support extracting MS1 spectra).

See also the LC-MS/MS data analysis vignette for more details and examples.

### Usage

    chromPeakSpectra(
      x,
      msLevel = 2L,
      expandRt = 0,
      expandMz = 0,
      ppm = 0,
      method = c("all", "closest_rt", "closest_mz", "signal", "largest_tic", "largest_bpi"),
      skipFilled = FALSE,
      return.type = c("MSpectra", "Spectra", "list", "List"),
      peaks = character()
    )

### Arguments

`x` | XCMSnExp object with identified chromatographic peaks.
`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.
`method` | `character(1)` specifying which spectra to include in the result. Defaults to `method = "all"`. See function description for details.
`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.
`peaks` | `character`, `logical` or `integer` allowing to specify a subset of chromatographic peaks in `chromPeaks` for which spectra should be returned (providing either their ID, a logical vector same length than `nrow(chromPeaks(x))` or their index in `chromPeaks(x)`). This parameter overrides `skipFilled` and is only supported for `return.type` being either `"Spectra"` or `"List"`.

### 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 peaks. Metadata column `"peak_id"` provides the ID of the respective peak (i.e. its rowname in `chromPeaks()`).

- `return.type = "Spectra"`: a `Spectra` object (defined in the `Spectra` package). The result contains all spectra for all peaks. Metadata column `"peak_id"` provides the ID of the respective peak (i.e. its rowname in `chromPeaks()` and `"peak_index"` its index in the object's `chromPeaks` matrix.

- `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 peaks.

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

### Author(s)

Johannes Rainer

### Examples

    ## Read a file with DDA LC-MS/MS data
    fl <- system.file("TripleTOF-SWATH/PestMix1_DDA.mzML", package = "msdata")
    dda <- readMSData(fl, mode = "onDisk")

    ## Subset the object to reduce runtime of the example
    dda <- filterRt(dda, c(200, 400))

    ## Perform MS1 peak detection
    dda <- findChromPeaks(dda, CentWaveParam(peakwidth = c(5, 15), prefilter = c(5, 1000)))

    ## Load the required Spectra package and return all MS2 spectro for each
    ## chromatographic peaks as a Spectra object
    ms2_sps <- chromPeakSpectra(dda, return.type = "Spectra")
    ms2_sps

    ## columns peak_id or peak_index assign spectra to the chromatographic peaks
    ms2_sps$peak_id
    ms2_sps$peak_index
    chromPeaks(dda)

    ## Alternatively, return the result as a List of Spectra objects. This list
    ## is parallel to chromPeaks hence the mapping between chromatographic peaks
    ## and MS2 spectra is easier.
    ms2_sps <- chromPeakSpectra(dda, return.type = "List")
    ms2_sps[[1L]]
    length(ms2_sps)

    ## In addition to MS2 spectra we could also return the MS1 spectrum for each
    ## chromatographic peak which is closest to the peak's apex position.
    ms1_sps <- chromPeakSpectra(dda, msLevel = 1L, method = "closest_rt",
        return.type = "Spectra")
    ms1_sps

    ## Parameter peaks would allow to extract spectra for specific peaks only
    chromPeakSpectra(dda, msLevel = 1L, method = "closest_rt", peaks = c(3, 5))

[Package xcms version 3.16.1 Index]