Metabolite Candidate Ranking Likelihood Scoring

---
name: metabolite-candidate-ranking-likelihood-scoring
description: Use when you have a query mass spectrum matched to multiple candidate metabolites (by accurate mass, database lookup, or spectral similarity), and you possess or can train a DNN model for retention time prediction on your target chromatographic method.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3801
  edam_topics:
  - http://edamontology.org/topic_0154
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_3407
  tools:
  - alvaDesc
  - cmmrt
derived_from:
- doi: 10.1186/s13321-022-00613-8
  title: cmmrt
evidence_spans:
- 5,666 molecular descriptors and 2,214 fingerprints (MACCS166, Extended Connectivity, and Path Fingerprints fingerprints) were generated with the alvaDesc software
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v1
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_cmmrt
    doi: 10.1186/s13321-022-00613-8
    title: cmmrt
  dedup_kept_from: coll_cmmrt
schema_version: 0.2.0
---

# metabolite-candidate-ranking-likelihood-scoring

## Summary

Convert predicted retention times and their uncertainties into probabilistic likelihood scores to rank candidate metabolite annotations in descending order of plausibility. This skill integrates deep neural network RT predictions with Bayesian meta-learned chromatographic projections to generate normalized probability densities that reflect both point estimates and prediction confidence.

## When to use

You have a query mass spectrum matched to multiple candidate metabolites (by accurate mass, database lookup, or spectral similarity), and you possess or can train a DNN model for retention time prediction on your target chromatographic method. Use this skill when you need to re-rank candidates by their likelihood of being the true metabolite, leveraging the fact that retention time is an independent, orthogonal feature to mass spectrometry that can disambiguate isobaric or co-eluting species. Apply this particularly when your reference chromatographic method differs from the analytical system used for your unknowns—the meta-learning projection bridges this gap with as few as 10 calibration molecules.

## When NOT to use

- Input candidates lack structural information (SMILES/InChI unavailable) or are not small molecules amenable to descriptor/fingerprint calculation.
- No trained DNN model exists for your chromatographic method and you cannot access or train one on 80,000+ reference RT measurements.
- Retention time is not expected to be predictive for your metabolite class (e.g., highly polar salts, metal complexes, or compounds with poor alvaDesc representation).

## Inputs

- Query mass spectrum (m/z, intensity pairs)
- Candidate metabolite structures (SMILES strings or InChI)
- Trained DNN retention time prediction model (weights and architecture)
- Molecular descriptor and fingerprint vectors (MACCS166, Extended Connectivity, Path Fingerprints generated by alvaDesc)
- Optional: calibration set of ≥10 molecules with known RTs in both reference and target chromatographic methods (for meta-learning projection)

## Outputs

- Ranked candidate list with retention time probability scores
- Per-candidate likelihood scores (normalized Gaussian kernel values or probability density estimates)
- Projected retention times for target chromatographic method (if meta-learning projection applied)
- Uncertainty bounds associated with each RT prediction

## How to apply

First, generate molecular descriptors and fingerprints (MACCS166, Extended Connectivity, Path Fingerprints) for all candidate metabolites using alvaDesc software from their SMILES or InChI structures. Second, apply your trained DNN model (regularized with cosine annealing warm restarts and stochastic weight averaging) to predict retention times for each candidate, obtaining both point estimates and associated uncertainty bounds (mean absolute error ~39.2±1.2 s). If predicting on a chromatographic method different from your training set, use the Bayesian meta-learning approach to project predicted RTs from the reference method to your target chromatographic method, requiring a minimum of 10 molecules with known retention times in both systems to calibrate the Gaussian Process prior. Finally, convert the projected RTs and their prediction uncertainties into RT-based likelihood scores by computing a normalized Gaussian kernel or probability density function for each candidate. Rank candidates by their likelihood score in descending order and output the ranked candidate list annotated with the corresponding RT probability scores.

## Related tools

- **alvaDesc** (Generate 5,666 molecular descriptors and 2,214 fingerprints (MACCS166, Extended Connectivity, Path Fingerprints) from candidate metabolite structures) — https://www.alvascience.com/alvadesc/
- **cmmrt** (Train DNN retention time prediction model with cosine annealing warm restarts and stochastic weight averaging; implement Bayesian meta-learning for RT projection between chromatographic methods) — https://github.com/constantino-garcia/cmmrt

## Examples

```
python cmmrt/rt/train_model.py --storage sqlite:///results/optuna/train.db --save_to saved_models && python -c "from cmmrt.rt import predict; candidates = [('caffeine', 'CN1C=NC2=C1C(=O)N(C(=O)N2C)C'), ...]; scores = predict.rank_by_rt_likelihood(candidates, model_path='saved_models', calibration_set=calibration_df)"
```

## Evaluation signals

- Mean absolute error (MAE) of RT predictions on held-out test set is ≤ 39.2±1.2 s, matching or exceeding the article's DNN baseline.
- Ranked candidate order places true metabolite (confirmed by orthogonal method or database) within top-3 predictions for ≥85% of test queries.
- Likelihood scores are properly normalized (sum to 1.0 if using probability distribution, or are bounded [0,1] if using kernel density).
- When meta-learning projection is applied, projected RTs fall within ±50 s of experimentally measured RTs for calibration molecules (demonstrating successful GP calibration).
- Uncertainty bounds expand appropriately for out-of-distribution structural features or extreme predicted RT values, preventing overconfident rankings.

## Limitations

- Fingerprint-based RT prediction can degrade for novel structures underrepresented in the METLIN training set (80,038 molecules); descriptor-only or combined descriptor+fingerprint models perform worse than fingerprints alone.
- Meta-learning projection requires at least 10 calibration molecules measured in both reference and target chromatographic methods; smaller calibration sets may yield unstable Gaussian Process priors.
- Bayesian meta-learning error rates remain competitive but are not strictly superior to previous projection methods; gains are primarily in sample efficiency (few molecules needed) rather than absolute accuracy.
- Prediction is deterministic given DNN weights; if the DNN is overfit or undertrained, likelihood scores will be miscalibrated regardless of post-hoc uncertainty quantification.

## Evidence

- [readme] 5,666 molecular descriptors and 2,214 fingerprints (MACCS166, Extended Connectivity, and Path Fingerprints fingerprints) were generated with the alvaDesc software: "5,666 molecular descriptors and 2,214 fingerprints (MACCS166, Extended Connectivity, and Path Fingerprints fingerprints) were generated with the alvaDesc software"
- [readme] The best results were obtained by a heavily regularized DNN trained with cosine annealing warm restarts and stochastic weight averaging, achieving a mean and median absolute errors of 39.2±1.2 s: "heavily regularized DNN trained with cosine annealing warm restarts and stochastic weight averaging, achieving a mean and median absolute errors of 39.2±1.2 s"
- [readme] A novel Bayesian meta-learning approach is proposed for RT projection between CMs from as few as 10 molecules while still obtaining competitive error rates compared with previous approaches.: "Bayesian meta-learning approach is proposed for RT projection between CMs from as few as 10 molecules while still obtaining competitive error rates"
- [other] Convert projected RTs and prediction uncertainties into RT-based likelihood scores (probability density or normalized Gaussian kernel).: "Convert projected RTs and prediction uncertainties into RT-based likelihood scores (probability density or normalized Gaussian kernel)"
- [readme] Results suggest that fingerprints tend to perform better.: "Results suggest that fingerprints tend to perform better"