% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods-XCMSnExp.R
\docType{methods}
\name{chromatogram,XCMSnExp-method}
\alias{chromatogram,XCMSnExp-method}
\alias{chromatogram}
\title{Extracting chromatograms}
\usage{
\S4method{chromatogram}{XCMSnExp}(object, rt, mz, aggregationFun = "sum",
  missing = NA_real_, msLevel = 1L, BPPARAM = bpparam(),
  adjustedRtime = hasAdjustedRtime(object), filled = FALSE)
}
\arguments{
\item{object}{Either a \code{\link{OnDiskMSnExp}} or
\code{\link{XCMSnExp}} object from which the chromatograms should be
extracted.}

\item{rt}{\code{numeric(2)} or two-column \code{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 \code{numeric(1)} in which case
\code{range} is called on it to transform it to a \code{numeric(2)}.}

\item{mz}{\code{numeric(2)} or two-column \code{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 \code{numeric(1)} in which case
\code{range} is called on it to transform it to a \code{numeric(2)}.}

\item{aggregationFun}{\code{character} specifying the function to be used to
aggregate intensity values across the mz value range for the same
retention time. Allowed values are \code{"sum"}, \code{"max"},
\code{"mean"} and \code{"min"}.}

\item{missing}{\code{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 \code{NA_real_} (see also
Details and Notes sections below). Use \code{missing = 0} to resemble the
behaviour of the \code{getEIC} from the \code{old} user interface.}

\item{msLevel}{\code{integer} specifying the MS level from which the
chromatogram should be extracted. Defaults to \code{msLevel = 1L}.}

\item{BPPARAM}{Parallelisation backend to be used, which will
depend on the architecture. Default is
\code{BiocParallel::bparam()}.}

\item{adjustedRtime}{For \code{chromatogram,XCMSnExp}: whether the
adjusted (\code{adjustedRtime = TRUE}) or raw retention times
(\code{adjustedRtime = FALSE}) should be used for filtering and returned
in the resulting \code{\link{Chromatogram}} object. Adjusted
retention times are used by default if available.}

\item{filled}{\code{logical(1)} whether filled-in peaks should also be
returned. Defaults to \code{filled = FALSE}, i.e. returns only detected
chromatographic peaks in the result object.}
}
\value{
\code{chromatogram} returns a \code{\link{XChromatograms}} object with
the number of columns corresponding to the number of files in
\code{object} and number of rows the number of specified ranges (i.e.
number of rows of matrices provided with arguments \code{mz} and/or
\code{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.
}
\description{
\code{chromatogram}: the method allows to extract
chromatograms from \code{\link{OnDiskMSnExp}} and
\code{\link{XCMSnExp}} objects. See also the
\code{\link{chromatogram}} implementation for
\code{\link{OnDiskMSnExp}} in the \code{MSnbase} package.
}
\details{
Arguments \code{rt} and \code{mz} allow to specify the MS
data slice from which the chromatogram should be extracted.
The parameter \code{aggregationSum} allows to specify the function to be
used to aggregate the intensities across the mz range for the same
retention time. Setting \code{aggregationFun = "sum"} would e.g. allow
to calculate the \emph{total ion chromatogram} (TIC),
\code{aggregationFun = "max"} the \emph{base peak chromatogram} (BPC).
The length of the extracted \code{\link{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 \code{NA_real_} is reported as intensity for the
retention time (see Notes for more information). This can be changed
using the \code{missing} parameter.
}
\note{
\code{\link{Chromatogram}} objects extracted with
\code{chromatogram}
contain \code{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 \code{Chromatogram} object
of length 0 is returned.

For \code{\link{XCMSnExp}} objects, if adjusted retention times are
available, the \code{chromatogram} method will by default report
and use these (for the subsetting based on the provided parameter
\code{rt}). This can be overwritten with the parameter
\code{adjustedRtime}.
}
\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")

## Subset to speed up processing
od <- filterRt(od, rt = c(2500, 3000))

## Perform peak detection using default CentWave parameters
xod <- findChromPeaks(od, param = CentWaveParam())

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

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(xod, mz = mzr, rt = rtr)

chrs <- chromatogram(xod, mz = mzr)

rtr[1, 1] <- 2785
chrs <- chromatogram(xod, 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])
}
\seealso{
\code{\link{XCMSnExp}} for the data object.
    \code{\link{Chromatogram}} for the object representing
    chromatographic data.

    \code{\link{XChromatograms}} for the object allowing to arrange
    multiple \code{XChromatogram} objects.

    \code{\link{plot}} to plot a \code{XChromatogram} or
    \code{Chromatograms} objects.

    \code{\link{as}} (\code{as(x, "data.frame")}) in \code{MSnbase}
    for a method to extract the MS data as \code{data.frame}.
}
\author{
Johannes Rainer
}
