findChromPeaks-centWaveWithPredIsoROIs {xcms} | R Documentation

## Two-step centWave peak detection considering also isotopes

### Description

This method performs a two-step centWave-based chromatographic peak detection: in a first centWave run peaks are identified for which then the location of their potential isotopes in the mz-retention time is predicted. A second centWave run is then performed on these regions of interest (ROIs). The final list of chromatographic peaks comprises all non-overlapping peaks from both centWave runs.

The `CentWavePredIsoParam` class allows to specify all settings for the two-step centWave-based peak detection considering also predicted isotopes of peaks identified in the first centWave run. Instances should be created with the `CentWavePredIsoParam` constructor. See also the documentation of the `CentWaveParam` for all methods and arguments this class inherits.

The `findChromPeaks,OnDiskMSnExp,CentWavePredIsoParam` method performs a two-step centWave-based chromatographic peak detection on all samples from an `OnDiskMSnExp` object. `OnDiskMSnExp` objects encapsule all experiment specific data and load the spectra data (mz and intensity values) on the fly from the original files applying also all eventual data manipulations.

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

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

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

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

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

### Usage

    CentWavePredIsoParam(
      ppm = 25,
      peakwidth = c(20, 50),
      snthresh = 10,
      prefilter = c(3, 100),
      mzCenterFun = "wMean",
      integrate = 1L,
      mzdiff = -0.001,
      fitgauss = FALSE,
      noise = 0,
      verboseColumns = FALSE,
      roiList = list(),
      firstBaselineCheck = TRUE,
      roiScales = numeric(),
      snthreshIsoROIs = 6.25,
      maxCharge = 3,
      maxIso = 5,
      mzIntervalExtension = TRUE,
      polarity = "unknown"
    )

    ## S4 method for signature 'OnDiskMSnExp,CentWavePredIsoParam'
    findChromPeaks(
      object,
      param,
      BPPARAM = bpparam(),
      return.type = "XCMSnExp",
      msLevel = 1L
    )

    ## S4 method for signature 'CentWavePredIsoParam'
    snthreshIsoROIs(object)

    ## S4 replacement method for signature 'CentWavePredIsoParam'
    snthreshIsoROIs(object) <- value

    ## S4 method for signature 'CentWavePredIsoParam'
    maxCharge(object)

    ## S4 replacement method for signature 'CentWavePredIsoParam'
    maxCharge(object) <- value

    ## S4 method for signature 'CentWavePredIsoParam'
    maxIso(object)

    ## S4 replacement method for signature 'CentWavePredIsoParam'
    maxIso(object) <- value

    ## S4 method for signature 'CentWavePredIsoParam'
    mzIntervalExtension(object)

    ## S4 replacement method for signature 'CentWavePredIsoParam'
    mzIntervalExtension(object) <- value

    ## S4 method for signature 'CentWavePredIsoParam'
    polarity(object)

    ## S4 replacement method for signature 'CentWavePredIsoParam'
    polarity(object) <- value

### Arguments

