joinPeaks {Spectra} | R Documentation

## Join (map) peaks of two spectra

### Description

These functions map peaks from two spectra with each other if the difference between their m/z values is smaller than defined with parameters `tolerance` and `ppm`. All functions take two matrices

- `joinPeaks`: maps peaks from two spectra allowing to specify the type of join that should be performed: `type = "outer"` each peak in `x` will be matched with each peak in `y`, for peaks that do not match any peak in the other spectra an `NA` intensity is returned. With `type = "left"` all peaks from the left spectrum (`x`) will be matched with peaks in `y`. Peaks in `y` that do not match any peak in `x` are omitted. `type = "right"` is the same as `type = "left"` only for `y`. Only peaks that can be matched between `x` and `y` are returned by `type = "inner"`, i.e. only peaks present in both spectra are reported.

- `joinPeaksGnps` matches/maps peaks between spectra with the same approach used in GNPS: peaks are considered matching if a) the difference in their m/z values is smaller than defined by `tolerance` and `ppm` (this is the same as `joinPeaks`) and b) the difference of their m/z adjusted for the difference of the spectras' precursor is smaller than defined by `tolerance` and `ppm`. Based on this definition, peaks in `x` can match up to two peaks in `y` hence peaks in the returned matrices might be reported multiple times. Note that if one of `xPrecursorMz` or `yPrecursorMz` are `NA` or if both are the same, the results are the same as with `joinPeaks()`. To calculate GNPS similarity scores, `gnps()` should be called on the aligned peak matrices (i.e. `compareSpectra` should be called with `MAPFUN = joinPeaksGnps` and `FUN = MsCoreUtils::gnps`).

### Usage

    joinPeaks(x, y, type = "outer", tolerance = 0, ppm = 10, ...)

    joinPeaksGnps(
      x,
      y,
      xPrecursorMz = NA_real_,
      yPrecursorMz = NA_real_,
      tolerance = 0,
      ppm = 0,
      type = "outer",
      ...
    )

### Arguments

`x` | `matrix` with two columns `"mz"` and `"intensity"` containing the m/z and intensity values of the mass peaks of a spectrum.
`y` | `matrix` with two columns `"mz"` and `"intensity"` containing the m/z and intensity values of the mass peaks of a spectrum.
`type` | For `joinPeaks` and `joinPeaksGnps`: `character(1)` specifying the type of join that should be performed. See function description for details.
`tolerance` | `numeric(1)` defining a constant maximal accepted difference between m/z values of peaks from the two spectra to be matched/mapped.
`ppm` | `numeric(1)` defining a relative, m/z-dependent, maximal accepted difference between m/z values of peaks from the two spectra to be matched/mapped.
`...` | optional parameters passed to the `MsCoreUtils::join()` function.
`xPrecursorMz` | for `joinPeaksGnps`: `numeric(1)` with the precursor m/z of the spectrum `x`.
`yPrecursorMz` | for `joinPeaksGnps`: `numeric(1)` with the precursor m/z of the spectrum `y`.

### Value

All functions return a `list` of elements `"x"` and `"y"` each being a two column matrix with m/z (first column) and intensity values (second column). The two matrices contain the matched peaks between input matrices `x` and `y` and hence have the same number of rows. Peaks present in `x` but not in the `y` input matrix have m/z and intensity values of `NA` in the result matrix for `y` (and vice versa).

### Implementation notes

A mapping function must take two numeric matrices `x` and `y` as input and must return `list` with two elements named `"x"` and `"y"` that represent the aligned input matrices. The function should also have `...` in its definition. Parameters `ppm` and `tolerance` are suggested but not required.

### Author(s)

Johannes Rainer, Michael Witting

### See Also

`gnps()`

### Examples

    x <- cbind(c(31.34, 50.14, 60.3, 120.9, 230, 514.13, 874.1),
        1:7)
    y <- cbind(c(12, 31.35, 70.3, 120.9 + ppm(120.9, 5),
        230 + ppm(230, 10), 315, 514.14, 901, 1202),
        1:9)

    ## No peaks with identical m/z
    joinPeaks(x, y, ppm = 0, type = "inner")

    ## With ppm 10 two peaks are overlapping
    joinPeaks(x, y, ppm = 10, type = "inner")

    ## Outer join: contain all peaks from x and y
    joinPeaks(x, y, ppm = 10, type = "outer")

    ## Left join: keep all peaks from x and those from y that match
    joinPeaks(x, y, ppm = 10, type = "left")

    ## Right join: keep all peaks from y and those from x that match. Using
    ## a constant tolerance of 0.01
    joinPeaks(x, y, tolerance = 0.01, type = "right")

    ## GNPS-like peak matching

    ## Define spectra
    x <- cbind(mz = c(10, 36, 63, 91, 93), intensity = c(14, 15, 999, 650, 1))
    y <- cbind(mz = c(10, 12, 50, 63, 105), intensity = c(35, 5, 16, 999, 450))
    ## The precursor m/z
    pmz_x <- 91
    pmz_y <- 105

    ## Plain joinPeaks identifies only 2 matching peaks: 1 and 5
    joinPeaks(x, y)

    ## joinPeaksGnps finds 4 matches
    joinPeaksGnps(x, y, pmz_x, pmz_y)

    ## with one of the two precursor m/z being NA, the result are the same as
    ## with joinPeaks (with type = "left").
    joinPeaksGnps(x, y, pmz_x, yPrecursorMz = NA)

[Package Spectra version 1.2.2 Index]