# Mass Tolerance Window Filtering

> Use when after calculating neutral mass from observed m/z and adduct type, and before ranking candidates by chemical plausibility. Use it whenever querying a formula database (KEGG, PubChem, or custom) to retrieve all molecular formulae within a specified mass tolerance window of each neutral mass.

- Skill: `holobiomicslab/mass-tolerance-window-filtering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-tolerance-window-filtering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-tolerance-window-filtering/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-filtering

---


# mass-tolerance-window-filtering

## Summary

Filter candidate molecular formulae by mass error tolerance when matching observed m/z values to database entries. This skill constrains formula lookup results to a user-defined ppm or Da window around the neutral mass, reducing false positives and focusing candidate lists on chemically plausible assignments.

## When to use

Apply this skill after calculating neutral mass from observed m/z and adduct type, and before ranking candidates by chemical plausibility. Use it whenever querying a formula database (KEGG, PubChem, or custom) to retrieve all molecular formulae within a specified mass tolerance window of each neutral mass. It is essential when the database is large and you need to reduce the candidate set to interpretable size.

## When NOT to use

- Input is already a feature table (annotation/compound assignment is done; use this skill earlier in the workflow)
- Mass tolerance window is unknown or unavailable from the instrument (cannot proceed without specifying ppm or Da threshold)
- Formula database is empty, unavailable, or not built in MetaboShiny (build or import database first)

## Inputs

- observed m/z peak list (numeric vector or peaklist file)
- configured adduct definitions (e.g., [M+H]+, [M+Na]+, [M-H]−)
- mass tolerance threshold (numeric, in ppm or Da)
- formula database (KEGG, PubChem, or user-supplied CSV)

## Outputs

- filtered candidate formula table (rows = peaks, columns = formula, observed m/z, theoretical m/z, mass error, adduct type)
- candidate ranking by mass error
- tabulated results with per-peak formula assignments and mass error metrics

## How to apply

For each m/z peak in your input list, first apply the inverse of the configured adduct transformation (e.g., subtract 1.007825 for [M+H]+, subtract 22.989220 for [M+Na]+) to calculate the neutral mass. Then query the formula database with a mass tolerance window defined in parts per million (ppm) or Daltons (Da). The tolerance window is typically set during MetaboShiny project initialization (e.g., 5 ppm for high-resolution instruments). Return all candidate formulae whose theoretical m/z values fall within ±tolerance of the neutral mass. This filtering step greatly reduces computational load and prevents unlikely formulae from propagating to downstream plausibility scoring.

## Related tools

- **MetaboShiny** (Provides configurable adduct settings, formula database integration, and mass-tolerance-filtered candidate lookup within a unified workflow UI) — https://github.com/joannawolthuis/MetaboShiny
- **R** (Underlying language for mass-error calculation, database querying, and candidate filtering logic)
- **KEGG** (Formula database source for molecular formula candidates)
- **PubChem** (Formula database source for molecular formula candidates)

## Evaluation signals

- Candidate formulae returned have mass error (observed m/z − theoretical m/z) within the specified tolerance window (e.g., ≤5 ppm)
- No candidate formulae are returned with mass error exceeding the tolerance threshold
- Candidate count per peak is reduced by >90% relative to unfiltered database size, indicating effective filtering
- Mass error distribution is centered near zero with minimal outliers, suggesting correct neutral mass calculation and adduct inversion
- Downstream chemical plausibility scoring (element ratios, hydrogen deficiency) confirms candidates are chemically reasonable

## Limitations

- Filtering is only as good as the accuracy of the mass spectrometer and the configured mass tolerance; underestimating tolerance may exclude true positives, while overestimating may re-introduce false positives.
- The skill assumes adduct definitions are correct and complete; misconfigured adduct rules will propagate incorrect neutral masses to the tolerance filter.
- Formula databases (KEGG, PubChem) may have gaps, outdated records, or biases toward certain compound classes; custom databases must be manually curated and formatted.
- When multiple adducts are configured for the same peak, tolerance filtering produces separate candidate lists per adduct; ambiguity resolution requires downstream ranking or manual curation.

## Evidence

- [other] For each m/z value, calculate the neutral mass by applying the inverse of each configured adduct transformation (e.g., [M+H]+, [M+Na]+, [M-H]−).: "For each m/z value, calculate the neutral mass by applying the inverse of each configured adduct transformation (e.g., [M+H]+, [M+Na]+, [M-H]−)."
- [other] Query the formula database (KEGG, PubChem, or user-supplied) to retrieve all molecular formulae within the configured mass tolerance window (in ppm or Da) of each neutral mass.: "Query the formula database (KEGG, PubChem, or user-supplied) to retrieve all molecular formulae within the configured mass tolerance window (in ppm or Da) of each neutral mass."
- [readme] Set the error margin of your mass spectrometer in parts per million (ppm).: "Set the error margin of your mass spectrometer in parts per million (ppm)."
- [other] Rank candidate formulae by mass error and chemical plausibility rules (e.g., element ratios, hydrogen deficiency).: "Rank candidate formulae by mass error and chemical plausibility rules (e.g., element ratios, hydrogen deficiency)."
- [other] Return and tabulate the top-ranked candidates with their assigned formula, adduct type, observed m/z, theoretical m/z, and mass error for each peak.: "Return and tabulate the top-ranked candidates with their assigned formula, adduct type, observed m/z, theoretical m/z, and mass error for each peak."