% 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-density}
\alias{groupChromPeaks-density}
\alias{PeakDensityParam-class}
\alias{PeakDensityParam}
\alias{show,PeakDensityParam-method}
\alias{sampleGroups,PeakDensityParam-method}
\alias{sampleGroups}
\alias{sampleGroups<-,PeakDensityParam-method}
\alias{sampleGroups<-}
\alias{bw,PeakDensityParam-method}
\alias{bw}
\alias{bw<-,PeakDensityParam-method}
\alias{bw<-}
\alias{minFraction,PeakDensityParam-method}
\alias{minFraction}
\alias{minFraction<-,PeakDensityParam-method}
\alias{minFraction<-}
\alias{minSamples,PeakDensityParam-method}
\alias{minSamples}
\alias{minSamples<-,PeakDensityParam-method}
\alias{minSamples<-}
\alias{binSize,PeakDensityParam-method}
\alias{binSize<-,PeakDensityParam-method}
\alias{maxFeatures,PeakDensityParam-method}
\alias{maxFeatures}
\alias{maxFeatures<-,PeakDensityParam-method}
\alias{maxFeatures<-}
\alias{groupChromPeaks,XCMSnExp,PeakDensityParam-method}
\title{Peak grouping based on time dimension peak densities}
\usage{
PeakDensityParam(sampleGroups = numeric(), bw = 30,
  minFraction = 0.5, minSamples = 1, binSize = 0.25,
  maxFeatures = 50)

\S4method{show}{PeakDensityParam}(object)

\S4method{sampleGroups}{PeakDensityParam}(object)

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

\S4method{bw}{PeakDensityParam}(object)

\S4method{bw}{PeakDensityParam}(object) <- value

\S4method{minFraction}{PeakDensityParam}(object)

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

\S4method{minSamples}{PeakDensityParam}(object)

\S4method{minSamples}{PeakDensityParam}(object) <- value

\S4method{binSize}{PeakDensityParam}(object)

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

\S4method{maxFeatures}{PeakDensityParam}(object)

\S4method{maxFeatures}{PeakDensityParam}(object) <- value

\S4method{groupChromPeaks}{XCMSnExp,PeakDensityParam}(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{bw}{\code{numeric(1)} defining the bandwidth (standard deviation ot the
smoothing kernel) to be used. This argument is passed to the
[density() method.}

\item{minFraction}{\code{numeric(1)} defining the minimum fraction of samples
in at least one sample group in which the peaks have to be present to be
considered as a peak group (feature).}

\item{minSamples}{\code{numeric(1)} with the minimum number of samples in at
least one sample group in which the peaks have to be detected to be
considered a peak group (feature).}

\item{binSize}{\code{numeric(1)} defining the size of the overlapping slices
in mz dimension.}

\item{maxFeatures}{\code{numeric(1)} with the maximum number of peak groups
to be identified in a single mz slice.}

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

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

\item{param}{A \code{PeakDensityParam} 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{PeakDensityParam} function returns a
\code{PeakDensityParam} class instance with all of the settings
specified for chromatographic peak alignment based on peak densities.
Note that argument \code{sampleGroups} is mandatory and should represent
either the sample grouping in the experiment. It's length has to match
the number of sample in the experiments.

For \code{groupChromPeaks}: a \link{XCMSnExp} object with the
results of the correspondence analysis. The definition of the resulting
mz-rt features can be accessed with the \code{\link[=featureDefinitions]{featureDefinitions()}} method
}
\description{
This method performs performs correspondence (chromatographic
peak grouping) based on the density (distribution) of identified peaks
along the retention time axis within slices of overlapping mz ranges.
All peaks (from the same or from different samples) being close on the
retention time axis are grouped into a feature (\emph{peak group}).

The \code{PeakDensityParam} class allows to specify all settings for the peak
grouping based on peak densities along the time dimension. Instances should
be created with the \code{\link[=PeakDensityParam]{PeakDensityParam()}} constructor.

\code{sampleGroups},\code{sampleGroups<-}: getter and setter
for the \code{sampleGroups} slot of the object. Its length should match
the number of samples in the experiment and it should not contain
\code{NA}s.

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

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

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

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

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

\code{groupChromPeaks,XCMSnExp,PeakDensityParam}:
performs correspondence (peak grouping within and across samples) within
in mz dimension overlapping slices of MS data based on the density
distribution of the identified chromatographic peaks in the slice along
the time axis.
}
\section{Slots}{

\describe{
\item{\code{.__classVersion__,sampleGroups,bw,minFraction,minSamples,binSize,maxFeatures}}{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{PeakDensityParam} object.

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

## Create a PeakDensityParam object
p <- PeakDensityParam(binSize = 0.05, sampleGroups = c(1, 1, 2, 2))
## Change hte minSamples slot
minSamples(p) <- 3
p

##############################
## 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 using the density 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 chromatographic 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 chromatographic peak grouping. Assigning all samples to
## the same sample group.
fdp <- PeakDensityParam(sampleGroups = rep(1, length(fileNames(res))))
res <- groupChromPeaks(res, fdp)

## The definition of the features (peak groups):
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{
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"
Anal. Chem. 2006, 78:779-787.
}
\seealso{
The \code{\link[=do_groupChromPeaks_density]{do_groupChromPeaks_density()}} core API function and \code{\link[=group.density]{group.density()}}
for the old user interface.

\code{\link[=plotChromPeakDensity]{plotChromPeakDensity()}} to plot peak densities and evaluate different
algorithm settings.

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

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

\code{\link[=plotChromPeakDensity]{plotChromPeakDensity()}} for plotting chromatographic peak density with the
possibility to test different parameter settings.

Other peak grouping methods: \code{\link{groupChromPeaks-mzClust}},
  \code{\link{groupChromPeaks-nearest}},
  \code{\link{groupChromPeaks}}
}
\author{
Colin Smith, Johannes Rainer
}
\concept{peak grouping methods}
