mass-accuracy-ppm-filtering
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
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-filtering-23description: 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> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Filter 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.1314## When to use1516When 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.1718## When NOT to use1920- When input is already a validated, annotated feature table (PPM filtering is upstream annotation step, not post-hoc validation).21- When dealing with low-resolution mass spectrometry data where mass accuracy is insufficient to distinguish between formulae (PPM filtering assumes sufficient resolution).22- When no theoretical m/z reference database or candidate formula set is available (PPM comparison requires both observed and theoretical values).2324## Inputs2526- observed m/z value (decimal numeric)27- candidate molecular formulae (chemical formula strings or structures)28- theoretical m/z values for each candidate (decimal numeric, precomputed)29- PPM threshold parameter (default: 5 ppm)3031## Outputs3233- filtered candidate formula set (formulae within PPM threshold)34- ranked formula list with PPM error scores35- confidence-scored formula network (when integrated into MLR model)3637## How to apply3839Calculate 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.4041## Related tools4243- **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/SMART4445## Examples4647```48py SMART.py -i 185.9934 -d smart.db -l lr_4f.pkl -p 0 -m 549```5051## Evaluation signals5253- PPM error values for all returned candidates fall within the specified PPM threshold (e.g., ≤5 ppm by default).54- Candidates are ranked in ascending order of absolute PPM error, confirming that lowest-error formulae appear first.55- When integrated into the MLR model, PPM scores contribute proportionally to final formula ranking alongside linked-formulae and DBEdges/BioEdges criteria.56- 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.57- Known positive formulae (from benchmarking datasets) are retained within the PPM threshold and ranked competitively vs. false positives.5859## Limitations6061- 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.62- 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.63- 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).6465## Evidence6667- [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"68- [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."69- [readme] PPM threshold for formula assignment (Default: 5).: "PPM threshold for formula assignment (Default: 5)."
HolobiomicsLab