groupChromPeaks-nearest {xcms} | R Documentation

## Peak grouping based on proximity in the mz-rt space

### Description

This method is inspired by the grouping algorithm of mzMine (Katajamaa 2006) and performs correspondence based on proximity of peaks in the space spanned by retention time and mz values. The method creates first a master peak list consisting of all chromatographic peaks from the sample in which most peaks were identified, and starting from that, calculates distances to peaks from the sample with the next most number of peaks. If peaks are closer than the defined threshold they are grouped together.

The `NearestPeaksParam` class allows to specify all settings for the peak grouping based on the nearest algorithm. Instances should be created with the `NearestPeaksParam` constructor.

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

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

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

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

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

`groupChromPeaks,XCMSnExp,NearestPeaksParam`: performs peak grouping based on the proximity between chromatographic peaks from different samples in the mz-rt range.

The correspondence analysis can be performed on chromatographic peaks of any MS level (if present and if chromatographic peak detection has been performed for that MS level) defining features combining these peaks. The MS level can be selected with the parameter `msLevel`. By default, calling `groupChromPeaks` will remove any previous correspondence results. This can be disabled with `add = TRUE`, which will add newly defined features to already present feature definitions.

### Usage

    NearestPeaksParam(
      sampleGroups = numeric(),
      mzVsRtBalance = 10,
      absMz = 0.2,
      absRt = 15,
      kNN = 10
    )

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

    ## S4 method for signature 'NearestPeaksParam'
    sampleGroups(object)

    ## S4 replacement method for signature 'NearestPeaksParam'
    sampleGroups(object) <- value

    ## S4 method for signature 'NearestPeaksParam'
    mzVsRtBalance(object)

    ## S4 replacement method for signature 'NearestPeaksParam'
    mzVsRtBalance(object) <- value

    ## S4 method for signature 'NearestPeaksParam'
    absMz(object)

    ## S4 replacement method for signature 'NearestPeaksParam'
    absMz(object) <- value

    ## S4 method for signature 'NearestPeaksParam'
    absRt(object)

    ## S4 replacement method for signature 'NearestPeaksParam'
    absRt(object) <- value

    ## S4 method for signature 'NearestPeaksParam'
    kNN(object)

    ## S4 replacement method for signature 'NearestPeaksParam'
    kNN(object) <- value

    ## S4 method for signature 'XCMSnExp,NearestPeaksParam'
    groupChromPeaks(object, param, msLevel = 1L, add = FALSE)

### Arguments

`sampleGroups` | A vector of the same length than samples defining the sample group assignments (i.e. which samples belong to which sample group). This parameter is mandatory for the `PeakDensityParam` and has to be provided also if there is no sample grouping in the experiment (in which case all samples should be assigned to the same group).
`mzVsRtBalance` | `numeric(1)` representing the factor by which mz values are multiplied before calculating the (euclician) distance between two peaks.
`absMz` | `numeric(1)` maximum tolerated distance for mz values.
`absRt` | `numeric(1)` maximum tolerated distance for rt values.
`kNN` | `numeric(1)` representing the number of nearest neighbors to check.
`object` | For `groupChromPeaks`: an XCMSnExp object containing the results from a previous chromatographic peak detection analysis (see `findChromPeaks()`).
    For all other methods: a `NearestPeaksParam` object.
`value` | The value for the slot.
`param` | A `PeakDensityParam` object containing all settings for the peak grouping algorithm.
`msLevel` | `integer(1)` defining the MS level. Currently only MS level 1 is supported.
`add` | `logical(1)` (default `add = FALSE`) allowing to perform an additional round of correspondence (e.g. on a different MS level) and add features to the already present feature definitions.

### Value

The `NearestPeaksParam` function returns a `NearestPeaksParam` class instance with all of the settings specified for peak alignment based on peak proximity.

For `groupChromPeaks`: a XCMSnExp object with the results of the peak grouping/correspondence step (i.e. the mz-rt features). These can be accessed with the `featureDefinitions()` method.

### Slots

`.__classVersion__,sampleGroups,mzVsRtBalance,absMz,absRt,kNN`

  See corresponding parameter above. `.__classVersion__` stores the version from the class. Slots values should exclusively be accessed via the corresponding getter and setter methods listed above.

### Note

These methods and classes are part of the updated and modernized `xcms` user interface. All of the settings to the algorithm can be passed with a `NearestPeaksParam` object.

### References

Katajamaa M, Miettinen J, Oresic M: MZmine: Toolbox for processing and visualization of mass spectrometry based molecular profile data. Bioinformatics 2006, 22:634-636.

### See Also

The `do_groupChromPeaks_nearest()` core API function.

`featureDefinitions()` and `featureValues()` for methods to access peak grouping results (i.e. the features).

XCMSnExp for the object containing the results of the peak grouping.

Other peak grouping methods: `groupChromPeaks-density`, `groupChromPeaks-mzClust`, `groupChromPeaks()`

### Examples

    ## Create a NearestPeaksParam object
    p <- NearestPeaksParam(kNN = 3)
    p

    ##############################
    ## Chromatographic peak detection and grouping.
    ##
    ## Below we perform first a chromatographic peak detection (using the
    ## matchedFilter method) on some of the test files from the faahKO package
    ## followed by a peaks grouping using the "nearest" method.
    library(faahKO)
    library(MSnbase)
    fls <- dir(system.file("cdf/KO", package = "faahKO"), recursive = TRUE,
               full.names = TRUE)

    ## Reading 2 of the KO samples
    raw_data <- readMSData(fls[1:2], mode = "onDisk")

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

    ## Perform the peak detection using the matchedFilter method.
    mfp <- MatchedFilterParam(snthresh = 20, binSize = 1)
    res <- findChromPeaks(raw_data, param = mfp)

    head(chromPeaks(res))
    ## The number of peaks identified per sample:
    table(chromPeaks(res)[, "sample"])

    ## Performing the peak grouping
    p <- NearestPeaksParam()
    res <- groupChromPeaks(res, param = p)

    ## The results from the peak grouping:
    featureDefinitions(res)

    ## Using the featureValues method to extract a matrix with the intensities of
    ## the features per sample.
    head(featureValues(res, value = "into"))

    ## The process history:
    processHistory(res)

[Package xcms version 3.10.2 Index]