featureChromatograms: Extract ion chromatograms for each feature
In sneumann/xcms: LC-MS and GC-MS Data Analysis

featureChromatograms

R Documentation

Extract ion chromatograms for each feature

Description

Extract ion chromatograms for features in an XcmsExperiment or XCMSnExp object. The function returns for each feature the extracted ion chromatograms (along with all associated chromatographic peaks) in each sample. The chromatogram is extracted from the m/z - rt region that includes all chromatographic peaks of a feature. By default, this region is defined using the range of the chromatographic peaks' m/z and retention times (with mzmin = min, mzmax = max, rtmin = min and rtmax = max). For some features, and depending on the data, the m/z and rt range can thus be relatively large. The boundaries of the m/z - rt region can also be restricted by changing parameters mzmin, mzmax, rtmin and rtmax to a different functions, such as median.

By default only chromatographic peaks associated with a feature are included in the returned XChromatograms object. For object being an XCMSnExp object parameter include allows also to return all chromatographic peaks with their apex position within the selected region (include = "apex_within") or any chromatographic peak overlapping the m/z and retention time range (include = "any").

Usage

featureChromatograms(object, ...)

## S4 method for signature 'XcmsExperiment'
featureChromatograms(
  object,
  expandRt = 0,
  expandMz = 0,
  aggregationFun = "max",
  features = character(),
  return.type = "XChromatograms",
  chunkSize = 2L,
  mzmin = min,
  mzmax = max,
  rtmin = min,
  rtmax = max,
  ...,
  progressbar = TRUE,
  BPPARAM = bpparam()
)

## S4 method for signature 'XCMSnExp'
featureChromatograms(
  object,
  expandRt = 0,
  aggregationFun = "max",
  features,
  include = c("feature_only", "apex_within", "any", "all"),
  filled = FALSE,
  n = length(fileNames(object)),
  value = c("maxo", "into"),
  expandMz = 0,
  ...
)

Arguments

`object`	`XcmsExperiment` or `XCMSnExp` object with grouped chromatographic peaks.
`...`	optional arguments to be passed along to the `chromatogram()` function.
`expandRt`	`numeric(1)` to expand the retention time range for each chromatographic peak by a constant value on each side.
`expandMz`	`numeric(1)` to expand the m/z range for each chromatographic peak by a constant value on each side. Be aware that by extending the m/z range the extracted EIC might no longer represent the actual identified chromatographic peak because intensities of potential additional mass peaks within each spectra would be aggregated into the final reported intensity value per spectrum (retention time).
`aggregationFun`	`character(1)` specifying the name that should be used to aggregate intensity values across the m/z value range for the same retention time. The default `"max"` returns a base peak chromatogram.
`features`	`integer`, `character` or `logical` defining a subset of features for which chromatograms should be returned. Can be the index of the features in `featureDefinitions`, feature IDs (row names of `featureDefinitions`) or a logical vector.
`return.type`	`character(1)` defining how the result should be returned. At present only `return.type = "XChromatograms"` is supported and the results are thus returned as an `XChromatograms()` object.
`chunkSize`	For `object` being an `XcmsExperiment`: `integer(1)` defining the number of files from which the data should be loaded at a time into memory. Defaults to `chunkSize = 2L`.
`mzmin`	`function` defining how the lower boundary of the m/z region from which the EIC is integrated should be defined. Defaults to `mzmin = min` thus the smallest `"mzmin"` value for all chromatographic peaks of a feature will be used.
`mzmax`	`function` defining how the upper boundary of the m/z region from which the EIC is integrated should be defined. Defaults to `mzmax = max` thus the largest `"mzmax"` value for all chromatographic peaks of a feature will be used.
`rtmin`	`function` defining how the lower boundary of the rt region from which the EIC is integrated should be defined. Defaults to `rtmin = min` thus the smallest `"rtmin"` value for all chromatographic peaks of a feature will be used.
`rtmax`	`function` defining how the upper boundary of the rt region from which the EIC is integrated should be defined. Defaults to `rtmax = max` thus the largest `"rtmax"` value for all chromatographic peaks of a feature will be used.
`progressbar`	`logical(1)` defining whether a progress bar is shown.
`BPPARAM`	For `object` being an `XcmsExperiment`: parallel processing setup. Defaults to `BPPARAM = bpparam()`. See `bpparam()` for more information.
`include`	Only for `object` being an `XCMSnExp`: `character(1)` defining which chromatographic peaks (and related feature definitions) should be included in the returned `XChromatograms()`. Defaults to `"feature_only"`; See description above for options and details.
`filled`	Only for `object` being an `XCMSnExp`: `logical(1)` whether filled-in peaks should be included in the result object. The default is `filled = FALSE`, i.e. only detected peaks are reported.
`n`	Only for `object` being an `XCMSnExp`: `integer(1)` to optionally specify the number of top n samples from which the EIC should be extracted.
`value`	Only for `object` being an `XCMSnExp`: `character(1)` specifying the column to be used to sort the samples. Can be either `"maxo"` (the default) or `"into"` to use the maximal peak intensity or the integrated peak area, respectively.

Value

XChromatograms() object. In future, depending on parameter return.type, the data might be returned as a different object.

Note

The EIC data of a feature is extracted from every sample using the same m/z - rt area. The EIC in a sample does thus not exactly represent the signal of the actually identified chromatographic peak in that sample. The chromPeakChromatograms() function would allow to extract the actual EIC of the chromatographic peak in a specific sample. See also examples below.

Parameters include, filled, n and value are only supported for object being an XCMSnExp.

When extracting EICs from only the top n samples it can happen that one or more of the features specified with features are dropped because they have no detected peak in the top n samples. The chance for this to happen is smaller if x contains also filled-in peaks (with fillChromPeaks).

Author(s)

Johannes Rainer

Examples


## Load a test data set with detected peaks
library(xcms)
library(MsExperiment)
faahko_sub <- loadXcmsData("faahko_sub2")

## Disable parallel processing for this example
register(SerialParam())

## Perform correspondence analysis
xdata <- groupChromPeaks(faahko_sub,
    param = PeakDensityParam(minFraction = 0.8, sampleGroups = rep(1, 3)))

## Get the feature definitions
featureDefinitions(xdata)

## Extract ion chromatograms for the first 3 features. Parameter
## `features` can be either the feature IDs or feature indices.
chrs <- featureChromatograms(xdata,
    features = rownames(featureDefinitions)[1:3])

## Plot the EIC for the first feature using different colors for each file.
plot(chrs[1, ], col = c("red", "green", "blue"))

## The EICs for all 3 samples use the same m/z and retention time range,
## which was defined using the `featureArea` function:
featureArea(xdata, features = rownames(featureDefinitions(xdata))[1:3],
    mzmin = min, mzmax = max, rtmin = min, rtmax = max)

## To extract the actual (exact) EICs for each chromatographic peak of
## a feature in each sample, the `chromPeakChromatograms` function would
## need to be used instead. Below we extract the EICs for all
## chromatographic peaks of the first feature. We need to first get the
## IDs of all chromatographic peaks assigned to the first feature:
peak_ids <- rownames(chromPeaks(xdata))[featureDefinitions(xdata)$peakidx[[1L]]]

## We can now pass these to the `chromPeakChromatograms` function with
## parameter `peaks`:
eic_1 <- chromPeakChromatograms(xdata, peaks = peak_ids)

## To plot these into a single plot we need to use the
## `plotChromatogramsOverlay` function:
plotChromatogramsOverlay(eic_1)

sneumann/xcms documentation built on Nov. 3, 2024, 10:33 p.m.