Reconstruct the isotope scoring module for candidate annotations
Summary
Rank and filter candidate molecular formula and adduct annotations by computing isotope scores that measure similarity between observed and theoretical isotopic patterns. This skill is essential in untargeted metabolomics workflows to prioritize the most chemically plausible annotations from large candidate lists generated by database searching.
When to use
Apply this skill after generating candidate formula/adduct pairs from m/z database matching but before final metabolite annotation. Use it when you have observed isotopic patterns from feature detection (e.g., from XCMS or MSnbase output) and need to disambiguate multiple candidates with similar m/z values by leveraging high-resolution isotope ratio information.
When NOT to use
- Input m/z data lacks isotopic fine structure or is acquired at low mass resolution (e.g., unit resolution instruments); isotope scoring requires sufficient resolving power to detect isotopic patterns
- Candidates already have high-confidence annotations from orthogonal methods (e.g., authentic standard matching); isotope scoring adds marginal value when chemical identity is established
- Intensity imprecision or calibration of observed isotope ratios is unknown; scoring accuracy depends on reliable peak intensity quantification
Inputs
- Candidate molecular formula and adduct pairs (CSV or table format)
- Observed m/z isotopic patterns from feature detection (peak intensities and m/z values)
- Isotope scoring configuration (method selection, intensity imprecision threshold)
Outputs
- Ranked annotation table with isotope scores per candidate
- Filtered candidate set (above threshold only)
- Similarity metrics (cosine similarity or intensity correlation values)
How to apply
Load candidate formula/adduct pairs alongside their corresponding observed m/z isotopic patterns from feature detection output. For each candidate, calculate the theoretical isotopic pattern using the molecular formula and specified adduct (e.g., [M+H]+ or [M+Na]+). Compute an isotope score by measuring similarity between observed and theoretical patterns using cosine similarity or intensity correlation. Apply the isotope scoring threshold filters configured in MetaboShiny's Isotope scoring settings panel (including intensity imprecision, typically set at 2% default). Finally, rank all candidates by isotope score in descending order and export the ranked annotation table with scores; candidates exceeding the configured threshold are retained for downstream analysis.
Related tools
- MetaboShiny (Provides the Isotope scoring configuration panel and ranked annotation output interface; orchestrates theoretical isotope pattern calculation and threshold filtering within the pre-analysis workflow) — https://github.com/joannawolthuis/MetaboShiny
- R (Underlying computational engine for isotope pattern simulation, similarity metric calculation, and candidate ranking)
Evaluation signals
- Isotope scores for all candidates are numeric, bounded (0–1 for cosine similarity), and comparable across candidates for the same feature
- Candidates ranked by descending isotope score show chemical plausibility: true molecular formulas should rank higher than spurious matches with similar m/z
- Filtered output contains only candidates with isotope scores ≥ the configured threshold; no candidates below threshold remain in the ranked table
- Observed and theoretical isotope patterns exhibit high visual overlap (in chromatograms or mass spectra plots) for top-ranked candidates
- Reproducibility check: re-running the workflow with identical settings and intensity imprecision threshold produces identical rankings
Limitations
- Currently only M-score method is available for isotope scoring; alternative similarity metrics are not yet implemented
- Accuracy depends critically on correct theoretical isotope pattern calculation, which requires accurate molecular formulas and properly defined adduct rules
- Intensity imprecision (default 2%) is a fixed parameter; users must tune this threshold based on instrument calibration and sample type, and no guidance is provided for selecting it
- Isotope scoring does not account for adduct-specific fragmentation or in-source modifications that may alter observed patterns; patterns from heavily modified ions may not match theory
- Low-abundance isotopologs (e.g., 13C2, 37Cl) may fall below detection limits, leading to incomplete observed patterns that artificially penalize correct candidates
Evidence
- [other] How does the isotope scoring mechanism rank and filter candidate molecular formula and adduct annotations based on observed isotopic pattern matching?: "How does the isotope scoring mechanism rank and filter candidate molecular formula and adduct annotations based on observed isotopic pattern matching?"
- [other] For each candidate, calculate the theoretical isotopic pattern using the molecular formula and specified adduct. 3. Compute isotope score by measuring the similarity between observed and theoretical patterns (e.g., cosine similarity or intensity correlation).: "For each candidate, calculate the theoretical isotopic pattern using the molecular formula and specified adduct. 3. Compute isotope score by measuring the similarity between observed and theoretical"
- [other] MetaboShiny includes an Isotope scoring configuration setting as part of its pre-analysis workflow, located within the Settings section alongside Global, Project, Search, Adducts, and Formula prediction parameters.: "MetaboShiny includes an Isotope scoring configuration setting as part of its pre-analysis workflow, located within the Settings section alongside Global, Project, Search, Adducts, and Formula"
- [readme] Select the method to use to score compounds that have the same weight (currently only M-score available). Set the intensity imprecision (default: 2%).: "Select the method to use to score compounds that have the same weight (currently only M-score available). Set the intensity imprecision (default: 2%)."
- [other] Rank all candidates by isotope score in descending order and output the ranked annotation table with scores.: "Rank all candidates by isotope score in descending order and output the ranked annotation table with scores."
1---2name: formula-annotation-ranking-23description: Use when after generating candidate formula/adduct pairs from m/z database matching but before final metabolite annotation. Use it when you have observed isotopic patterns from feature detection (e.4license: CC-BY-4.05---67# Reconstruct the isotope scoring module for candidate annotations89## Summary1011Rank and filter candidate molecular formula and adduct annotations by computing isotope scores that measure similarity between observed and theoretical isotopic patterns. This skill is essential in untargeted metabolomics workflows to prioritize the most chemically plausible annotations from large candidate lists generated by database searching.1213## When to use1415Apply this skill after generating candidate formula/adduct pairs from m/z database matching but before final metabolite annotation. Use it when you have observed isotopic patterns from feature detection (e.g., from XCMS or MSnbase output) and need to disambiguate multiple candidates with similar m/z values by leveraging high-resolution isotope ratio information.1617## When NOT to use1819- Input m/z data lacks isotopic fine structure or is acquired at low mass resolution (e.g., unit resolution instruments); isotope scoring requires sufficient resolving power to detect isotopic patterns20- Candidates already have high-confidence annotations from orthogonal methods (e.g., authentic standard matching); isotope scoring adds marginal value when chemical identity is established21- Intensity imprecision or calibration of observed isotope ratios is unknown; scoring accuracy depends on reliable peak intensity quantification2223## Inputs2425- Candidate molecular formula and adduct pairs (CSV or table format)26- Observed m/z isotopic patterns from feature detection (peak intensities and m/z values)27- Isotope scoring configuration (method selection, intensity imprecision threshold)2829## Outputs3031- Ranked annotation table with isotope scores per candidate32- Filtered candidate set (above threshold only)33- Similarity metrics (cosine similarity or intensity correlation values)3435## How to apply3637Load candidate formula/adduct pairs alongside their corresponding observed m/z isotopic patterns from feature detection output. For each candidate, calculate the theoretical isotopic pattern using the molecular formula and specified adduct (e.g., [M+H]+ or [M+Na]+). Compute an isotope score by measuring similarity between observed and theoretical patterns using cosine similarity or intensity correlation. Apply the isotope scoring threshold filters configured in MetaboShiny's Isotope scoring settings panel (including intensity imprecision, typically set at 2% default). Finally, rank all candidates by isotope score in descending order and export the ranked annotation table with scores; candidates exceeding the configured threshold are retained for downstream analysis.3839## Related tools4041- **MetaboShiny** (Provides the Isotope scoring configuration panel and ranked annotation output interface; orchestrates theoretical isotope pattern calculation and threshold filtering within the pre-analysis workflow) — https://github.com/joannawolthuis/MetaboShiny42- **R** (Underlying computational engine for isotope pattern simulation, similarity metric calculation, and candidate ranking)4344## Evaluation signals4546- Isotope scores for all candidates are numeric, bounded (0–1 for cosine similarity), and comparable across candidates for the same feature47- Candidates ranked by descending isotope score show chemical plausibility: true molecular formulas should rank higher than spurious matches with similar m/z48- Filtered output contains only candidates with isotope scores ≥ the configured threshold; no candidates below threshold remain in the ranked table49- Observed and theoretical isotope patterns exhibit high visual overlap (in chromatograms or mass spectra plots) for top-ranked candidates50- Reproducibility check: re-running the workflow with identical settings and intensity imprecision threshold produces identical rankings5152## Limitations5354- Currently only M-score method is available for isotope scoring; alternative similarity metrics are not yet implemented55- Accuracy depends critically on correct theoretical isotope pattern calculation, which requires accurate molecular formulas and properly defined adduct rules56- Intensity imprecision (default 2%) is a fixed parameter; users must tune this threshold based on instrument calibration and sample type, and no guidance is provided for selecting it57- Isotope scoring does not account for adduct-specific fragmentation or in-source modifications that may alter observed patterns; patterns from heavily modified ions may not match theory58- Low-abundance isotopologs (e.g., 13C2, 37Cl) may fall below detection limits, leading to incomplete observed patterns that artificially penalize correct candidates5960## Evidence6162- [other] How does the isotope scoring mechanism rank and filter candidate molecular formula and adduct annotations based on observed isotopic pattern matching?: "How does the isotope scoring mechanism rank and filter candidate molecular formula and adduct annotations based on observed isotopic pattern matching?"63- [other] For each candidate, calculate the theoretical isotopic pattern using the molecular formula and specified adduct. 3. Compute isotope score by measuring the similarity between observed and theoretical patterns (e.g., cosine similarity or intensity correlation).: "For each candidate, calculate the theoretical isotopic pattern using the molecular formula and specified adduct. 3. Compute isotope score by measuring the similarity between observed and theoretical"64- [other] MetaboShiny includes an Isotope scoring configuration setting as part of its pre-analysis workflow, located within the Settings section alongside Global, Project, Search, Adducts, and Formula prediction parameters.: "MetaboShiny includes an Isotope scoring configuration setting as part of its pre-analysis workflow, located within the Settings section alongside Global, Project, Search, Adducts, and Formula"65- [readme] Select the method to use to score compounds that have the same weight (currently only M-score available). Set the intensity imprecision (default: 2%).: "Select the method to use to score compounds that have the same weight (currently only M-score available). Set the intensity imprecision (default: 2%)."66- [other] Rank all candidates by isotope score in descending order and output the ranked annotation table with scores.: "Rank all candidates by isotope score in descending order and output the ranked annotation table with scores."
HolobiomicsLab 