joinPeaks: Join (map) peaks of two spectra
In rformassspectrometry/Spectra: Spectra Infrastructure for Mass Spectrometry Data

joinPeaks

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, MsCoreUtils::gnps() should be called on the aligned peak matrices (i.e. compareSpectra should be called with MAPFUN = joinPeaksGnps and FUN = MsCoreUtils::gnps).
joinPeaksNone(): does not perform any peak matching but simply returns the peak matrices in a list. This function should be used with the MAPFUN parameter of compareSpectra() if the spectra similarity function used (parameter FUN of compareSpectra()) performs its own peak matching and does hence not expect matched peak matrices as an input.

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",
  ...
)

joinPeaksNone(x, y, ...)

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

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)

rformassspectrometry/Spectra documentation built on Dec. 19, 2024, 1:05 p.m.