Mass tolerance window calibration

mass-tolerance-window-calibration

Summary

Calibration and validation of mass tolerance windows used to match observed m/z values against theoretical adduct masses in metabolomics feature annotation. This skill ensures accurate assignment of ionization adducts by defining and testing appropriate tolerance thresholds for mass-matching logic.

When to use

When implementing adduct detection in LC-MS metabolomics workflows, after defining theoretical adduct mass offsets (e.g., [M+NH4]+ at +17.0266 Da, [M+K]+ at +38.9815 Da), and before assigning adduct labels to a feature table. Use this skill when you need to validate that mass-matching produces no false positives on a reference feature set.

When NOT to use

• Input feature table is already fully annotated with adduct types from another source
• Mass spectrometry data lack sufficient m/z resolution or calibration to distinguish adducts within the tolerance window
• No reference feature set with ground-truth adduct labels is available for validation

Inputs

• Feature table (CSV format, with observed m/z and intensity columns)
• Reference feature set with known adduct annotations (for validation)
• Defined adduct mass offsets and theoretical masses (as constants or configuration)

Outputs

• Labeled feature table with adduct annotations and assigned adduct types
• Verification report documenting assigned labels, accuracy metrics, and false positive count

How to apply

First, define the adduct mass offsets for each ionization species to be recognized (e.g., [M+NH4]+, [M+K]+, [M+H2O+H]+, [M-H2O+H]+) with their precise mass deltas in Daltons. Then, establish a mass tolerance window (e.g., within a specified ppm or Da threshold) around each theoretical adduct mass. Implement mass-matching logic that scans the input feature table and compares observed m/z values against theoretical adduct masses within this tolerance window. Run unit tests (using pytest) to validate that the detection correctly identifies each adduct type on a reference feature set and reports no false positives. Finally, generate a labeled feature table with adduct annotations and produce a verification report that lists assigned labels and their accuracy against known adducts.

Related tools

• pytest (Unit testing framework to validate adduct detection correctness, confirm no false positives, and verify that observed m/z values are correctly matched within mass tolerance windows)
• fermo_core (Core metabolomics processing library that implements adduct detection and feature annotation logic) — https://github.com/fermo-metabolomics/fermo_core
• FERMO (Dashboard and GUI that integrates metabolomics data with adduct detection for rapid hypothesis-driven analysis) — https://github.com/fermo-metabolomics/FERMO

Evaluation signals

• All reference features with known adducts are correctly identified and labeled in the output feature table
• False positive rate is zero or below a pre-specified threshold on the validation set
• No m/z values outside the defined tolerance window are incorrectly assigned to an adduct
• Unit test suite passes all adduct type detection tests (pytest output shows zero failures)
• Verification report documents exact match counts for each adduct species and overall accuracy percentage

Limitations

• Requires accurate prior calibration of the mass spectrometer; uncalibrated or poorly calibrated instruments may violate the tolerance window assumptions
• Only recognizes adduct types for which mass offsets have been explicitly defined; novel or unexpected ionization species will be missed
• Mass tolerance window must be chosen to balance specificity (avoiding false positives) and sensitivity (avoiding false negatives); overly tight windows may miss valid adducts with slight calibration drift

Evidence

• [other] Define adduct mass offsets for [M+NH4]+ (+17.0266 Da), [M+K]+ (+38.9815 Da), [M+H2O+H]+ (+19.0184 Da), and [M-H2O+H]+ (+1.0078 Da): "Define adduct mass offsets for [M+NH4]+ (+17.0266 Da), [M+K]+ (+38.9815 Da), [M+H2O+H]+ (+19.0184 Da), and [M-H2O+H]+ (+1.0078 Da) in the adduct detection module."
• [other] Implement mass-matching logic to scan input feature table and assign adduct labels by comparing observed m/z values against theoretical adduct masses within a specified mass tolerance window: "Implement mass-matching logic to scan an input feature table and assign adduct labels by comparing observed m/z values against theoretical adduct masses within a specified mass tolerance window."
• [other] Run pytest unit tests to validate that the adduct detection correctly identifies each adduct type on a reference feature set and reports no false positives: "Run pytest unit tests to validate that the adduct detection correctly identifies each adduct type on a reference feature set and reports no false positives."
• [other] Generate a labeled feature table with adduct annotations and produce a verification report listing assigned labels and their accuracy: "Generate a labeled feature table with adduct annotations and produce a verification report listing assigned labels and their accuracy."
• [other] FERMO implements adduct detection to recognize [M+NH4]+, [M+K]+, [M+H2O+H]+, and [M-H2O+H]+ as ionization adducts for feature mass labeling: "FERMO implements adduct detection to recognize [M+NH4]+, [M+K]+, [M+H2O+H]+, and [M-H2O+H]+ as ionization adducts for feature mass labeling."