fillChromPeaks: Integrate areas of missing peaks
In xcms: LC-MS and GC-MS Data Analysis

Description Usage Arguments Details Value Slots Note Author(s) See Also Examples

expandMz,expandMz<-: getter and setter for the expandMz slot of the object.

expandRt,expandRt<-: getter and setter for the expandRt slot of the object.

ppm,ppm<-: getter and setter for the 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 chromPeaks() matrix. Such filled-in peaks are indicated with a TRUE in column "is_filled" in the result object's chromPeakData() data frame.

Two different gap-filling approaches are implemented:

param = FillChromPeaksParam(): the default of the original xcms code. Signal is integrated from the m/z and retention time range as defined in the featureDefinitions() data frame, i.e. from the "rtmin", "rtmax", "mzmin" and "mzmax". See details below for more information and settings for this method.
param = ChromPeakAreaParam(): the area from which the signal for a feature is integrated is defined based on the feature's chromatographic peak areas. The m/z range is by default defined as the the lower quartile of chromatographic peaks' "mzmin" value to the upper quartile of the chromatographic peaks' "mzmax" values. The retention time range for the area is defined analogously. Alternatively, by setting mzmin = median, mzmax = median, rtmin = median and rtmax = median in ChromPeakAreaParam, the median "mzmin", "mzmax", "rtmin" and "rtmax" values from all detected chromatographic peaks of a feature would be used instead. In contrast to the FillChromPeaksParam approach this method uses the actual identified chromatographic peaks of a feature to define the area from which the signal should be integrated.

FillChromPeaksParam(
  expandMz = 0,
  expandRt = 0,
  ppm = 0,
  fixedMz = 0,
  fixedRt = 0
)

fixedRt(object)

fixedMz(object)

ChromPeakAreaParam(
  mzmin = function(z) quantile(z, probs = 0.25),
  mzmax = function(z) quantile(z, probs = 0.75),
  rtmin = function(z) quantile(z, probs = 0.25),
  rtmax = function(z) quantile(z, probs = 0.75)
)

## S4 method for signature 'FillChromPeaksParam'
show(object)

## S4 method for signature 'FillChromPeaksParam'
expandMz(object)

## S4 replacement method for signature 'FillChromPeaksParam'
expandMz(object) <- value

## S4 method for signature 'FillChromPeaksParam'
expandRt(object)

## S4 replacement method for signature 'FillChromPeaksParam'
expandRt(object) <- value

## S4 method for signature 'FillChromPeaksParam'
ppm(object)

## S4 replacement method for signature 'FillChromPeaksParam'
ppm(object) <- value

## S4 method for signature 'XCMSnExp,FillChromPeaksParam'
fillChromPeaks(object, param, msLevel = 1L, BPPARAM = bpparam())

## S4 method for signature 'XCMSnExp,ChromPeakAreaParam'
fillChromPeaks(object, param, msLevel = 1L, BPPARAM = bpparam())

## S4 method for signature 'XCMSnExp,missing'
fillChromPeaks(object, param, BPPARAM = bpparam(), msLevel = 1L)

