FillChromPeaksParam-class {xcms} | R Documentation

## Integrate areas of missing peaks

### Description

`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.

### Usage

    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'
    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)

### Arguments

`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.

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

### Value

The `FillChromPeaksParam` function returns a `FillChromPeaksParam` object.

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

### Slots

`expandMz,expandRt,ppm,fixedMz,fixedRt`

  See corresponding parameter above.

`rtmin,rtmax,mzmin,mzmax`

  See corresponding parameter above.

### Note

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.

### Author(s)

Johannes Rainer

### See Also

`groupChromPeaks()` for methods to perform the correspondence.

featureArea for the function to define the m/z-retention time region for each feature.

### Examples

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

[Package xcms version 3.16.1 Index]