`ppm` | `numeric(1)` defining the maximal tolerated m/z deviation in consecutive scans in parts per million (ppm) for the initial ROI definition.
`peakwidth` | `numeric(2)` with the expected approximate peak width in chromatographic space. Given as a range (min, max) in seconds.
`snthresh` | `numeric(1)` defining the signal to noise ratio cutoff.
`prefilter` | `numeric(2)`: `c(k, I)` specifying the prefilter step for the first analysis step (ROI detection). Mass traces are only retained if they contain at least `k` peaks with intensity `>= I`.
`mzCenterFun` | Name of the function to calculate the m/z center of the chromatographic peak. Allowed are: `"wMean"`: intensity weighted mean of the peak's m/z values, `"mean"`: mean of the peak's m/z values, `"apex"`: use the m/z value at the peak apex, `"wMeanApex3"`: intensity weighted mean of the m/z value at the peak apex and the m/z values left and right of it and `"meanApex3"`: mean of the m/z value of the peak apex and the m/z values left and right of it.
`integrate` | Integration method. For `integrate = 1` peak limits are found through descent on the mexican hat filtered data, for `integrate = 2` the descent is done on the real data. The latter method is more accurate but prone to noise, while the former is more robust, but less exact.
`mzdiff` | `numeric(1)` representing the minimum difference in m/z dimension required for peaks with overlapping retention times; can be negative to allow overlap. During peak post-processing, peaks defined to be overlapping are reduced to the one peak with the largest signal.
`fitgauss` | `logical(1)` whether or not a Gaussian should be fitted to each peak. This affects mostly the retention time position of the peak.
`noise` | `numeric(1)` allowing to set a minimum intensity required for centroids to be considered in the first analysis step (centroids with intensity `< noise` are omitted from ROI detection).
`verboseColumns` | `logical(1)` whether additional peak meta data columns should be returned.
`roiList` | An optional list of regions-of-interest (ROI) representing detected mass traces. If ROIs are submitted the first analysis step is omitted and chromatographic peak detection is performed on the submitted ROIs. Each ROI is expected to have the following elements specified: `scmin` (start scan index), `scmax` (end scan index), `mzmin` (minimum m/z), `mzmax` (maximum m/z), `length` (number of scans), `intensity` (summed intensity). Each ROI should be represented by a `list` of elements or a single row `data.frame`.
`firstBaselineCheck` | `logical(1)`. If `TRUE` continuous data within regions of interest is checked to be above the first baseline.
`roiScales` | Optional numeric vector with length equal to `roiList` defining the scale for each region of interest in `roiList` that should be used for the centWave-wavelets.
`snthreshIsoROIs` | `numeric(1)` defining the signal to noise ratio cutoff to be used in the second centWave run to identify peaks for predicted isotope ROIs.
`maxCharge` | `integer(1)` defining the maximal isotope charge. Isotopes will be defined for charges `1:maxCharge`.
`maxIso` | `integer(1)` defining the number of isotope peaks that should be predicted for each peak identified in the first centWave run.
`mzIntervalExtension` | `logical(1)` whether the mz range for the predicted isotope ROIs should be extended to increase detection of low intensity peaks.
`polarity` | `character(1)` specifying the polarity of the data. Currently not used, but has to be `"positive"`, `"negative"` or `"unknown"` if provided.
`object` | For `findChromPeaks`: an `OnDiskMSnExp` object containing the MS- and all other experiment-relevant data. For all other methods: a parameter object.
`param` | An `CentWavePredIsoParam` object with the settings for the chromatographic peak detection algorithm.
`BPPARAM` | A parameter class specifying if and how parallel processing should be performed. It defaults to `bpparam`. See documentation of the `BiocParallel` for more details. If parallel processing is enabled, peak detection is performed in parallel on several of the input samples.
`return.type` | Character specifying what type of object the method should return. Can be either `"XCMSnExp"` (default), `"list"` or `"xcmsSet"`.
`msLevel` | `integer(1)` defining the MS level on which the peak detection should be performed. Defaults to `msLevel = 1`.
`value` | The value for the slot.

### Details

See `centWave` for details on the centWave method.

Parallel processing (one process per sample) is supported and can be configured either by the `BPPARAM` parameter or by globally defining the parallel processing mode using the `register` method from the `BiocParallel` package.

### Value

The `CentWavePredIsoParam` function returns a `CentWavePredIsoParam` class instance with all of the settings specified for the two-step centWave-based peak detection considering also isotopes.

For `findChromPeaks`: if `return.type = "XCMSnExp"` an `XCMSnExp` object with the results of the peak detection. If `return.type = "list"` a list of length equal to the number of samples with matrices specifying the identified peaks. If `return.type = "xcmsSet"` an `xcmsSet` object with the results of the peak detection.

### Slots

`ppm,peakwidth,snthresh,prefilter,mzCenterFun,integrate,mzdiff,fitgauss,noise,verboseColumns,roiList,firstBaselineCheck,roiScales,snthreshIsoROIs,maxCharge,maxIso,mzIntervalExtension,polarity`

  See corresponding parameter above.

### Note

These methods and classes are part of the updated and modernized `xcms` user interface which will eventually replace the `findPeaks` methods. It supports chromatographic peak detection on `OnDiskMSnExp` objects (defined in the `MSnbase` package). All of the settings to the algorithm can be passed with a `CentWavePredIsoParam` object.

### Author(s)

Hendrik Treutler, Johannes Rainer

### See Also

The `do_findChromPeaks_centWaveWithPredIsoROIs` core API function and `findPeaks.centWave` for the old user interface. `CentWaveParam` for the class the `CentWavePredIsoParam` extends.

`XCMSnExp` for the object containing the results of the peak detection.

Other peak detection methods: `chromatographic-peak-detection`, `findChromPeaks-centWave`, `findChromPeaks-massifquant`, `findChromPeaks-matchedFilter`, `findPeaks-MSW`

### Examples

    ## Create a param object
    p <- CentWavePredIsoParam(maxCharge = 4)
    ## Change snthresh parameter
    snthresh(p) <- 25
    p

[Package xcms version 3.16.1 Index]