metabolite-ranking-by-annotation-score
Summary
Rank candidate metabolites by comparing experimental MS/MS peaks against theoretical fragment ions using cosine similarity or peak-matching algorithms. This skill identifies the most probable metabolite annotations from a scored candidate list, enabling prioritization of biochemically relevant hits in untargeted metabolomics workflows.
When to use
When you have generated a set of candidate metabolites for a given experimental MS/MS spectrum and need to determine which candidate is most likely to be the true metabolite. Apply this skill after in silico fragmentation has produced theoretical fragment ion patterns for each candidate, and experimental peaks have been acquired from a high-resolution mass spectrometer in mzML, mzXML, or equivalent format.
When NOT to use
- Input candidate set contains only a single metabolite (ranking is not meaningful).
- Experimental MS/MS spectrum is of insufficient quality (e.g., <5 reliable peaks or very low signal-to-noise ratio).
- Theoretical fragment ion library is unavailable or not pre-computed for the candidate set.
Inputs
- experimental MS/MS spectrum (m/z and intensity pairs)
- set of candidate metabolite structures with molecular formulas
- theoretical fragment ion predictions for each candidate
Outputs
- ranked list of metabolite candidates with annotation scores
- match statistics per candidate (cosine similarity, matched peak count, mass error)
How to apply
For each candidate metabolite, calculate theoretical fragment ions using established fragmentation rules. Compare the experimental MS/MS peak list against the theoretical fragments for each candidate by computing cosine similarity or peak-matching scores, which quantify the overlap and intensity agreement between observed and predicted peaks. Score each candidate according to the quality of this match. Rank all candidates by descending annotation score, with the highest-scoring candidate representing the most probable metabolite identity. Output the ranked list with match statistics (e.g., cosine similarity values, number of matched peaks, mass error in ppm) to allow downstream filtering and confidence assessment.
Related tools
- MAGMa (performs in silico metabolite annotation including candidate generation, theoretical fragmentation, and ranking by peak-matching score) — https://github.com/NLeSC/MAGMa
Evaluation signals
- Ranked list contains all candidate metabolites with no duplicates and scores in descending order.
- Annotation scores (cosine similarity or peak-matching metric) fall within expected range [0, 1] or are monotonically bounded.
- Top-ranked metabolite shows mass error within instrument tolerance (typically <5 ppm for high-resolution MS) and matched peak count ≥3.
- Comparison of ranked scores against known standard compounds (if available) shows the true metabolite ranked in top-N (e.g., top-3) candidates.
- Output schema includes all expected fields: metabolite identifier/name, annotation score, matched peak count, mass error, and rank position.
Limitations
- Ranking accuracy depends critically on the quality and completeness of the theoretical fragmentation model; incorrect fragmentation rules will produce misleading scores.
- Cosine similarity and peak-matching algorithms are sensitive to mass calibration errors and instrument-specific peak intensity variation, which can misrank candidates with similar fragment patterns.
- PubChem database lookup may miss novel, biosynthetic, or rare metabolites not in the reference database, limiting the candidate set.
- High spectral noise or low precursor mass resolution can reduce discrimination between candidates with overlapping fragment ion patterns.
Evidence
- [other] Score each candidate by comparing experimental MS/MS peaks against theoretical fragments using cosine similarity or peak-matching algorithm.: "Score each candidate by comparing experimental MS/MS peaks against theoretical fragments using cosine similarity or peak-matching algorithm."
- [other] Rank metabolite candidates by annotation score and output ranked list with match statistics.: "Rank metabolite candidates by annotation score and output ranked list with match statistics."
- [other] Calculate theoretical fragment ions for each candidate metabolite via fragmentation rules.: "Calculate theoretical fragment ions for each candidate metabolite via fragmentation rules."
- [readme] The project develops chemo-informatics based methods for metabolite identification and biochemical network reconstruction in an integrative metabolomics data analysis workflow.: "The project develops chemo-informatics based methods for metabolite identification and biochemical network reconstruction in an integrative metabolomics data analysis workflow."
1---2name: metabolite-ranking-by-annotation-score-23description: Use when when you have generated a set of candidate metabolites for a given experimental MS/MS spectrum and need to determine which candidate is most likely to be the true metabolite.4license: CC-BY-4.05---67# metabolite-ranking-by-annotation-score89## Summary1011Rank candidate metabolites by comparing experimental MS/MS peaks against theoretical fragment ions using cosine similarity or peak-matching algorithms. This skill identifies the most probable metabolite annotations from a scored candidate list, enabling prioritization of biochemically relevant hits in untargeted metabolomics workflows.1213## When to use1415When you have generated a set of candidate metabolites for a given experimental MS/MS spectrum and need to determine which candidate is most likely to be the true metabolite. Apply this skill after in silico fragmentation has produced theoretical fragment ion patterns for each candidate, and experimental peaks have been acquired from a high-resolution mass spectrometer in mzML, mzXML, or equivalent format.1617## When NOT to use1819- Input candidate set contains only a single metabolite (ranking is not meaningful).20- Experimental MS/MS spectrum is of insufficient quality (e.g., <5 reliable peaks or very low signal-to-noise ratio).21- Theoretical fragment ion library is unavailable or not pre-computed for the candidate set.2223## Inputs2425- experimental MS/MS spectrum (m/z and intensity pairs)26- set of candidate metabolite structures with molecular formulas27- theoretical fragment ion predictions for each candidate2829## Outputs3031- ranked list of metabolite candidates with annotation scores32- match statistics per candidate (cosine similarity, matched peak count, mass error)3334## How to apply3536For each candidate metabolite, calculate theoretical fragment ions using established fragmentation rules. Compare the experimental MS/MS peak list against the theoretical fragments for each candidate by computing cosine similarity or peak-matching scores, which quantify the overlap and intensity agreement between observed and predicted peaks. Score each candidate according to the quality of this match. Rank all candidates by descending annotation score, with the highest-scoring candidate representing the most probable metabolite identity. Output the ranked list with match statistics (e.g., cosine similarity values, number of matched peaks, mass error in ppm) to allow downstream filtering and confidence assessment.3738## Related tools3940- **MAGMa** (performs in silico metabolite annotation including candidate generation, theoretical fragmentation, and ranking by peak-matching score) — https://github.com/NLeSC/MAGMa4142## Evaluation signals4344- Ranked list contains all candidate metabolites with no duplicates and scores in descending order.45- Annotation scores (cosine similarity or peak-matching metric) fall within expected range [0, 1] or are monotonically bounded.46- Top-ranked metabolite shows mass error within instrument tolerance (typically <5 ppm for high-resolution MS) and matched peak count ≥3.47- Comparison of ranked scores against known standard compounds (if available) shows the true metabolite ranked in top-N (e.g., top-3) candidates.48- Output schema includes all expected fields: metabolite identifier/name, annotation score, matched peak count, mass error, and rank position.4950## Limitations5152- Ranking accuracy depends critically on the quality and completeness of the theoretical fragmentation model; incorrect fragmentation rules will produce misleading scores.53- Cosine similarity and peak-matching algorithms are sensitive to mass calibration errors and instrument-specific peak intensity variation, which can misrank candidates with similar fragment patterns.54- PubChem database lookup may miss novel, biosynthetic, or rare metabolites not in the reference database, limiting the candidate set.55- High spectral noise or low precursor mass resolution can reduce discrimination between candidates with overlapping fragment ion patterns.5657## Evidence5859- [other] Score each candidate by comparing experimental MS/MS peaks against theoretical fragments using cosine similarity or peak-matching algorithm.: "Score each candidate by comparing experimental MS/MS peaks against theoretical fragments using cosine similarity or peak-matching algorithm."60- [other] Rank metabolite candidates by annotation score and output ranked list with match statistics.: "Rank metabolite candidates by annotation score and output ranked list with match statistics."61- [other] Calculate theoretical fragment ions for each candidate metabolite via fragmentation rules.: "Calculate theoretical fragment ions for each candidate metabolite via fragmentation rules."62- [readme] The project develops chemo-informatics based methods for metabolite identification and biochemical network reconstruction in an integrative metabolomics data analysis workflow.: "The project develops chemo-informatics based methods for metabolite identification and biochemical network reconstruction in an integrative metabolomics data analysis workflow."
HolobiomicsLab 