Formula Annotation Ranking

---
name: formula-annotation-ranking
description: 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3629
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0625
  tools:
  - MetaboShiny
  - R
  techniques:
  - mass-spectrometry
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1007/s11306-020-01717-8
  title: MetaboShiny
evidence_spans:
- Welcome to the info page on MetaboShiny
- Welcome to the info page on MetaboShiny! We are currently on BioRXiv
- Through R
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_metaboshiny_cq
    doi: 10.1007/s11306-020-01717-8
    title: MetaboShiny
  dedup_kept_from: coll_metaboshiny_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1007/s11306-020-01717-8
  all_source_dois:
  - 10.1007/s11306-020-01717-8
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# 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."