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)."
1---2name: mass-accuracy-ppm-filtering3description: 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.4license: CC-BY-4.05---67# mass-accuracy-ppm-filtering89## Summary1011Filter 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.1213## When to use1415When 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.1617## When NOT to use1819- When input is already a validated, annotated feature table (PPM filtering is upstream annotation step, not post-hoc validation).20- When dealing with low-resolution mass spectrometry data where mass accuracy is insufficient to distinguish between formulae (PPM filtering assumes sufficient resolution).21- When no theoretical m/z reference database or candidate formula set is available (PPM comparison requires both observed and theoretical values).2223## Inputs2425- observed m/z value (decimal numeric)26- candidate molecular formulae (chemical formula strings or structures)27- theoretical m/z values for each candidate (decimal numeric, precomputed)28- PPM threshold parameter (default: 5 ppm)2930## Outputs3132- filtered candidate formula set (formulae within PPM threshold)33- ranked formula list with PPM error scores34- confidence-scored formula network (when integrated into MLR model)3536## How to apply3738Calculate 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.3940## Related tools4142- **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/SMART4344## Examples4546```47py SMART.py -i 185.9934 -d smart.db -l lr_4f.pkl -p 0 -m 548```4950## Evaluation signals5152- PPM error values for all returned candidates fall within the specified PPM threshold (e.g., ≤5 ppm by default).53- Candidates are ranked in ascending order of absolute PPM error, confirming that lowest-error formulae appear first.54- When integrated into the MLR model, PPM scores contribute proportionally to final formula ranking alongside linked-formulae and DBEdges/BioEdges criteria.55- 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.56- Known positive formulae (from benchmarking datasets) are retained within the PPM threshold and ranked competitively vs. false positives.5758## Limitations5960- 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.61- 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.62- 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).6364## Evidence6566- [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"67- [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."68- [readme] PPM threshold for formula assignment (Default: 5).: "PPM threshold for formula assignment (Default: 5)."
HolobiomicsLab 