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

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

The FillChromPeaksParam object encapsules all settings for the signal integration for missing peaks.

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. Such peaks will have a TRUE in column "is_filled" in the chromPeakData data frame containing peak annotations.

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

fixedRt(object)

fixedMz(object)

## 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,missing'
fillChromPeaks(object, param, BPPARAM = bpparam(), msLevel = 1L)

`expandMz`	`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 mz width. A value of `0` means no expansion, a value of `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).
`expandRt`	`numeric(1)`, same as `expandMz` but for the retention time width.
`ppm`	`numeric(1)` optionally specifying a ppm by which the mz width of the peak region should be expanded. For peaks with an mz 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)` and `mzmax` by `mean(c(mzmin, mzmax)) + (mean(c(mzmin, mzmax)) * ppm / 2 / 1e6)`. This is applied before eventually expanding the mz width using the `expandMz` parameter.
`fixedMz`	`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`	`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.
`value`	The value for the slot.
`param`	A `FillChromPeaksParam` object with all settings.
`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. 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 (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 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 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 defined by "mzmin", "mzmax", "rtmin" and "rtmax" 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.

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. This is in contrast to the fillPeaks.chrom method that returned an "into" and "maxo" of 0 for such peak areas. Growing the mz-rt area using the expandMz and expandRt might help to reduce the number of missing peak signals after filling.

Johannes Rainer

groupChromPeaks for methods to perform the correspondence. dropFilledChromPeaks for the method to remove filled in peaks.

## 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, prefilter = c(3, 10000),
    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.