% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/DataClasses.R, R/functions-Params.R,
%   R/methods-Params.R, R/methods-XCMSnExp.R
\docType{class}
\name{groupChromPeaks-nearest}
\alias{groupChromPeaks-nearest}
\alias{NearestPeaksParam-class}
\alias{NearestPeaksParam}
\alias{show,NearestPeaksParam-method}
\alias{sampleGroups,NearestPeaksParam-method}
\alias{sampleGroups<-,NearestPeaksParam-method}
\alias{mzVsRtBalance,NearestPeaksParam-method}
\alias{mzVsRtBalance}
\alias{mzVsRtBalance<-,NearestPeaksParam-method}
\alias{mzVsRtBalance<-}
\alias{absMz,NearestPeaksParam-method}
\alias{absMz<-,NearestPeaksParam-method}
\alias{absRt,NearestPeaksParam-method}
\alias{absRt}
\alias{absRt<-,NearestPeaksParam-method}
\alias{absRt<-}
\alias{kNN,NearestPeaksParam-method}
\alias{kNN}
\alias{kNN<-,NearestPeaksParam-method}
\alias{kNN<-}
\alias{groupChromPeaks,XCMSnExp,NearestPeaksParam-method}
\title{Peak grouping based on proximity in the mz-rt space}
\usage{
NearestPeaksParam(sampleGroups = numeric(), mzVsRtBalance = 10,
  absMz = 0.2, absRt = 15, kNN = 10)

\S4method{show}{NearestPeaksParam}(object)

\S4method{sampleGroups}{NearestPeaksParam}(object)

\S4method{sampleGroups}{NearestPeaksParam}(object) <- value

\S4method{mzVsRtBalance}{NearestPeaksParam}(object)

\S4method{mzVsRtBalance}{NearestPeaksParam}(object) <- value

\S4method{absMz}{NearestPeaksParam}(object)

\S4method{absMz}{NearestPeaksParam}(object) <- value

\S4method{absRt}{NearestPeaksParam}(object)

\S4method{absRt}{NearestPeaksParam}(object) <- value

\S4method{kNN}{NearestPeaksParam}(object)

\S4method{kNN}{NearestPeaksParam}(object) <- value

\S4method{groupChromPeaks}{XCMSnExp,NearestPeaksParam}(object, param,
  msLevel = 1L)
}
\arguments{
\item{sampleGroups}{A vector of the same length than samples defining the
sample group assignments (i.e. which samples belong to which sample
group). This parameter is mandatory for the \code{PeakDensityParam}
and has to be provided also if there is no sample grouping in the
experiment (in which case all samples should be assigned to the
same group).}

\item{mzVsRtBalance}{\code{numeric(1)} representing the factor by which mz
values are multiplied before calculating the (euclician) distance between
two peaks.}

\item{absMz}{\code{numeric(1)} maximum tolerated distance for mz values.}

\item{absRt}{\code{numeric(1)} maximum tolerated distance for rt values.}

\item{kNN}{\code{numeric(1)} representing the number of nearest neighbors
to check.}

\item{object}{For \code{groupChromPeaks}: an \link{XCMSnExp} object containing the
results from a previous chromatographic peak detection
analysis (see \code{\link[=findChromPeaks]{findChromPeaks()}}).\preformatted{For all other methods: a `NearestPeaksParam` object.
}}

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

\item{param}{A \code{NearestPeaksParam} object containing all settings for
the peak grouping algorithm.}

\item{msLevel}{\code{integer(1)} defining the MS level. Currently only MS level
1 is supported.}
}
\value{
The \code{NearestPeaksParam} function returns a
    \code{NearestPeaksParam} class instance with all of the settings
    specified for peak alignment based on peak proximity.

For \code{groupChromPeaks}: a \link{XCMSnExp} object with the results of the peak
grouping/correspondence step (i.e. the mz-rt features). These can be
accessed with the \code{\link[=featureDefinitions]{featureDefinitions()}} method.
}
\description{
This method is inspired by the grouping algorithm of mzMine
(Katajamaa 2006) and performs correspondence based on proximity of peaks
in the space spanned by retention time and mz values.
The method creates first a \emph{master peak list} consisting of all
chromatographic peaks from the sample in which most peaks were
identified, and starting from that, calculates distances to peaks from
the sample with the next most number of peaks. If peaks are closer than
the defined threshold they are grouped together.

The \code{NearestPeaksParam} class allows to specify all
settings for the peak grouping based on the \emph{nearest} algorithm.
Instances should be created with the \code{NearestPeaksParam} constructor.

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

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

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

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

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

\code{groupChromPeaks,XCMSnExp,NearestPeaksParam}:
performs peak grouping based on the proximity between chromatographic
peaks from different samples in the mz-rt range.
}
\section{Slots}{

\describe{
\item{\code{.__classVersion__,sampleGroups,mzVsRtBalance,absMz,absRt,kNN}}{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. All of the settings to the algorithm
can be passed with a \code{NearestPeaksParam} object.

Calling \code{groupChromPeaks} on an \code{XCMSnExp} object will cause
all eventually present previous alignment results to be dropped.
}
\examples{

## Create a NearestPeaksParam object
p <- NearestPeaksParam(kNN = 3)
p

##############################
## Chromatographic peak detection and grouping.
##
## Below we perform first a chromatographic peak detection (using the
## matchedFilter method) on some of the test files from the faahKO package
## followed by a peaks grouping using the "nearest" method.
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 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
p <- NearestPeaksParam()
res <- groupChromPeaks(res, param = p)

## The results from the peak grouping:
featureDefinitions(res)

## Using the featureValues method to extract a matrix with the intensities of
## the features per sample.
head(featureValues(res, value = "into"))

## The process history:
processHistory(res)
}
\references{
Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for
processing and visualization of mass spectrometry based molecular profile
data. Bioinformatics 2006, 22:634-636.
}
\seealso{
The \code{\link[=do_groupChromPeaks_nearest]{do_groupChromPeaks_nearest()}} core API function.

\code{\link[=featureDefinitions]{featureDefinitions()}} and \code{\link[=featureValues]{featureValues()}} for methods to access
peak grouping results (i.e. the features).

\link{XCMSnExp} for the object containing the results of
the peak grouping.

Other peak grouping methods: \code{\link{groupChromPeaks-density}},
  \code{\link{groupChromPeaks-mzClust}},
  \code{\link{groupChromPeaks}}
}
\concept{peak grouping methods}