`expandMz`	for `FillChromPeaksParam`: `numeric(1)` defining the value by which the mz width of peaks should be expanded. Each peak is expanded in mz direction by `expandMz ` their original m/z width. A value of `0` means no expansion, a value of `1` grows each peak by `1 ` the m/z width of the peak resulting in peaks with twice their original size in m/z direction (expansion by half m/z width to both sides).
`expandRt`	for `FillChromPeaksParam`: `numeric(1)`, same as `expandMz` but for the retention time width.
`ppm`	for `FillChromPeaksParam`: `numeric(1)` optionally specifying a ppm by which the m/z width of the peak region should be expanded. For peaks with an m/z width smaller than `mean(c(mzmin, mzmax)) * ppm / 1e6`, the `mzmin` will be replaced by `mean(c(mzmin, mzmax)) - (mean(c(mzmin, mzmax)) * ppm / 2 / 1e6)` `mzmax` by `mean(c(mzmin, mzmax)) + (mean(c(mzmin, mzmax)) * ppm / 2 / 1e6)`. This is applied before eventually expanding the m/z width using the `expandMz` parameter.
`fixedMz`	for `FillChromPeaksParam`: `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 `fixedMz` (i.e. `fixedMz` is subtracted from the lower m/z and added to the upper m/z). This expansion is applied after `expandMz` and `ppm`.
`fixedRt`	for `FillChromPeaksParam`: `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 `fixedRt` (i.e. `fixedRt` is subtracted from the lower rt and added to the upper rt). This expansion is applied after `expandRt`.
`object`	`XCMSnExp` object with identified and grouped chromatographic peaks.
`mzmin`	`function` to be applied to values in the `"mzmin"` column of all chromatographic peaks of a feature to define the lower m/z value of the area from which signal for the feature should be integrated. Defaults to `mzmin = function(z) quantile(z, probs = 0.25)` hence using the 25% quantile of all values.
`mzmax`	`function` to be applied to values in the `"mzmax"` column of all chromatographic peaks of a feature to define the upper m/z value of the area from which signal for the feature should be integrated. Defaults to `mzmax = function(z) quantile(z, probs = 0.75)` hence using the 75% quantile of all values.
`rtmin`	`function` to be applied to values in the `"rtmin"` column of all chromatographic peaks of a feature to define the lower rt value of the area from which signal for the feature should be integrated. Defaults to `rtmin = function(z) quantile(z, probs = 0.25)` hence using the 25% quantile of all values.
`rtmax`	`function` to be applied to values in the `"rtmax"` column of all chromatographic peaks of a feature to define the upper rt value of the area from which signal for the feature should be integrated. Defaults to `rtmax = function(z) quantile(z, probs = 0.75)` hence using the 75% quantile of all values.
`value`	The value for the slot.
`param`	`FillChromPeaksParam` or `ChromPeakAreaParam` object defining which approach should be used (see details section).
`msLevel`	`integer(1)` defining the MS level on which peak filling should be performed (defaults to `msLevel = 1L`). Only peak filling on one MS level at a time is supported, to fill in peaks for MS level 1 and 2 run first using `msLevel = 1` and then (on the returned result object) again with `msLevel = 2`.
`BPPARAM`	Parallel processing settings.

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 fillChromPeaks method defines intensity values for such features in the missing samples by integrating the signal in the mz-rt region of the feature. Two different approaches to define this region are available: with ChromPeakAreaParam the region is defined based on the detected chromatographic peaks of a feature, while with FillChromPeaksParam the region is defined based on the m/z and retention times of the feature (which represent the m/z and retentention times of the apex position of the associated chromatographic peaks). For the latter approach various parameters are available to increase the area from which signal is to be integrated, either by a constant value (fixedMz and fixedRt) or by a feature-relative amount (expandMz and 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 used 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 matchedFilter() method, signal integration is performed on the profile matrix generated with the same settings used also during peak finding (using the same bin size for example). For direct injection data and peaks identified with the MSW algorithm signal is integrated only along the mz dimension. For all other methods the complete (raw) signal within the area is used.

The FillChromPeaksParam function returns a FillChromPeaksParam object.

A XCMSnExp object with previously missing chromatographic peaks for features filled into its chromPeaks() matrix.

.__classVersion__,expandMz,expandRt,ppm,fixedMz,fixedRt: See corresponding parameter above. '.__classVersion__' stores the version of the class.
.__classVersion__,rtmin,rtmax,mzmin,mzmax: See corresponding parameter above. '.__classVersion__' stores the version of the class.

The reported "mzmin", "mzmax", "rtmin" and "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 NA in the matrix returned by the featureValues() method.

Johannes Rainer

groupChromPeaks() for methods to perform the correspondence.

## Load a test data set with identified chromatographic peaks
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")
res <- faahko_sub

## Disable parallel processing for this example
register(SerialParam())

## 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 the peak area from identified
## chromatographic peaks.
res <- fillChromPeaks(res, param = ChromPeakAreaParam())

## How many missing values do we have after peak filling?
sum(is.na(featureValues(res)))

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

## 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

## It is also possible to remove filled-in peaks:
res <- dropFilledChromPeaks(res)

sum(is.na(featureValues(res)))