chromatogram,XCMSnExp-method {xcms} | R Documentation

## Extracting chromatograms

### Description

`chromatogram`: extract chromatographic data (such as an extracted ion chromatogram, a base peak chromatogram or total ion chromatogram) from an OnDiskMSnExp or XCMSnExp objects. See also the help page of the `chromatogram` function in the `MSnbase` package.

### Usage

    ## S4 method for signature 'XCMSnExp'
    chromatogram(
      object,
      rt,
      mz,
      aggregationFun = "sum",
      missing = NA_real_,
      msLevel = 1L,
      BPPARAM = bpparam(),
      adjustedRtime = hasAdjustedRtime(object),
      filled = FALSE,
      include = c("apex_within", "any", "none")
    )

### Arguments

`object` | Either a OnDiskMSnExp or XCMSnExp object from which the chromatograms should be extracted.
`rt` | `numeric(2)` or two-column `matrix` defining the lower and upper boundary for the retention time range(s). If not specified, the full retention time range of the original data will be used.
`mz` | `numeric(2)` or two-column `matrix` defining the lower and upper mz value for the MS data slice(s). If not specified, the chromatograms will be calculated on the full mz range.
`aggregationFun` | `character(1)` specifying the function to be used to aggregate intensity values across the mz value range for the same retention time. Allowed values are `"sum"` (the default), `"max"`, `"mean"` and `"min"`.
`missing` | `numeric(1)` allowing to specify the intensity value to be used if for a given retention time no signal was measured within the mz range of the corresponding scan. Defaults to `NA_real_` (see also Details and Notes sections below). Use `missing = 0` to resemble the behaviour of the `getEIC` from the old user interface.
`msLevel` | `integer(1)` specifying the MS level from which the chromatogram should be extracted. Defaults to `msLevel = 1L`.
`BPPARAM` | Parallelisation backend to be used, which will depend on the architecture. Default is `BiocParallel::bparam()`.
`adjustedRtime` | For `chromatogram,XCMSnExp`: whether the adjusted (`adjustedRtime = TRUE`) or raw retention times (`adjustedRtime = FALSE`) should be used for filtering and returned in the resulting MChromatograms object. Adjusted retention times are used by default if available.
`filled` | `logical(1)` whether filled-in peaks should also be returned. Defaults to `filled = FALSE`, i.e. returns only detected chromatographic peaks in the result object.
`include` | `character(1)` defining which chromatographic peaks should be returned. Supported are `include = "apex_within"` (the default) which returns chromatographic peaks that have their apex within the `mz` `rt` range, `include = "any"` to return all chromatographic peaks which m/z and rt ranges overlap the `mz` and `rt` or `include = "none"` to not include any chromatographic peaks.

### Details

Arguments `rt` and `mz` allow to specify the MS data slice (i.e. the m/z range and retention time window) from which the chromatogram should be extracted. These parameters can be either a `numeric` of length 2 with the lower and upper limit, or a `matrix` with two columns with the lower and upper limits to extract multiple EICs at once. The parameter `aggregationSum` allows to specify the function to be used to aggregate the intensities across the m/z range for the same retention time. Setting `aggregationFun = "sum"` would e.g. allow to calculate the total ion chromatogram (TIC), `aggregationFun = "max"` the base peak chromatogram (BPC).

If for a given retention time no intensity is measured in that spectrum a `NA` intensity value is returned by default. This can be changed with the parameter `missing`, setting `missing = 0` would result in a `0` intensity being returned in these cases.

### Value

`chromatogram` returns a XChromatograms object with the number of columns corresponding to the number of files in `object` and number of rows the number of specified ranges (i.e. number of rows of matrices provided with arguments `mz` and/or `rt`). All chromatographic peaks with their apex position within the m/z and retention time range are also retained as well as all feature definitions for these peaks.

### Note

For XCMSnExp objects, if adjusted retention times are available, the `chromatogram` method will by default report and use these (for the subsetting based on the provided parameter `rt`). This can be changed by setting `adjustedRtime = FALSE`.

### Author(s)

Johannes Rainer

### See Also

XCMSnExp for the data object. Chromatogram for the object representing chromatographic data.

    [XChromatograms] for the object allowing to arrange
    multiple [XChromatogram] objects.

    [plot] to plot a [XChromatogram] or [MChromatograms] objects.

    `as` (`as(x, "data.frame")`) in `MSnbase` for a method to extract
    the MS data as `data.frame`.

### Examples

    ## Load a test data set with identified chromatographic 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())

    ## Extract the ion chromatogram for one chromatographic peak in the data.
    chrs <- chromatogram(faahko_sub, rt = c(2700, 2900), mz = 335)

    chrs

    ## Identified chromatographic peaks
    chromPeaks(chrs)

    ## Plot the chromatogram
    plot(chrs)

    ## Extract chromatograms for multiple ranges.
    mzr <- matrix(c(335, 335, 344, 344), ncol = 2, byrow = TRUE)
    rtr <- matrix(c(2700, 2900, 2600, 2750), ncol = 2, byrow = TRUE)
    chrs <- chromatogram(faahko_sub, mz = mzr, rt = rtr)

    chromPeaks(chrs)

    plot(chrs)

    ## Get access to all chromatograms for the second mz/rt range
    chrs[1, ]

    ## Plot just that one
    plot(chrs[1, , drop = FALSE])

[Package xcms version 3.16.1 Index]