# Mass Tolerance Window Calibration

> Use when 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.

- Skill: `holobiomicslab/mass-tolerance-window-calibration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-tolerance-window-calibration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-tolerance-window-calibration/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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."