% 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{FillChromPeaksParam-class}
\alias{FillChromPeaksParam-class}
\alias{FillChromPeaksParam}
\alias{fixedRt}
\alias{fixedMz}
\alias{show,FillChromPeaksParam-method}
\alias{expandMz,FillChromPeaksParam-method}
\alias{expandMz}
\alias{expandMz<-,FillChromPeaksParam-method}
\alias{expandMz<-}
\alias{expandRt,FillChromPeaksParam-method}
\alias{expandRt}
\alias{expandRt<-,FillChromPeaksParam-method}
\alias{expandRt<-}
\alias{ppm,FillChromPeaksParam-method}
\alias{ppm<-,FillChromPeaksParam-method}
\alias{fillChromPeaks,XCMSnExp,FillChromPeaksParam-method}
\alias{fillChromPeaks}
\alias{fillChromPeaks,XCMSnExp,missing-method}
\title{Integrate areas of missing peaks}
\usage{
FillChromPeaksParam(expandMz = 0, expandRt = 0, ppm = 0,
  fixedMz = 0, fixedRt = 0)

fixedRt(object)

fixedMz(object)

\S4method{show}{FillChromPeaksParam}(object)

\S4method{expandMz}{FillChromPeaksParam}(object)

\S4method{expandMz}{FillChromPeaksParam}(object) <- value

\S4method{expandRt}{FillChromPeaksParam}(object)

\S4method{expandRt}{FillChromPeaksParam}(object) <- value

\S4method{ppm}{FillChromPeaksParam}(object)

\S4method{ppm}{FillChromPeaksParam}(object) <- value

\S4method{fillChromPeaks}{XCMSnExp,FillChromPeaksParam}(object, param,
  msLevel = 1L, BPPARAM = bpparam())

\S4method{fillChromPeaks}{XCMSnExp,missing}(object, param,
  BPPARAM = bpparam(), msLevel = 1L)
}
\arguments{
\item{expandMz}{\code{numeric(1)} defining the value by which the mz width of
peaks should be expanded. Each peak is expanded in mz direction by
\code{expandMz *} their original mz width. A value of \code{0} means no
expansion, a value of \code{1} grows each peak by 1 * the mz width of
the peak resulting in peakswith twice their original size in mz
direction (expansion by half mz width to both sides).}

\item{expandRt}{\code{numeric(1)}, same as \code{expandRt} but for the
retention time width.}

\item{ppm}{\code{numeric(1)} optionally specifying a \emph{ppm} by which the
mz width of the peak region should be expanded. For peaks with an mz
width smaller than \code{mean(c(mzmin, mzmax)) * ppm / 1e6}, the
\code{mzmin} will be replaced by
\code{mean(c(mzmin, mzmax)) - (mean(c(mzmin, mzmax)) * ppm / 2 / 1e6)}
and \code{mzmax} by
\code{mean(c(mzmin, mzmax)) + (mean(c(mzmin, mzmax)) * ppm / 2 / 1e6)}.
This is applied before eventually expanding the mz width using the
\code{expandMz} parameter.}

\item{fixedMz}{\code{numeric(1)} defining a constant factor by which the
m/z width of each feature is to be expanded. The m/z width is expanded
on both sides by \code{fixedMz} (i.e. \code{fixedMz} is subtracted
from the lower m/z and added to the upper m/z). This expansion is
applied \emph{after} \code{expandMz} and \code{ppm}.}

\item{fixedRt}{\code{numeric(1)} defining a constant factor by which the
retention time width of each factor is to be expanded. The rt width is
expanded on both sides by \code{fixedRt} (i.e. \code{fixedRt} is
subtracted from the lower rt and added to the upper rt). This
expansion is applied \emph{after} \code{expandRt}.}

\item{object}{\code{XCMSnExp} object with identified and grouped
chromatographic peaks.}

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

\item{param}{A \code{FillChromPeaksParam} object with all settings.}

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

\item{BPPARAM}{Parallel processing settings.}
}
\value{
The \code{FillChromPeaksParam} function returns a
    \code{FillChromPeaksParam} object.

A \code{\link{XCMSnExp}} object with previously missing
chromatographic peaks for features filled into its \code{chromPeaks}
matrix.
}
\description{
The \code{FillChromPeaksParam} object encapsules all settings for
the signal integration for missing peaks.

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

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

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

Integrate signal in the mz-rt area of a feature (chromatographic
peak group) for samples in which no chromatographic peak for this
feature was identified and add it to the \code{chromPeaks}. Such peaks
will have a \code{TRUE} in the \code{chromPeakData} data frame containing
peak annotations.
}
\details{
After correspondence (i.e. grouping of chromatographic peaks across
samples) there will always be features (peak groups) that do not include
peaks from every sample. The \code{fillChromPeaks} method defines
intensity values for such features in the missing samples by integrating
the signal in the mz-rt region of the feature. The mz-rt area is defined
by the median mz and rt start and end points of the other detected
chromatographic peaks for a given feature. Various parameters allow to
increase this area, either by a constant value (\code{fixedMz} and
\code{fixedRt}) or by a feature-relative amount (\code{expandMz} and
\code{expandRt}).

Adjusted retention times will be used if available.

Based on the peak finding algorithm that was used to identify the
(chromatographic) peaks different internal functions are employed to
guarantee that the integrated peak signal matches as much as possible
the peak signal integration used during the peak detection. For peaks
identified with the \code{\link{matchedFilter}} method, signal
integration is performed on the \emph{profile matrix} generated with
the same settings used also during peak finding (using the same
\code{bin} size for example). For direct injection data and peaks
identified with the \code{\link{MSW}} algorithm signal is integrated
only along the mz dimension. For all other methods the complete (raw)
signal within the area defined by \code{"mzmin"}, \code{"mzmax"},
\code{"rtmin"} and \code{"rtmax"} is used.
}
\section{Slots}{

\describe{
\item{\code{.__classVersion__,expandMz,expandRt,ppm,fixedMz,fixedRt}}{See corresponding parameter above. \code{.__classVersion__} stores the version of the class.}
}}

