# Mass Accuracy Ppm Filtering

> Use when when you have a set of candidate molecular formulae for a measured m/z value and need to rank them by how closely their theoretical m/z matches the observed value.

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

---


# mass-accuracy-ppm-filtering

## Summary

Filter and rank candidate molecular formulae by mass accuracy using parts-per-million (PPM) error thresholds, a key criterion in the SMART multiple linear regression scoring pipeline for m/z-based formula assignment in mass spectrometry imaging.

## When to use

When you have a set of candidate molecular formulae for a measured m/z value and need to rank them by how closely their theoretical m/z matches the observed value. Use this when PPM mass accuracy is a scoring criterion in a formula assignment or annotation workflow, particularly in spatially-resolved metabolomics where feature annotation precision lags behind LC-MS.

## When NOT to use

- When input is already a validated, annotated feature table (PPM filtering is upstream annotation step, not post-hoc validation).
- When dealing with low-resolution mass spectrometry data where mass accuracy is insufficient to distinguish between formulae (PPM filtering assumes sufficient resolution).
- When no theoretical m/z reference database or candidate formula set is available (PPM comparison requires both observed and theoretical values).

## Inputs

- observed m/z value (decimal numeric)
- candidate molecular formulae (chemical formula strings or structures)
- theoretical m/z values for each candidate (decimal numeric, precomputed)
- PPM threshold parameter (default: 5 ppm)

## Outputs

- filtered candidate formula set (formulae within PPM threshold)
- ranked formula list with PPM error scores
- confidence-scored formula network (when integrated into MLR model)

## How to apply

Calculate the mass error in PPM between the observed m/z value and the theoretical m/z of each candidate formula using the formula: PPM = ((observed_mz − theoretical_mz) / theoretical_mz) × 10^6. Filter candidate formulae to retain only those within a specified PPM threshold (default: 5 ppm in SMART). Rank the retained candidates by absolute PPM error, with lower PPM error indicating higher confidence. Include PPM values as one of three criteria in a multiple linear regression model alongside linked formulae connections and DBEdges/BioEdges relationship strength to produce a final confidence-ranked formula network.

## Related tools

- **SMART** (integrates PPM-based filtering as one of three criteria in a multiple linear regression model to score and rank candidate formulae from formula networks extracted from the KnownSet database) — https://github.com/bioinfo-ibms-pumc/SMART

## Examples

```
py SMART.py -i 185.9934 -d smart.db -l lr_4f.pkl -p 0 -m 5
```

## Evaluation signals

- PPM error values for all returned candidates fall within the specified PPM threshold (e.g., ≤5 ppm by default).
- Candidates are ranked in ascending order of absolute PPM error, confirming that lowest-error formulae appear first.
- When integrated into the MLR model, PPM scores contribute proportionally to final formula ranking alongside linked-formulae and DBEdges/BioEdges criteria.
- The number of filtered candidates is reasonable (typically 1–10 per m/z) and does not collapse the candidate space to zero nor explode to implausibly many hits.
- Known positive formulae (from benchmarking datasets) are retained within the PPM threshold and ranked competitively vs. false positives.

## Limitations

- PPM threshold sensitivity: Too stringent a threshold (e.g., <2 ppm) may exclude correct formulae due to instrument calibration drift or isotope effects; too lenient (e.g., >10 ppm) may retain too many candidates, reducing discriminative power.
- Does not account for adduct formation, fragmentation, or neutral loss; PPM filtering is applied to the observed m/z directly and must be calibrated for the ionization mode (+/−/0 polarity) used in the experiment.
- Formula candidate set quality directly impacts output: PPM filtering cannot recover correct formulae if they are not present in the underlying KnownSet database (2.8 million formulae from HMDB, ChEMBL, PubChem, KEGG).

## Evidence

- [readme] scores potential candidates based on various criteria, including linked formulae, DBEdges/BioEdges, and PPMs ppms values: "scores potential candidates based on various criteria, including linked formulae, DBEdges/BioEdges, and PPMs ppms values"
- [other] Score each candidate formula using criteria including linked formulae connections, DBEdges/BioEdges relationship strength, and PPM mass accuracy values.: "Score each candidate formula using criteria including linked formulae connections, DBEdges/BioEdges relationship strength, and PPM mass accuracy values."
- [readme] PPM threshold for formula assignment (Default: 5).: "PPM threshold for formula assignment (Default: 5)."