formula-network-extraction-from-mz
Summary
Extract candidate molecular formulae and their interconnection networks for a given mass-to-charge (m/z) value by querying a precomputed database of 2.8 million formulae linked via chemical and biological edges, then rank them using a multiple linear regression model trained on mass accuracy, database connectivity, and biochemical relationship strength.
When to use
You have an observed m/z value from spatially-resolved mass spectrometry imaging and need to assign one or more plausible molecular formulae with confidence metrics. This skill is especially useful when LC-MS annotation methods are unavailable or when working with tissue-specific metabolomic features where chemical context (linked compound relationships, biochemical pathways) should inform the ranking.
When NOT to use
- Your m/z values are already annotated with high-confidence formulae from orthogonal methods (e.g. tandem MS fragmentation or standards); this skill is for de novo or consensus annotation when chemical context is limited.
- You lack calibrated mass accuracy (>10 ppm drift) or your instrument shows systematic m/z bias; the MLR model assumes reliable PPM values and will rank spurious matches if mass calibration is poor.
- Your metabolites are not expected to exist in HMDB, ChEMBL, PubChem, or KEGG (e.g. purely synthetic compounds, very recently discovered metabolites); the formula network relies on these databases.
Inputs
- m/z value (single numeric or list of m/z values in file format)
- ion polarity (+ / − / 0)
- PPM tolerance threshold (numeric; default 5)
- SMART-Database file (smart.db or equivalent)
- trained multiple linear regression model file (e.g. lr_4f.pkl)
Outputs
- ranked list of candidate molecular formulae
- formula network graph (linked formulae and edges)
- MLR confidence scores per formula
- source database origin per formula (HMDB/ChEMBL/PubChem)
- PPM deviation and mass accuracy metrics
How to apply
Load the precomputed SMART-Database (containing 2.8 million formulae with DBEdges from HMDB, ChEMBL, PubChem and BioEdges from KEGG). For each input m/z value, apply a multiple linear regression model to extract all formulae within a user-defined PPM tolerance (default 5 ppm). Score each candidate formula using three criteria: (1) the number and strength of linked formulae connections in the network (DBEdges/BioEdges), (2) biochemical relationship evidence (BioEdges from KEGG reactant pairs), and (3) mass accuracy (PPM deviation). Rank results by regression score and return the formula network with confidence metrics. The PPM threshold and polarity (positive/negative/neutral) are key parameters that must match your instrument calibration and ionization mode.
Related tools
Examples
python SMART.py -i 185.9934 -d smart.db -l lr_4f.pkl -p 0 -m 5
Evaluation signals
- Returned formula candidates fall within the specified PPM tolerance of the input m/z value.
- Formulae are chemically plausible (e.g. rational elemental composition, valid valence) and match known metabolite databases (HMDB/ChEMBL/PubChem).
- MLR scores correlate with network density (formulae with many DBEdges/BioEdges receive higher scores when mass accuracy is similar).
- Top-ranked formula can be validated against independent standards, MS/MS fragmentation patterns, or tissue-specific metabolic expectations.
- Formula network includes documented biochemical connections (KEGG BioEdges) that support the annotation in the biological context of the tissue/sample.
Limitations
- Accuracy of formula assignment is constrained by the completeness and correctness of HMDB, ChEMBL, PubChem, and KEGG databases; novel or very rare metabolites may not be captured.
- MLR model is trained on reference datasets; performance may degrade when m/z values or mass accuracy characteristics differ substantially from the training distribution.
- The full SMART-database exceeds 1 Terabyte; only a temporary HMDB-restricted version is publicly available. Access to the complete database requires contacting the developers.
- PPM tolerance is user-defined; setting it too high increases false positives; too low may miss valid formulae if instrument calibration drifts.
- Formula networks are static and reflect the state of source databases at database construction time; they do not update in real time as new compounds are discovered.
Evidence
- [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: "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"
- [readme] 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] 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] Since the raw SMART-database consists of huge number of formulae with their evidences, with database size exceeds 1 Terabyte, users who want to use the raw SMART-database can contact us: "Since the raw SMART-database consists of huge number of formulae with their evidences, with database size exceeds 1 Terabyte, users who want to use the raw SMART-database can contact us"
1---2name: formula-network-extraction-from-mz3description: Use when you have an observed m/z value from spatially-resolved mass spectrometry imaging and need to assign one or more plausible molecular formulae with confidence metrics.4license: CC-BY-4.05---67# formula-network-extraction-from-mz89## Summary1011Extract candidate molecular formulae and their interconnection networks for a given mass-to-charge (m/z) value by querying a precomputed database of 2.8 million formulae linked via chemical and biological edges, then rank them using a multiple linear regression model trained on mass accuracy, database connectivity, and biochemical relationship strength.1213## When to use1415You have an observed m/z value from spatially-resolved mass spectrometry imaging and need to assign one or more plausible molecular formulae with confidence metrics. This skill is especially useful when LC-MS annotation methods are unavailable or when working with tissue-specific metabolomic features where chemical context (linked compound relationships, biochemical pathways) should inform the ranking.1617## When NOT to use1819- Your m/z values are already annotated with high-confidence formulae from orthogonal methods (e.g. tandem MS fragmentation or standards); this skill is for de novo or consensus annotation when chemical context is limited.20- You lack calibrated mass accuracy (>10 ppm drift) or your instrument shows systematic m/z bias; the MLR model assumes reliable PPM values and will rank spurious matches if mass calibration is poor.21- Your metabolites are not expected to exist in HMDB, ChEMBL, PubChem, or KEGG (e.g. purely synthetic compounds, very recently discovered metabolites); the formula network relies on these databases.2223## Inputs2425- m/z value (single numeric or list of m/z values in file format)26- ion polarity (+ / − / 0)27- PPM tolerance threshold (numeric; default 5)28- SMART-Database file (smart.db or equivalent)29- trained multiple linear regression model file (e.g. lr_4f.pkl)3031## Outputs3233- ranked list of candidate molecular formulae34- formula network graph (linked formulae and edges)35- MLR confidence scores per formula36- source database origin per formula (HMDB/ChEMBL/PubChem)37- PPM deviation and mass accuracy metrics3839## How to apply4041Load the precomputed SMART-Database (containing 2.8 million formulae with DBEdges from HMDB, ChEMBL, PubChem and BioEdges from KEGG). For each input m/z value, apply a multiple linear regression model to extract all formulae within a user-defined PPM tolerance (default 5 ppm). Score each candidate formula using three criteria: (1) the number and strength of linked formulae connections in the network (DBEdges/BioEdges), (2) biochemical relationship evidence (BioEdges from KEGG reactant pairs), and (3) mass accuracy (PPM deviation). Rank results by regression score and return the formula network with confidence metrics. The PPM threshold and polarity (positive/negative/neutral) are key parameters that must match your instrument calibration and ionization mode.4243## Related tools4445- **SMART** (primary platform for formula network extraction and multiple linear regression-based formula assignment from m/z values) — https://github.com/bioinfo-ibms-pumc/SMART4647## Examples4849```50python SMART.py -i 185.9934 -d smart.db -l lr_4f.pkl -p 0 -m 551```5253## Evaluation signals5455- Returned formula candidates fall within the specified PPM tolerance of the input m/z value.56- Formulae are chemically plausible (e.g. rational elemental composition, valid valence) and match known metabolite databases (HMDB/ChEMBL/PubChem).57- MLR scores correlate with network density (formulae with many DBEdges/BioEdges receive higher scores when mass accuracy is similar).58- Top-ranked formula can be validated against independent standards, MS/MS fragmentation patterns, or tissue-specific metabolic expectations.59- Formula network includes documented biochemical connections (KEGG BioEdges) that support the annotation in the biological context of the tissue/sample.6061## Limitations6263- Accuracy of formula assignment is constrained by the completeness and correctness of HMDB, ChEMBL, PubChem, and KEGG databases; novel or very rare metabolites may not be captured.64- MLR model is trained on reference datasets; performance may degrade when m/z values or mass accuracy characteristics differ substantially from the training distribution.65- The full SMART-database exceeds 1 Terabyte; only a temporary HMDB-restricted version is publicly available. Access to the complete database requires contacting the developers.66- PPM tolerance is user-defined; setting it too high increases false positives; too low may miss valid formulae if instrument calibration drifts.67- Formula networks are static and reflect the state of source databases at database construction time; they do not update in real time as new compounds are discovered.6869## Evidence7071- [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: "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"72- [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"73- [readme] the accurate annotation of which lags notably behind LC-MS based approaches: "the accurate annotation of which lags notably behind LC-MS based approaches"74- [readme] 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"75- [readme] Since the raw SMART-database consists of huge number of formulae with their evidences, with database size exceeds 1 Terabyte, users who want to use the raw SMART-database can contact us: "Since the raw SMART-database consists of huge number of formulae with their evidences, with database size exceeds 1 Terabyte, users who want to use the raw SMART-database can contact us"
HolobiomicsLab 