AnnotateTable: Annotate a Peaktable

In yguitton/metaMS: MS-based metabolomics annotation pipeline

Annotate a Peaktable

Description

Functions which annotate a peaktable on the bases af a database of standards. Not meant to be called directly by the user.

Usage

## Annotate one feature
AnnotateFeature(input, DB, settings, errf)

## Annotate a full table of features
AnnotateTable(peaktable, errf, DB, settings)

Arguments

input	A vector with three elements in the form (mz,rt,I).
peaktable	A peaktable (matrix) with three column corresponding to mz,rt and I values for a series of features.
errf	The file containing the error function used to predict the tolerance on the m/z value used for the matching against the DB.
DB	A dataframe used for the annotation. See the help of LCDBtest for a description of the DB.
settings	The subset of settings contained into the "match2DB" element of the XCMSsettings list.

Details

The annotation of each feature is performed by comparing its m/z value and its retention time to a database provided by the user. To account for shifts in retention time and mass occurring during data acquisition, the matching of a specific feature against the DB is done with a specific tolerance in mass and in retention time.

Retention time tolerance
The retention time tolerance is specified (in minutes) in the settings list (field rttol). This value is instrument- and chromatography-dependent.

m/z tolerance
The tolerance on the mass scale mainly depends on the characteristics of the spectrometer used for the acquisition. For Q-TOF instruments it has been recently shown (see references) that the optimal mass tolerance can be expressed as a function of the m/z value and of the logarithm of the ion intensity log10(I). As a trend, the mass drift will be bigger for smaller ions and for low intensity signals.
In the present implementation the tolerance in mass can be either fixed over the complete mass range or calculated as a function of the mz and I values of each feature. In the simplest case, the fixed mass tolerance is provided in the mzwindow (in Dalton!) element of the list of settings.
Alternatively, one can provide (supplying the errf argument) a function used to calculate the mz tolerance (in ppm!) as a function of the fields of the input vector ((mz,rt,I)).
As discussed in the publication, for a Waters Synapt Q-TOF the function is a linear model taking as inputs M = input["mz"], logI = log10(input["I"]). This error function can be calculated by analyzing the results of the injections of the chemical standards. To avoid unreasonable small errors where data for mz and I are not available, the minimum value for the mass tolerance is explicitly set in the settings (ppm). This value should match the technical characteristics of the spectrometer.

To reduce the number of false positives and make the annotation more reliable, a match is retained only if more than one feature associated to a specific compound is found in the list of features. How many "validation" features are required is defined in the list of settings in the minfeat element. At this validation level, another retention time tolerance is introduced: two or more features validate one specific annotation if their retention time are not very much different. This rt tolerance is also defined in the settings (the rtval field). As a general suggestion, rtval should be kept smaller than rttol. The latter, indeed, refers to the matching of a peaktable with a database which has been created from the injections of the chemical standards during different instrumental runs (maybe also with different columns). On the other hand, rtval accounts for smaller retention time shifts, occurring within the same LC run.

For the description of the structure of the DB, refer to the help of the LCDBtest dataset.

Value

A list with the following elements

annotation.table	A data.frame withe the results of the annotation and the reference to the DB
compounds	The names of the annotated compounds
IDs	The IDs of the annotated compounds
multiple.annotations	The features with multiple annotations
ann.features	The features with annotation

Author(s)

Pietro Franceschi

References

N. Shahaf, P. Franceschi, P. Arapitsas, I. Rogachev, U. Vrhovsek and R. Wehrens: "Constructing a mass measurement error surface to improve automatic annotations in liquid chromatography/mass spectrometry based metabolomics". Rapid Communications in Mass Spectrometry, 27(21), 2425 (2013).

Examples

## Example of results
  data(GCresults) ## pre-compiled results
  GCresults$PeakTable

yguitton/metaMS documentation built on Feb. 27, 2023, 11:45 p.m.