featureChromatograms {xcms} | R Documentation

## Extract ion chromatograms for each feature

### Description

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.

### Usage

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

### Arguments

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

### Value

`XChromatograms()` object.

### Note

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

### See Also

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

### Examples

    ## 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"))

[Package xcms version 3.16.1 Index]