FillChromPeaksParam-class {xcms} | R Documentation

## Integrate areas of missing peaks

### Description

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 the `chromPeakData` data frame containing peak annotations.

### Usage

    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)

### Arguments

`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 `expandRt` 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. Currently only MS level 1 is supported.
`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. 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.

### Value

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

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

### Slots

`.__classVersion__,expandMz,expandRt,ppm,fixedMz,fixedRt`

  See corresponding parameter above. `.__classVersion__` stores the version of the class.

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

### Author(s)

Johannes Rainer

### See Also

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

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

[Package xcms version 3.9.1 Index]