% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/DataClasses.R, R/functions-Params.R,
%   R/methods-OnDiskMSnExp.R, R/methods-Params.R, R/methods-XCMSnExp.R
\docType{class}
\name{adjustRtime-obiwarp}
\alias{adjustRtime-obiwarp}
\alias{ObiwarpParam-class}
\alias{ObiwarpParam}
\alias{adjustRtime,OnDiskMSnExp,ObiwarpParam-method}
\alias{show,ObiwarpParam-method}
\alias{binSize,ObiwarpParam-method}
\alias{binSize<-,ObiwarpParam-method}
\alias{centerSample,ObiwarpParam-method}
\alias{centerSample}
\alias{centerSample<-,ObiwarpParam-method}
\alias{centerSample<-}
\alias{response,ObiwarpParam-method}
\alias{response}
\alias{response<-,ObiwarpParam-method}
\alias{response<-}
\alias{distFun,ObiwarpParam-method}
\alias{distFun}
\alias{distFun<-,ObiwarpParam-method}
\alias{distFun<-}
\alias{gapInit,ObiwarpParam-method}
\alias{gapInit}
\alias{gapInit<-,ObiwarpParam-method}
\alias{gapInit<-}
\alias{gapExtend,ObiwarpParam-method}
\alias{gapExtend}
\alias{gapExtend<-,ObiwarpParam-method}
\alias{gapExtend<-}
\alias{factorDiag,ObiwarpParam-method}
\alias{factorDiag}
\alias{factorDiag<-,ObiwarpParam-method}
\alias{factorDiag<-}
\alias{factorGap,ObiwarpParam-method}
\alias{factorGap}
\alias{factorGap<-,ObiwarpParam-method}
\alias{factorGap<-}
\alias{localAlignment,ObiwarpParam-method}
\alias{localAlignment}
\alias{localAlignment<-,ObiwarpParam-method}
\alias{localAlignment<-}
\alias{initPenalty,ObiwarpParam-method}
\alias{initPenalty}
\alias{initPenalty<-,ObiwarpParam-method}
\alias{initPenalty<-}
\alias{subset,ObiwarpParam-method}
\alias{subset<-,ObiwarpParam-method}
\alias{subsetAdjust,ObiwarpParam-method}
\alias{subsetAdjust<-,ObiwarpParam-method}
\alias{adjustRtime,XCMSnExp,ObiwarpParam-method}
\title{Align retention times across samples using Obiwarp}
\usage{
ObiwarpParam(binSize = 1, centerSample = integer(), response = 1L,
  distFun = "cor_opt", gapInit = numeric(), gapExtend = numeric(),
  factorDiag = 2, factorGap = 1, localAlignment = FALSE,
  initPenalty = 0, subset = integer(), subsetAdjust = c("average",
  "previous"))

\S4method{adjustRtime}{OnDiskMSnExp,ObiwarpParam}(object, param,
  msLevel = 1L)

\S4method{show}{ObiwarpParam}(object)

\S4method{binSize}{ObiwarpParam}(object)

\S4method{binSize}{ObiwarpParam}(object) <- value

\S4method{centerSample}{ObiwarpParam}(object)

\S4method{centerSample}{ObiwarpParam}(object) <- value

\S4method{response}{ObiwarpParam}(object)

\S4method{response}{ObiwarpParam}(object) <- value

\S4method{distFun}{ObiwarpParam}(object)

\S4method{distFun}{ObiwarpParam}(object) <- value

\S4method{gapInit}{ObiwarpParam}(object)

\S4method{gapInit}{ObiwarpParam}(object) <- value

\S4method{gapExtend}{ObiwarpParam}(object)

\S4method{gapExtend}{ObiwarpParam}(object) <- value

\S4method{factorDiag}{ObiwarpParam}(object)

\S4method{factorDiag}{ObiwarpParam}(object) <- value

\S4method{factorGap}{ObiwarpParam}(object)

\S4method{factorGap}{ObiwarpParam}(object) <- value

\S4method{localAlignment}{ObiwarpParam}(object)

\S4method{localAlignment}{ObiwarpParam}(object) <- value

\S4method{initPenalty}{ObiwarpParam}(object)

\S4method{initPenalty}{ObiwarpParam}(object) <- value

\S4method{subset}{ObiwarpParam}(x)

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

\S4method{subsetAdjust}{ObiwarpParam}(object)

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

\S4method{adjustRtime}{XCMSnExp,ObiwarpParam}(object, param,
  msLevel = 1L)
}
\arguments{
\item{binSize}{\code{numeric(1)} defining the bin size (in mz dimension)
to be used for the \emph{profile matrix} generation. See \code{step}
parameter in \code{\link{profile-matrix}} documentation for more details.}

\item{centerSample}{\code{integer(1)} defining the index of the center sample
in the experiment. It defaults to
\code{floor(median(1:length(fileNames(object))))}. Note that if
\code{subset} is used, the index passed with \code{centerSample} is
within these subset samples.}

\item{response}{\code{numeric(1)} defining the \emph{responsiveness} of
warping with \code{response = 0} giving linear warping on start and end
points and \code{response = 100} warping using all bijective anchors.}

\item{distFun}{character defining the distance function to be used. Allowed
values are \code{"cor"} (Pearson's correlation), \code{"cor_opt"}
(calculate only 10\% diagonal band of distance matrix; better runtime),
\code{"cov"} (covariance), \code{"prd"} (product) and \code{"euc"}
(Euclidian distance). The default value is \code{distFun = "cor_opt"}.}

\item{gapInit}{\code{numeric(1)} defining the penalty for gap opening. The
default value for \code{gapInit} depends on the value of \code{distFun}:
for \code{distFun = "cor"} and \code{distFun = "cor_opt"} it is
\code{0.3}, for \code{distFun = "cov"} and \code{distFun = "prd"}
\code{0.0} and for \code{distFun = "euc"} \code{0.9}.}

\item{gapExtend}{\code{numeric(1)} defining the penalty for gap enlargement.
The default value for \code{gapExtend} depends on the value of
\code{distFun}, for \code{distFun = "cor"} and
\code{distFun = "cor_opt"} it is \code{2.4}, for \code{distFun = "cov"}
\code{11.7}, for \code{distFun = "euc"} \code{1.8} and for
\code{distFun = "prd"} {7.8}.}

\item{factorDiag}{\code{numeric(1)} defining the local weight applied to
diagonal moves in the alignment.}

\item{factorGap}{\code{numeric(1)} defining the local weight for gap moves
in the alignment.}

\item{localAlignment}{\code{logical(1)} whether a local alignment should be
performed instead of the default global alignment.}

\item{initPenalty}{\code{numeric(1)} defining the penalty for initiating an
alignment (for local alignment only).}

\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.

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

\item{param}{A \code{ObiwarpParam} object containing all settings for
the alignment method.}

\item{msLevel}{\code{integer} defining the MS level on which the retention
time should be performed.}

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

\item{x}{a \code{PeakGroupsParam} object.}
}
\value{
The \code{ObiwarpParam} function returns a
    \code{ObiwarpParam} class instance with all of the settings
    specified for obiwarp retention time adjustment and alignment.

For \code{adjustRtime,XCMSnExp,ObiwarpParam}: 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 peak grouping results from the result
object.

For \code{adjustRtime,OnDiskMSnExp,ObiwarpParam}: a \code{numeric} with
the adjusted retention times per spectra (in the same order than
\code{rtime}).
}
\description{
This method performs retention time adjustment using the
Obiwarp method [Prince 2006]. It is based on the code at
\url{http://obi-warp.sourceforge.net} but supports alignment of multiple
samples by aligning each against a \emph{center} sample. The alignment is
performed directly on the \code{\link{profile-matrix}} and can hence be
performed independently of the peak detection or peak grouping.

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{ObiwarpParam} class allows to specify all
    settings for the retention time adjustment based on the \emph{obiwarp}
    method. Class Instances should be created using the
    \code{ObiwarpParam} constructor.

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

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

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

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

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

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

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

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

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

\code{initPenalty},\code{initPenalty<-}: getter and setter
    for the \code{initPenalty} 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,ObiwarpParam}:
performs retention time correction/alignment based on the total mz-rt
data using the \emph{obiwarp} method.
}
\section{Slots}{

\describe{
\item{\code{.__classVersion__,binSize,centerSample,response,distFun,gapInit,gapExtend,factorDiag,factorGap,localAlignment,initPenalty,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{retcor}} methods. All of the settings to the alignment
algorithm can be passed with a \code{ObiwarpParam} object.

Alignment using obiwarp is performed on the retention time of spectra
of on MS level. Retention times for spectra of other MS levels are
subsequently adjusted based on the adjustment function defined on the
retention times of the spectra of MS level \code{msLevel}.

Calling \code{adjustRtime} on an \code{XCMSnExp} object will cause
all peak grouping (correspondence) results and any previous retention
time adjustment results to be dropped.
}
\examples{
library(faahKO)
library(MSnbase)
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 retention time correction on the OnDiskMSnExp:
res <- adjustRtime(raw_data, param = ObiwarpParam())

## As a result we get a numeric vector with the adjusted retention times for
## all spectra.
head(res)

## We can split this by file to get the adjusted retention times for each
## file
resL <- split(res, fromFile(raw_data))

##############################
## Perform retention time correction on an XCMSnExp:
##
## Perform first the chromatographic peak detection using the matchedFilter
## method.
mfp <- MatchedFilterParam(snthresh = 20, binSize = 1)
res <- findChromPeaks(raw_data, param = mfp)

## Performing the retention time adjustment using obiwarp.
res_2 <- adjustRtime(res, param = ObiwarpParam())

head(rtime(res_2))
head(rtime(raw_data))

## Also the retention times of the detected peaks were adjusted.
tail(chromPeaks(res))
tail(chromPeaks(res_2))
}
\references{
John T. Prince and Edward M. Marcotte. "Chromatographic Alignment of
ESI-LC-MS Proteomics Data Sets by Ordered Bijective Interpolated Warping"
\emph{Anal. Chem.} 2006, 78(17):6140-6152.

John T. Prince and Edward M. Marcotte. "Chromatographic Alignment of
ESI-LC-MS Proteomic Data Sets by Ordered Bijective Interpolated Warping"
\emph{Anal. Chem.} 2006, 78 (17), 6140-6152.
}
\seealso{
\code{\link{retcor.obiwarp}} 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-peakGroups}},
  \code{\link{adjustRtime}}
}
\author{
Colin Smith, Johannes Rainer
}
\concept{retention time correction methods}
