chromatogram,XCMSnExp-method {xcms} | R Documentation

## Extracting chromatograms

### Description

`chromatogram`: the method allows to extract chromatograms from `OnDiskMSnExp` and `XCMSnExp` objects. See also the `chromatogram` implementation for `OnDiskMSnExp` 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))

### 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. It is also possible to submit a `numeric(1)` in which case `range` is called on it to transform it to a `numeric(2)`.
`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. It is also possible to submit a `numeric(1)` in which case `range` is called on it to transform it to a `numeric(2)`.
`aggregationFun` | `character` specifying the function to be used to aggregate intensity values across the mz value range for the same retention time. Allowed values are `"sum"`, `"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` 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 `Chromatogram` object. Adjusted retention times are used by default if available.

### Details

Arguments `rt` and `mz` allow to specify the MS data slice from which the chromatogram should be extracted. The parameter `aggregationSum` allows to specify the function to be used to aggregate the intensities across the mz 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). The length of the extracted `Chromatogram` object, i.e. the number of available data points, corresponds to the number of scans/spectra measured in the specified retention time range. If in a specific scan (for a give retention time) no signal was measured in the specified mz range, a `NA_real_` is reported as intensity for the retention time (see Notes for more information). This can be changed using the `missing` parameter.

### Value

`chromatogram` returns a `Chromatograms` 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`).

### Note

`Chromatogram` objects extracted with `chromatogram` contain `NA_real_` values if, for a given retention time, no signal was measured in the specified mz range. If no spectrum/scan is present in the defined retention time window a `Chromatogram` object of length 0 is returned.

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 overwritten with the parameter `adjustedRtime`.

### Author(s)

Johannes Rainer

### See Also

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

`Chromatograms` for the object allowing to arrange multiple `Chromatogram` objects.

`plot` to plot a `Chromatogram` or `Chromatograms` objects.

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

### Examples

    ## Read some files from the faahKO package.
    library(xcms)
    library(faahKO)
    faahko_3_files <- c(system.file('cdf/KO/ko15.CDF', package = "faahKO"),
                        system.file('cdf/KO/ko16.CDF', package = "faahKO"),
                        system.file('cdf/KO/ko18.CDF', package = "faahKO"))

    od <- readMSData(faahko_3_files, mode = "onDisk")

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

    chrs

    ## Plot the chromatogram
    plot(rtime(chrs[1, 2]), intensity(chrs[1, 2]), type = "l", xlab = "rtime",
         ylab = "intensity", col = "000080")
    for(i in c(1, 3)) {
      points(rtime(chrs[1, i]), intensity(chrs[1, i]), type = "l",
      col = "00000080")
    }

    ## Plot the chromatogram using the dedicated plot method.
    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(od, mz = mzr, rt = rtr)

    chrs

    ## Plot the extracted chromatograms
    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.2.0 Index]