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

Description Usage Arguments Value Note Author(s) See Also Examples

Extract ion chromatograms for features in an XCMSnExp object. The function returns for each feature its extracted ion chromatogram and all associated peaks with it. The chromatogram is extracted from the m/z - rt region including all chromatographic peaks of that features (i.e. based on the ranges of "mzmin", "mzmax", "rtmin", "rtmax" of all chromatographic peaks of the feature).

By default only chromatographic peaks associated with a feature are included for an extracted ion chromatogram (parameter include = "feature_only"). By setting include = "apex_within" all chromatographic peaks (and eventually the feature which they are part of - if feature definitions are present) that have their apex position within the m/z - rt range from which the chromatogram is extracted are returned too. With include = "any" or include = "all" all chromatographic peaks (and eventually the feature in which they are present) overlapping the m/z and rt range will be returned.

featureChromatograms(
  x,
  expandRt = 0,
  aggregationFun = "max",
  features,
  include = c("feature_only", "apex_within", "any", "all"),
  filled = FALSE,
  n = length(fileNames(x)),
  value = c("maxo", "into"),
  ...
)

`x`	`XCMSnExp` object with grouped chromatographic peaks.
`expandRt`	`numeric(1)` to expand the retention time range for each chromatographic peak by a constant value on each side.
`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 `"sum"` 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.
`include`	`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`	`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`	`integer(1)` to optionally specify the number of top n samples from which the EIC should be extracted.
`value`	`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.
`...`	optional arguments to be passed along to the `chromatogram()` function.

XChromatograms() object.

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

Johannes Rainer

filterColumnsKeepTop() to filter the extracted EICs keeping only the top n columns (samples) with the highest intensity.

## Load a test data set with detected peaks
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")

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

## Subset the object to a smaller retention time range
xdata <- filterRt(faahko_sub, c(2500, 3500))

xdata <- groupChromPeaks(xdata,
    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 = 1:3)

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