% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Chromatograms.R
\name{Chromatograms}
\alias{Chromatograms}
\alias{Chromatograms-class}
\alias{[,Chromatograms-method}
\alias{[<-,Chromatograms-method}
\alias{[[,Chromatograms-method}
\alias{[[<-,Chromatograms-method}
\alias{chromExtract}
\alias{filterEmptyChromatograms}
\alias{Chromatograms,ChromBackendOrMissing-method}
\alias{Chromatograms,Spectra-method}
\alias{setBackend,Chromatograms,ChromBackend-method}
\alias{$,Chromatograms-method}
\alias{$<-,Chromatograms-method}
\alias{factorize,Chromatograms-method}
\alias{chromExtract,Chromatograms-method}
\alias{filterEmptyChromatograms,Chromatograms-method}
\title{The Chromatograms class to manage and access chromatographic data}
\usage{
\S4method{Chromatograms}{ChromBackendOrMissing}(object = ChromBackendMemory(), processingQueue = list(), ...)

\S4method{Chromatograms}{Spectra}(
  object,
  summarize.method = c("sum", "max"),
  chromData = data.frame(),
  factorize.by = c("msLevel", "dataOrigin"),
  spectraVariables = character(),
  ...
)

\S4method{setBackend}{Chromatograms,ChromBackend}(
  object,
  backend,
  f = processingChunkFactor(object),
  BPPARAM = SerialParam(),
  ...
)

\S4method{$}{Chromatograms}(x, name)

\S4method{$}{Chromatograms}(x, name) <- value

\S4method{[}{Chromatograms}(x, i, j, ..., drop = FALSE)

\S4method{[[}{Chromatograms}(x, i, j, ...)

\S4method{[[}{Chromatograms}(x, i, j, ...) <- value

\S4method{factorize}{Chromatograms}(object, factorize.by = c("msLevel", "dataOrigin"), ...)

\S4method{chromExtract}{Chromatograms}(object, peak.table, by, ...)

\S4method{filterEmptyChromatograms}{Chromatograms}(object, ...)
}
\arguments{
\item{object}{A \link{Chromatograms} object.}

\item{processingQueue}{\link{list} a list of processing steps (i.e. functions) to
be applied to the chromatographic data. The processing steps are
applied in the order they are listed in the \code{processingQueue}.}

\item{...}{Additional arguments.}

\item{summarize.method}{For \code{Chromatograms} created with a \code{Spectra} object:
A \code{character} vector with the name of the function to be used to
summaries the spectra data intensity. The available methods are "sum"
and "max". The default is "sum".}

\item{chromData}{For \code{Chromatograms()} build from a \code{Spectra} object backend,
a \code{data.frame} with the chromatographic data. If not provided
(or if empty), a default \code{data.frame} with the core chromatographic
variables will be created.}

\item{factorize.by}{A \code{character} vector with the names of the variables in
the \code{Spectra} object and the \code{chromData} slot that should be used
to factorize the \code{Spectra} object data to generate the
chromatographic data.}

\item{spectraVariables}{A \code{character} vector specifying which variables
from the \code{Spectra} object should be added to the chromData. These
will be mapped using the \code{chromSpectraIndex} variable.}

\item{backend}{\link{ChromBackend} object providing the raw data for the
\code{Chromatograms} object.}

\item{f}{\code{factor} defining the grouping to split the \code{Chromatograms} object.}

\item{BPPARAM}{Parallel setup configuration. See \code{\link[BiocParallel:register]{BiocParallel::bpparam()}}
for more information.}

\item{x}{A \link{Chromatograms} object.}

\item{name}{A \code{character} string specifying the name of the variable to
access.}

\item{value}{The value to replace the variable with.}

\item{i}{For \code{[}: \code{integer}, \code{logical} or \code{character} to subset the object.}

\item{j}{For \code{[} and \code{[[}: ignored.}

\item{drop}{For \code{[}: \code{logical(1)} default to \code{FALSE}.}

\item{peak.table}{For \code{chromExtract()} A \verb{data frame} containing the
following minimum columns:
- rtMin: Minimum retention time for each peak. Cannot be NA.
- rtMax: Maximum retention time for each peak. Cannot be NA.
- mzMin: Minimum m/z value for each peak.
- mzMax: Maximum m/z value for each peak.
Additionally, the \code{peak.table} must include columns that uniquely
identify chromatograms in the \code{object}. Common choices are
"msLevel" and/or "dataOrigin". These columns must also be present
in the \code{chromData} of the \code{object}. Any extra columns in
\code{peak.table} will be added to the \code{chromData} of the newly created
object.}

\item{by}{A \code{character} vector naming one or more columns that uniquely
identify chromatograms in both \code{peak.table} and
\code{chromData(object)}. The combination of these columns must be unique
within \code{chromData(object)}. Typically includes \code{"dataOrigin"},
\code{"msLevel"}, or both.}
}
\value{
Refer to the individual function description for information on
the return value.
}
\description{
The \code{Chromatograms} class encapsules chromatographic data and related
metadata. The chromatographic data is represented by a \emph{backend} extending
the virtual \link{ChromBackend} class which provides the raw data to the
\code{Chromatograms} object. Different backends and their properties are
described in the \link{ChromBackend} class documentation.

\strong{Available Backends}: The package provides several backends:
\itemize{
\item \code{ChromBackendMemory}: Stores data in memory (default, ideal for small datasets).
\item \code{ChromBackendMzR}: Reads peaks data from raw MS files on demand.
\item \code{ChromBackendSpectra}: Generates chromatographic data from a \code{Spectra} object.
This backend supports both in-memory and file-backed \code{Spectra} objects, using
an internal \code{spectraSortIndex} to avoid physically reordering the spectra.
}
}
\note{
This needs to be discussed, if we want for example to be able to set a
a backend to \code{ChromBackendMzR} we need to implement backendInitialize()
better. = Support peaksData and chromData as arguments AND have a way to
write .mzml files (which we do not have for chromatographic data).
}
\section{Creation of objects}{


\code{Chromatograms} objects can be created using the \code{Chromatograms()}
construction function. Either by providing a \code{ChromBackend} object or by
providing a \code{Spectra} object. The \code{Spectra} object will be used to generate
a \code{Chromatograms} object with a backend of class \code{\link{ChromBackendSpectra}}.
}

\section{Data stored in a \code{Chromatograms} object}{


The \code{Chromatograms} object is a container for chromatographic data, which
includes peaks data (\emph{retention time} and related intensity values, also
referred to as \emph{peaks data variables} in the context of \code{Chromatograms}) and
metadata of individual chromatogram (so called \emph{chromatograms variables}).
While a core set of chromatograms variables (the
\code{coreChromatogramsVariables()}) and peaks data variables (the
\code{corePeaksVariables()}) are guaranteed to be provided by a \code{Chromatograms},
it is possible to add arbitrary variables to a \code{Chromatograms} object.

The \code{Chromatograms} object is designed to contain chromatographic data of a
(large) set of chromatograms. The data is organized \emph{linearly} and can be
thought of a list of chromatograms, i.e. each element in the \code{Chromatograms}
is one chromatogram.

The \emph{chromatograms variables} information in the \code{Chromatograms} object can
be accessed using the \code{chromData()} function. Specific chromatograms
variables can be accessed by either precising the \code{"columns"} parameter in
\code{chromData()} or using \code{$}. \verb{@chromData} can be accessed, replaced but
also filtered/subsetted. Refer to the \link{chromData} documentation for more
details.

The \emph{peaks data variables} information in the \code{Chromatograms} object can be
accessed using the \code{peaksData()} function. Specific peaks variables can be
accessed by either precising the \code{"columns"} parameter in \code{peaksData()} or
using \code{$}. \verb{@peaksData} can be accessed, replaced but also
filtered/subsetted. Refer to the \link{peaksData} documentation for more details.
}

\section{Processing of \code{Chromatograms} objects}{


Functions that process the chromatograms data in some ways can be applied to
the object either directly or by using the \code{processingQueue} mechanism. The
\verb{@processingQueue} is a list of processing steps that are stored within the
object and only applied when needed. This was created so that the data can be
processed in a single step and is very useful for larger datasets. This is
even more true as this processing queue will call function that can be
applied on the data in a chunk-wise manner. This allows for parallel
processing of the data and reduces the memory demand. To read more about the
\code{processingQueue}, and how to parallelize your processes, see the
\link{processingQueue} documentation.
}

\section{Subsetting and accessing data}{

The \code{Chromatograms} class supports subsetting by chromatogram (i.e. rows) using
the \code{[} operator. The \code{[} operator does not support subsetting by columns.
Specific chromatograms or peaks variables can be accessed using the \code{[[}
operator or the \code{$} operator. The \code{[[} operator can also be used to
replace specific chromatograms or peaks variables.
}

\section{Changing the backend}{

The \code{setBackend()} function can be used to change the backend of a
\code{Chromatograms} object. This can be useful to switch to a backend that
better suits the needs of the user, for example switching to a memory-based
backend for smaller datasets or to a file-based backend for larger datasets.
The \code{setBackend()} function supports parallelization of the backend
conversion using the \code{BPPARAM} parameter. Note that any queued processing
steps are applied during the backend switch (since \code{peaksData()} is called
to transfer the data) and the processing queue is emptied afterwards.
}

\section{Filtering chromatograms}{

\itemize{
\item \code{filterEmptyChromatograms()}: removes empty chromatograms (i.e.
chromatograms without peaks) from the object. Returns the filtered
\code{Chromatograms} object (with chromatograms in their original order).
}
}

\section{Extracting chromatograms based on a peak table}{


The \code{chromExtract()} function allows users to extract specific regions of
interest from a \code{Chromatograms} object based on a user-provided peak table.
Each row in the \code{peak.table} defines a region to extract, using minimum and
maximum retention time (and m/z in the case of \code{chromBackendSpectra})
boundaries, and identifiers that uniquely match chromatograms in the object.

The resulting \strong{new} \code{Chromatograms} object contains only chromatograms
overlapping the specified regions, with updated metadata reflecting the
extracted boundaries.

This function is most commonly used to subset chromatographic data around
detected peaks or predefined time/mass ranges, for example to reprocess,
visualize, or quantify extracted chromatograms corresponding to known
features. It's important to notes that filtering by m/z is only supported
when using a \code{ChromBackendSpectra} backend. if the \code{mzMin} and \code{mzMax}
columns are provided when using other backends, they will be ignored.
}

\examples{

## Create a Chromatograms object with ChromBackendMemory
cdata <- data.frame(
    msLevel = c(1L, 1L, 1L),
    mz = c(112.2, 123.3, 134.4),
    dataOrigin = c("mem1", "mem2", "mem3")
)
pdata <- list(
    data.frame(rtime = c(2.1, 2.5, 3.0, 3.4, 3.9),
               intensity = c(100, 250, 400, 300, 150)),
    data.frame(rtime = c(3.5, 4.0, 4.5),
               intensity = c(80, 120, 90)),
    data.frame(rtime = c(5.1, 5.8, 6.3, 6.9, 7.5),
               intensity = c(80, 500, 1200, 600, 120))
)
chr <- Chromatograms(ChromBackendMemory(), chromData = cdata, peaksData = pdata)
chr

## Create a Chromatograms object from a Spectra object
library(MsBackendMetaboLights)
library(Spectra)

be <- backendInitialize(MsBackendMetaboLights(),
    mtblsId = "MTBLS39",
    filePattern = c("63B.cdf")
)
s <- Spectra(be)
s <- setBackend(s, MsBackendMemory())
chr <- Chromatograms(s)

## Subset
chr[1:2]

## Access a specific variable
chr[["msLevel"]]
chr$msLevel

## Replace data of a specific variable
chr$msLevel <- c(2L, 2L, 2L)

## Re-factorize the data
chr <- factorize(chr)

## Change the backend to memory
chr <- setBackend(chr, ChromBackendMemory())

}
\seealso{
\link{chromData} for a general description of the chromatographic
metadata available in the object, as well as how to access, replace
and subset them.
\link{peaksData} for a general description of the chromatographic peaks
data available in the object, as well as how to access, replace and
subset them.
\link{processingQueue} for more information on the queuing of
processings and parallelization for larger dataset.
}
