% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/DataClasses.R, R/functions-Params.R,
%   R/functions-XCMSnExp.R, R/methods-Params.R, R/methods-XCMSnExp.R
\docType{class}
\name{adjustRtime-peakGroups}
\alias{adjustRtime-peakGroups}
\alias{PeakGroupsParam-class}
\alias{PeakGroupsParam}
\alias{adjustRtimePeakGroups}
\alias{show,PeakGroupsParam-method}
\alias{minFraction,PeakGroupsParam-method}
\alias{minFraction<-,PeakGroupsParam-method}
\alias{extraPeaks,PeakGroupsParam-method}
\alias{extraPeaks}
\alias{extraPeaks<-,PeakGroupsParam-method}
\alias{extraPeaks<-}
\alias{smooth,PeakGroupsParam-method}
\alias{smooth}
\alias{smooth<-,PeakGroupsParam-method}
\alias{smooth<-}
\alias{span,PeakGroupsParam-method}
\alias{span}
\alias{span<-,PeakGroupsParam-method}
\alias{span<-}
\alias{family,PeakGroupsParam-method}
\alias{family}
\alias{family<-,PeakGroupsParam-method}
\alias{family<-}
\alias{peakGroupsMatrix,PeakGroupsParam-method}
\alias{peakGroupsMatrix}
\alias{peakGroupsMatrix<-,PeakGroupsParam-method}
\alias{peakGroupsMatrix<-}
\alias{subset,PeakGroupsParam-method}
\alias{subset}
\alias{subset<-,PeakGroupsParam-method}
\alias{subset<-}
\alias{subsetAdjust,PeakGroupsParam-method}
\alias{subsetAdjust}
\alias{subsetAdjust<-,PeakGroupsParam-method}
\alias{subsetAdjust<-}
\alias{adjustRtime,XCMSnExp,PeakGroupsParam-method}
\title{Retention time correction based on alignment of house keeping peak
groups}
\usage{
PeakGroupsParam(minFraction = 0.9, extraPeaks = 1, smooth = "loess",
  span = 0.2, family = "gaussian", peakGroupsMatrix = matrix(nrow =
  0, ncol = 0), subset = integer(), subsetAdjust = c("average",
  "previous"))

adjustRtimePeakGroups(object, param = PeakGroupsParam(), msLevel = 1L)

\S4method{show}{PeakGroupsParam}(object)

\S4method{minFraction}{PeakGroupsParam}(object)

\S4method{minFraction}{PeakGroupsParam}(object) <- value

\S4method{extraPeaks}{PeakGroupsParam}(object)

\S4method{extraPeaks}{PeakGroupsParam}(object) <- value

\S4method{smooth}{PeakGroupsParam}(x)

\S4method{smooth}{PeakGroupsParam}(object) <- value

\S4method{span}{PeakGroupsParam}(object)

\S4method{span}{PeakGroupsParam}(object) <- value

\S4method{family}{PeakGroupsParam}(object)

\S4method{family}{PeakGroupsParam}(object) <- value

\S4method{peakGroupsMatrix}{PeakGroupsParam}(object)

\S4method{peakGroupsMatrix}{PeakGroupsParam}(object) <- value

\S4method{subset}{PeakGroupsParam}(x)

\S4method{subset}{PeakGroupsParam}(object) <- value

\S4method{subsetAdjust}{PeakGroupsParam}(object)

\S4method{subsetAdjust}{PeakGroupsParam}(object) <- value

\S4method{adjustRtime}{XCMSnExp,PeakGroupsParam}(object, param,
  msLevel = 1L)
}
\arguments{
\item{minFraction}{\code{numeric(1)} between 0 and 1 defining the minimum
required fraction of samples in which peaks for the peak group were
identified. Peak groups passing this criteria will aligned across
samples and retention times of individual spectra will be adjusted
based on this alignment. For \code{minFraction = 1} the peak group
has to contain peaks in all samples of the experiment. Note that if
\code{subset} is provided, the specified fraction is relative to the
defined subset of samples and not to the total number of samples within
the experiment (i.e. a peak has to be present in the specified
proportion of subset samples).}

\item{extraPeaks}{\code{numeric(1)} defining the maximal number of
additional peaks for all samples to be assigned to a peak group (i.e.
feature) for retention time correction. For a data set with 6 samples,
\code{extraPeaks = 1} uses all peak groups with a total peak count
\code{<= 6 + 1}. The total peak count is the total number of peaks being
assigned to a peak group and considers also multiple peaks within a
sample being assigned to the group.}

\item{smooth}{character defining the function to be used, to interpolate
corrected retention times for all peak groups. Either \code{"loess"} or
\code{"linear"}.}

\item{span}{\code{numeric(1)} defining the degree of smoothing (if
\code{smooth = "loess"}). This parameter is passed to the internal call
to \code{\link{loess}}.}

\item{family}{character defining the method to be used for loess smoothing.
Allowed values are \code{"gaussian"} and \code{"symmetric"}.See
\code{\link{loess}} for more information.}

\item{peakGroupsMatrix}{optional \code{matrix} of (raw) retention times for
the peak groups on which the alignment should be performed. Each column
represents a sample, each row a feature/peak group. Such a matrix is
for example returned by the \code{\link{adjustRtimePeakGroups}} method.}

\item{subset}{\code{integer} with the indices of samples within the
experiment on which the alignment models should be estimated. Samples
not part of the subset are adjusted based on the closest subset sample.
See description above for more details.}

\item{subsetAdjust}{\code{character} specifying the method with which
non-subset samples should be adjusted. Supported options are
\code{"previous"} and \code{"average"} (default). See description above
for more information.}

\item{object}{For \code{adjustRtime}: an \code{\link{XCMSnExp}} object
    containing the results from a previous chromatographic peak detection
    (see \code{\link{findChromPeaks}}) and alignment analysis (see
    \code{\link{groupChromPeaks}}).

    For all other methods: a \code{PeakGroupsParam} object.}

\item{param}{A \code{PeakGroupsParam} object containing all settings for
the retention time correction method..}

\item{msLevel}{\code{integer(1)} specifying the MS level. Currently only MS
level 1 is supported.}

\item{value}{The value for the slot.}

\item{x}{a \code{PeakGroupsParam} object.}
}
\value{
The \code{PeakGroupsParam} function returns a
    \code{PeakGroupsParam} class instance with all of the settings
    specified for retention time adjustment based on \emph{house keeping}
    features/peak groups.

For \code{adjustRtimePeakGroups}: a \code{matrix}, rows being
features, columns samples, of retention times. The features are ordered
by the median retention time across columns.

For \code{adjustRtime}: a \code{\link{XCMSnExp}} object with the
results of the retention time adjustment step. These can be accessed
with the \code{\link{adjustedRtime}} method. Retention time correction
does also adjust the retention time of the identified chromatographic
peaks (accessed \emph{via} \code{\link{chromPeaks}}. Note that retention
time correction drops all previous alignment results from the result
object.
}
\description{
This method performs retention time adjustment based on the
alignment of chromatographic peak groups present in all/most samples
(hence corresponding to house keeping compounds). First the retention
time deviation of these peak groups is described by fitting either a
polynomial (\code{smooth = "loess"}) or a linear (
\code{smooth = "linear"}) model to the data points. These models are
subsequently used to adjust the retention time of each spectrum in
each sample.

It is also possible to exclude certain samples within an experiment from
the estimation of the alignment models. The parameter \code{subset}
allows to define the indices of samples within \code{object} that should
be aligned. Samples not part of this \code{subset} are left out in the
estimation of the alignment models, but their retention times are
subsequently adjusted based on the alignment results of the closest sample
in \code{subset} (close in terms of position within the \code{object}).
Alignment could thus be performed on only \emph{real} samples leaving out
e.g. blanks, which are then in turn adjusted based on the closest real
sample. Here it is up to the user to ensure that the samples within
\code{object} are ordered correctly (e.g. by injection index).

How the non-subset samples are adjusted bases also on the parameter
\code{subsetAdjust}: with \code{subsetAdjust = "previous"}, each non-subset
sample is adjusted based on the closest previous subset sample which results
in most cases with adjusted retention times of the non-subset sample being
identical to the subset sample on which the adjustment bases. The second,
default, option is to use \code{subsetAdjust = "average"} in which case
each non subset sample is adjusted based on the average retention time
adjustment from the previous and following subset sample. For the average
a weighted mean is used with weights being the inverse of the distance of
the non-subset sample to the subset samples used for alignment.

See also section \emph{Alignment of experiments including blanks} in the
\emph{xcms} vignette for an example.

The \code{PeakGroupsParam} class allows to specify all
    settings for the retention time adjustment based on \emph{house keeping}
    peak groups present in most samples.
    Instances should be created with the \code{PeakGroupsParam} constructor.

\code{adjustRtimePeakGroups} returns the features (peak groups)
which would, depending on the provided \code{\link{PeakGroupsParam}}, be
selected for alignment/retention time correction.

\code{minFraction},\code{minFraction<-}: getter and setter
    for the \code{minFraction} slot of the object.

\code{extraPeaks},\code{extraPeaks<-}: getter and setter
    for the \code{extraPeaks} slot of the object.

\code{smooth},\code{smooth<-}: getter and setter
    for the \code{smooth} slot of the object.

\code{span},\code{span<-}: getter and setter
    for the \code{span} slot of the object.

\code{family},\code{family<-}: getter and setter
    for the \code{family} slot of the object.

\code{peakGroupsMatrix},\code{peakGroupsMatrix<-}: getter and
    setter for the \code{peakGroupsMatrix} slot of the object.

\code{subset},\code{subset<-}: getter and
    setter for the \code{subset} slot of the object.

\code{subsetAdjust},\code{subsetAdjust<-}: getter and
    setter for the \code{subsetAdjust} slot of the object.

\code{adjustRtime,XCMSnExp,PeakGroupsParam}:
performs retention time correction based on the alignment of peak groups
(features) found in all/most samples. The correction function identified
on these peak groups is applied to the retention time of all spectra in
the object, i.e. retention times of all spectra, also MS level > 1 are
adjusted.
}
\section{Slots}{

\describe{
\item{\code{.__classVersion__,minFraction,extraPeaks,smooth,span,family,peakGroupsMatrix,subset,subsetAdjust}}{See corresponding parameter above. \code{.__classVersion__} stores
the version from the class. Slots values should exclusively be accessed
\emph{via} the corresponding getter and setter methods listed above.}
}}

\note{
These methods and classes are part of the updated and modernized
\code{xcms} user interface which will eventually replace the
\code{\link{group}} methods. All of the settings to the alignment
algorithm can be passed with a \code{PeakGroupsParam} object.

The matrix with the (raw) retention times of the peak groups used
in the alignment is added to the \code{peakGroupsMatrix} slot of the
\code{PeakGroupsParam} object that is stored into the corresponding
\emph{process history step} (see \code{\link{processHistory}} for how
to access the process history).

\code{adjustRtimePeakGroups} is supposed to be called \emph{before} the
sample alignment, but after a correspondence (peak grouping).

This method requires that a correspondence analysis has been performed
on the data, i.e. that grouped chromatographic peaks/features are present
(see \code{\link{groupChromPeaks}} for details).

Calling \code{adjustRtime} on an \code{XCMSnExp} object will cause all
peak grouping (correspondence) results and any previous retention time
adjustments to be dropped.
In some instances, the \code{adjustRtime,XCMSnExp,PeakGroupsParam}
re-adjusts adjusted retention times to ensure them being in the same
order than the raw (original) retention times.
}
\examples{
##############################
## Chromatographic peak detection and grouping.
##
## Below we perform first a peak detection (using the matchedFilter
## method) on some of the test files from the faahKO package followed by
## a peak grouping.
library(faahKO)
library(xcms)
fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE,
           full.names = TRUE)

## Reading 2 of the KO samples
raw_data <- readMSData(fls[1:2], mode = "onDisk")

## Perform the peak detection using the matchedFilter method.
mfp <- MatchedFilterParam(snthresh = 20, binSize = 1)
res <- findChromPeaks(raw_data, param = mfp)

head(chromPeaks(res))
## The number of peaks identified per sample:
table(chromPeaks(res)[, "sample"])

## Performing the peak grouping using the "peak density" method.
p <- PeakDensityParam(sampleGroups = c(1, 1))
res <- groupChromPeaks(res, param = p)

## Perform the retention time adjustment using peak groups found in both
## files.
fgp <- PeakGroupsParam(minFraction = 1)

## Before running the alignment we can evaluate which features (peak groups)
## would be used based on the specified parameters.
pkGrps <- adjustRtimePeakGroups(res, param = fgp)

## We can also plot these to evaluate if the peak groups span a large portion
## of the retention time range.
plot(x = pkGrps[, 1], y = rep(1, nrow(pkGrps)), xlim = range(rtime(res)),
    ylim = c(1, 2), xlab = "rt", ylab = "", yaxt = "n")
points(x = pkGrps[, 2], y = rep(2, nrow(pkGrps)))
segments(x0 = pkGrps[, 1], x1 = pkGrps[, 2],
    y0 = rep(1, nrow(pkGrps)), y1 = rep(2, nrow(pkGrps)))
grid()
axis(side = 2, at = c(1, 2), labels = colnames(pkGrps))

## Next we perform the alignment.
res <- adjustRtime(res, param = fgp)

## Any grouping information was dropped
hasFeatures(res)

## Plot the raw against the adjusted retention times.
plot(rtime(raw_data), rtime(res), pch = 16, cex = 0.25, col = fromFile(res))

## Adjusterd retention times can be accessed using
## rtime(object, adjusted = TRUE) and adjustedRtime
all.equal(rtime(res), adjustedRtime(res))

## To get the raw, unadjusted retention times:
all.equal(rtime(res, adjusted = FALSE), rtime(raw_data))

## To extract the retention times grouped by sample/file:
rts <- rtime(res, bySample = TRUE)
}
\references{
Colin A. Smith, Elizabeth J. Want, Grace O'Maille, Ruben Abagyan and
Gary Siuzdak. "XCMS: Processing Mass Spectrometry Data for Metabolite
Profiling Using Nonlinear Peak Alignment, Matching, and Identification"
\emph{Anal. Chem.} 2006, 78:779-787.
}
\seealso{
The \code{\link{do_adjustRtime_peakGroups}} core
    API function and \code{\link{retcor.peakgroups}} for the old user
    interface.
    \code{\link{plotAdjustedRtime}} for visualization of alignment results.

\code{\link{XCMSnExp}} for the object containing the results of
    the alignment.

Other retention time correction methods: \code{\link{adjustRtime-obiwarp}},
  \code{\link{adjustRtime}}
}
\author{
Colin Smith, Johannes Rainer
}
\concept{retention time correction methods}