\note{
The reported \code{"mzmin"}, \code{"mzmax"}, \code{"rtmin"} and
\code{"rtmax"} for the filled peaks represents the actual MS area from
which the signal was integrated.
Note that no peak is filled in if no signal was present in a file/sample
in the respective mz-rt area. These samples will still show a \code{NA}
in the matrix returned by the \code{\link{featureValues}} method. This
is in contrast to the \code{\link{fillPeaks.chrom}} method that returned
an \code{"into"} and \code{"maxo"} of \code{0} for such peak areas.
Growing the mz-rt area using the \code{expandMz} and \code{expandRt}
might help to reduce the number of missing peak signals after filling.
}
\examples{

## Perform the peak detection using centWave on some of the files from the
## faahKO package. Files are read using the readMSData from the MSnbase
## package
library(faahKO)
library(xcms)
fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE,
           full.names = TRUE)
raw_data <- readMSData(fls[1:2], mode = "onDisk")

## Create a CentWaveParam object. Note that the noise is set to 10000 to
## speed up the execution of the example - in a real use case the default
## value should be used, or it should be set to a reasonable value.
cwp <- CentWaveParam(ppm = 20, noise = 10000, snthresh = 40)

res <- findChromPeaks(raw_data, param = cwp)

## Perform the correspondence. We assign all samples to the same group.
res <- groupChromPeaks(res,
    param = PeakDensityParam(sampleGroups = rep(1, length(fileNames(res)))))

## For how many features do we lack an integrated peak signal?
sum(is.na(featureValues(res)))

## Filling missing peak data using default settings.
res <- fillChromPeaks(res)

## Get the peaks that have been filled in:
fp <- chromPeaks(res)[chromPeakData(res)$is_filled, ]
head(fp)

## Did we get a signal for all missing peaks?
sum(is.na(featureValues(res)))

## No.

## Get the process history step along with the parameters used to perform
## The peak filling:
ph <- processHistory(res, type = "Missing peak filling")[[1]]
ph

## The parameter class:
ph@param

## Drop the filled in peaks:
res <- dropFilledChromPeaks(res)

## Perform the peak filling with modified settings: allow expansion of the
## mz range by a specified ppm and expanding the mz range by mz width/2
prm <- FillChromPeaksParam(ppm = 40, expandMz = 0.5)
res <- fillChromPeaks(res, param = prm)

## Did we get a signal for all missing peaks?
sum(is.na(featureValues(res)))

## Still the same missing peaks.
}
\seealso{
\code{\link{groupChromPeaks}} for methods to perform the
    correspondence.
    \code{\link{dropFilledChromPeaks}} for the method to remove filled in peaks.
}
\author{
Johannes Rainer
}
