mass-spectral-feature-annotation
Summary
Assign molecular formulae to mass-to-charge (m/z) features in spatially-resolved mass spectrometry imaging using a machine-learning-guided database search. This skill bridges a critical gap in MSI annotation precision by leveraging a 2.8-million-formula knowledge base interconnected by biochemical evidence to rank formula candidates.
When to use
You have m/z values from spatially-resolved mass spectrometry imaging (e.g., MALDI-MSI, DESI-MSI) and need to assign molecular formulae to thousands of features with higher precision than traditional LC-MS approaches. Apply this skill when annotation accuracy is critical and you have access to a polarity designation (positive or negative mode) and a target PPM tolerance (typical range 5–10 ppm).
When NOT to use
- Your input is already a fully annotated feature table (e.g., from a previous LC-MS workflow with high-confidence identifications); re-annotation may introduce noise.
- You lack access to a pre-built SMART database or trained model; the skill requires external data that is large (>1 TB in full form) and must be downloaded separately.
- Your ionization mode or polarity is unknown; the skill requires explicit polarity specification and will rank candidates incorrectly if polarity is misspecified.
Inputs
- m/z value(s) as floating-point numbers (e.g., 185.9934)
- ionization polarity designation ('+' for positive, '−' for negative, or '0' for both)
- SMART-Database file (smart.db or equivalent)
- trained multiple linear regression model file (e.g., lr_4f.pkl)
- PPM tolerance threshold (numeric; default 5)
Outputs
- ranked list of candidate molecular formulae with scores
- database source(s) for each formula (H=HMDB, E=ChEMBL, P=PubChem, K=KEGG)
- PPM deviation for each candidate
- structured results file with formula predictions and precision metrics
How to apply
Load the SMART platform with a KnownSet database comprising 2.8 million formulae cross-linked by DBEdges (from HMDB, ChEMBL, PubChem) and BioEdges (from KEGG). Input your m/z value(s) and specify ionization polarity. SMART applies a multiple linear regression model to extract formula networks associated with each m/z, then scores candidate formulae based on three criteria: (1) linked formulae in the network, (2) presence of DBEdges/BioEdges connecting candidates to known metabolites, and (3) deviation from the observed m/z in parts-per-million (PPM). Select the highest-scoring candidate, verify it falls within your PPM threshold (default 5 ppm), and confirm biochemical plausibility via database source tags. The rationale is that true metabolite formulae are more likely to cluster in well-connected regions of the biochemical reaction network and maintain mass accuracy; spurious candidates typically lack these co-occurrence and edge support.
Related tools
- SMART (open-source platform that integrates the KnownSet database, multiple linear regression model, and scoring logic for formula assignment in mass spectrometry imaging) — https://github.com/bioinfo-ibms-pumc/SMART
Examples
python SMART.py -i 185.9934 -d smart.db -l lr_4f.pkl -p 0
Evaluation signals
- Predicted formulae match reference annotations on benchmarking datasets with reported precision metrics (as quantified in Cao et al.)
- PPM deviation of top-ranked prediction falls within the specified threshold (e.g., ≤5 ppm)
- Top-ranked candidate appears in at least one of the four database sources (HMDB, ChEMBL, PubChem, KEGG), indicating strong evidence linkage
- For multi-candidate scenarios, candidates with higher DBEdge/BioEdge support rank higher than isolated formulae, confirming network-informed scoring
- Predictions remain stable across repeated runs with identical inputs and parameters
Limitations
- The full raw SMART database (>1 Terabyte) is not publicly available; users must download a temporary reduced version (HMDB subset) or contact authors for full access.
- Annotation precision is still lower than LC-MS-based approaches in some contexts, indicating that spatially-resolved MSI retains inherent chemical complexity.
- The multiple linear regression model was trained on specific datasets; performance may degrade if input m/z distributions or ionization conditions diverge significantly from training data.
- Formula ranking depends critically on database completeness and edge annotation accuracy; rare or novel metabolites not present in HMDB/ChEMBL/PubChem/KEGG will not be ranked correctly.
Evidence
- [readme] spatially-resolved metabolomics plays a critical role in unraveling tissue-specific metabolic complexities. Despite significance, this profound technology generates thousands of features, the accurate annotation of which lags notably behind LC-MS based approaches.: "the accurate annotation of which lags notably behind LC-MS based approaches"
- [readme] SMART constructs a KnownSet database that comprise 2.8 million formulae interconnected by DBEdges sourced from repositories such as HMDB, ChEMBL, PubChem, and BioEdges from KEGG biological reactant pairs.: "SMART constructs a KnownSet database that comprise 2.8 million formulae interconnected by DBEdges sourced from repositories such as HMDB, ChEMBL, PubChem, and BioEdges from KEGG"
- [readme] By employing a multiple linear regression model, SMART extracts formula networks associated with the m/z of interest and scores potential candidates based on various criteria, including linked formulae, DBEdges/BioEdges, and PPMs ppms values.: "By employing a multiple linear regression model, SMART extracts formula networks associated with the m/z of interest and scores potential candidates based on various criteria, including linked"
- [intro] Benchmarking on reference datasets demonstrates SMART is able to predict the formulae with a desirable precision.: "Benchmarking on reference datasets demonstrates SMART is able to predict the formulae with a desirable precision"
- [readme] Type m/z values in the left input text(such as 185.9934), and then set up all the parameters in the middle. Click the 'Predict' button and results will be shown in the right table (DB: H:HMDB, E:chEMBL, P:PubChem).: "Type m/z values in the left input text(such as 185.9934), and then set up all the parameters in the middle. Click the 'Predict' button and results will be shown in the right table"
1---2name: mass-spectral-feature-annotation-33description: Use when you have m/z values from spatially-resolved mass spectrometry imaging (e.g., MALDI-MSI, DESI-MSI) and need to assign molecular formulae to thousands of features with higher precision than traditional LC-MS approaches.4license: CC-BY-4.05---67# mass-spectral-feature-annotation89## Summary1011Assign molecular formulae to mass-to-charge (m/z) features in spatially-resolved mass spectrometry imaging using a machine-learning-guided database search. This skill bridges a critical gap in MSI annotation precision by leveraging a 2.8-million-formula knowledge base interconnected by biochemical evidence to rank formula candidates.1213## When to use1415You have m/z values from spatially-resolved mass spectrometry imaging (e.g., MALDI-MSI, DESI-MSI) and need to assign molecular formulae to thousands of features with higher precision than traditional LC-MS approaches. Apply this skill when annotation accuracy is critical and you have access to a polarity designation (positive or negative mode) and a target PPM tolerance (typical range 5–10 ppm).1617## When NOT to use1819- Your input is already a fully annotated feature table (e.g., from a previous LC-MS workflow with high-confidence identifications); re-annotation may introduce noise.20- You lack access to a pre-built SMART database or trained model; the skill requires external data that is large (>1 TB in full form) and must be downloaded separately.21- Your ionization mode or polarity is unknown; the skill requires explicit polarity specification and will rank candidates incorrectly if polarity is misspecified.2223## Inputs2425- m/z value(s) as floating-point numbers (e.g., 185.9934)26- ionization polarity designation ('+' for positive, '−' for negative, or '0' for both)27- SMART-Database file (smart.db or equivalent)28- trained multiple linear regression model file (e.g., lr_4f.pkl)29- PPM tolerance threshold (numeric; default 5)3031## Outputs3233- ranked list of candidate molecular formulae with scores34- database source(s) for each formula (H=HMDB, E=ChEMBL, P=PubChem, K=KEGG)35- PPM deviation for each candidate36- structured results file with formula predictions and precision metrics3738## How to apply3940Load the SMART platform with a KnownSet database comprising 2.8 million formulae cross-linked by DBEdges (from HMDB, ChEMBL, PubChem) and BioEdges (from KEGG). Input your m/z value(s) and specify ionization polarity. SMART applies a multiple linear regression model to extract formula networks associated with each m/z, then scores candidate formulae based on three criteria: (1) linked formulae in the network, (2) presence of DBEdges/BioEdges connecting candidates to known metabolites, and (3) deviation from the observed m/z in parts-per-million (PPM). Select the highest-scoring candidate, verify it falls within your PPM threshold (default 5 ppm), and confirm biochemical plausibility via database source tags. The rationale is that true metabolite formulae are more likely to cluster in well-connected regions of the biochemical reaction network and maintain mass accuracy; spurious candidates typically lack these co-occurrence and edge support.4142## Related tools4344- **SMART** (open-source platform that integrates the KnownSet database, multiple linear regression model, and scoring logic for formula assignment in mass spectrometry imaging) — https://github.com/bioinfo-ibms-pumc/SMART4546## Examples4748```49python SMART.py -i 185.9934 -d smart.db -l lr_4f.pkl -p 050```5152## Evaluation signals5354- Predicted formulae match reference annotations on benchmarking datasets with reported precision metrics (as quantified in Cao et al.)55- PPM deviation of top-ranked prediction falls within the specified threshold (e.g., ≤5 ppm)56- Top-ranked candidate appears in at least one of the four database sources (HMDB, ChEMBL, PubChem, KEGG), indicating strong evidence linkage57- For multi-candidate scenarios, candidates with higher DBEdge/BioEdge support rank higher than isolated formulae, confirming network-informed scoring58- Predictions remain stable across repeated runs with identical inputs and parameters5960## Limitations6162- The full raw SMART database (>1 Terabyte) is not publicly available; users must download a temporary reduced version (HMDB subset) or contact authors for full access.63- Annotation precision is still lower than LC-MS-based approaches in some contexts, indicating that spatially-resolved MSI retains inherent chemical complexity.64- The multiple linear regression model was trained on specific datasets; performance may degrade if input m/z distributions or ionization conditions diverge significantly from training data.65- Formula ranking depends critically on database completeness and edge annotation accuracy; rare or novel metabolites not present in HMDB/ChEMBL/PubChem/KEGG will not be ranked correctly.6667## Evidence6869- [readme] spatially-resolved metabolomics plays a critical role in unraveling tissue-specific metabolic complexities. Despite significance, this profound technology generates thousands of features, the accurate annotation of which lags notably behind LC-MS based approaches.: "the accurate annotation of which lags notably behind LC-MS based approaches"70- [readme] SMART constructs a KnownSet database that comprise 2.8 million formulae interconnected by DBEdges sourced from repositories such as HMDB, ChEMBL, PubChem, and BioEdges from KEGG biological reactant pairs.: "SMART constructs a KnownSet database that comprise 2.8 million formulae interconnected by DBEdges sourced from repositories such as HMDB, ChEMBL, PubChem, and BioEdges from KEGG"71- [readme] By employing a multiple linear regression model, SMART extracts formula networks associated with the m/z of interest and scores potential candidates based on various criteria, including linked formulae, DBEdges/BioEdges, and PPMs ppms values.: "By employing a multiple linear regression model, SMART extracts formula networks associated with the m/z of interest and scores potential candidates based on various criteria, including linked"72- [intro] Benchmarking on reference datasets demonstrates SMART is able to predict the formulae with a desirable precision.: "Benchmarking on reference datasets demonstrates SMART is able to predict the formulae with a desirable precision"73- [readme] Type m/z values in the left input text(such as 185.9934), and then set up all the parameters in the middle. Click the 'Predict' button and results will be shown in the right table (DB: H:HMDB, E:chEMBL, P:PubChem).: "Type m/z values in the left input text(such as 185.9934), and then set up all the parameters in the middle. Click the 'Predict' button and results will be shown in the right table"
HolobiomicsLab 