# Structure Annotation Via Similarity Ranking

> Use when you have an unknown tandem MS spectrum and seek to assign a chemical structure by matching against a curated reference database (e.g., NIST, GNPS, or custom metabolite libraries) without requiring an exact spectral match.

- Skill: `holobiomicslab/structure-annotation-via-similarity-ranking` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/structure-annotation-via-similarity-ranking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/structure-annotation-via-similarity-ranking/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/structure-annotation-via-similarity-ranking

---


# structure-annotation-via-similarity-ranking

## Summary

Annotate unknown metabolite structures by embedding tandem MS spectra into a learned joint chemical space and ranking nearest-neighbor candidates from a reference database. This skill leverages contrastive learning to align spectrum embeddings with molecular fingerprint or chemical formula embeddings, enabling structure retrieval without direct database spectrum matching.

## When to use

Apply this skill when you have an unknown tandem MS spectrum and seek to assign a chemical structure by matching against a curated reference database (e.g., NIST, GNPS, or custom metabolite libraries) without requiring an exact spectral match. Use this when a pre-trained spectrum-to-embedding model is available or can be trained on paired spectra-structure data, and when the reference database has been encoded into the same joint embedding space.

## When NOT to use

- Input spectra are from instruments or ionization modes not represented in the training data; model generalization may be poor.
- Reference database is very small (<100 unique structures) or lacks diversity similar to the query spectrum's molecular class.
- Query spectrum has low signal-to-noise ratio or sparse fragmentation pattern; embeddings may be unreliable.
- No pre-trained or trainable contrastive model is available; standard database search methods (e.g., spectral cosine matching) are more appropriate.

## Inputs

- tandem mass spectrometry spectrum (MGF format or .ms file with m/z and intensity peak pairs)
- reference metabolite database with paired spectra and molecular structures (SMILES or structural fingerprints)
- pre-trained spectrum encoder model (MIST or equivalent transformer architecture)
- pre-trained chemical structure encoder model (fingerprint or formula transformer)

## Outputs

- ranked list of candidate structures with embedding similarity scores
- spectrum embedding vector in joint chemical space
- structure annotations with confidence metrics based on nearest-neighbor distance

## How to apply

Load tandem MS spectra and encode them using a pre-trained spectrum encoder (e.g., MIST transformer trained with contrastive loss). For each query spectrum, generate a continuous embedding in the joint chemical space. Encode a reference metabolite database (containing spectra and corresponding molecular structures or fingerprints) into the same embedding space using matched fingerprint or formula encoders. Perform nearest-neighbor similarity search in the embedding space using distance metrics (e.g., cosine, Euclidean) to retrieve the top-k candidate structures ranked by embedding proximity. The ranking score reflects the learned alignment between spectrum and structure representation; higher similarity indicates stronger agreement between the spectral fragmentation pattern and the candidate molecular structure.

## Related tools

- **MIST** (Transformer-based spectrum encoder trained with contrastive loss to generate spectrum embeddings aligned with fingerprint embeddings; used to encode query spectra and reference spectra into joint embedding space) — https://github.com/samgoldman97/mist
- **MIST-CF** (Extension of MIST for encoding chemical formulas and ranking formula-adduct candidates; can be combined with fingerprint ranking in multi-modal structure annotation) — https://github.com/samgoldman97/mist-cf

## Examples

```
. quickstart/00_download_models.sh && . quickstart/01_run_models.sh && ls quickstart/model_predictions/retrieval/
```

## Evaluation signals

- Retrieve-rank evaluation: measure if true structure appears in top-k (k=1, 5, 10) retrieved candidates; report accuracy or mean reciprocal rank (MRR).
- Embedding space coherence: verify that spectra from the same molecular structure cluster together and are separated from spectra of different structures by larger distances.
- Similarity score distribution: confirm that true structure matches have higher embedding similarity scores (e.g., cosine > 0.7) than decoy or false-positive candidates.
- Consistency across isomers: for molecules with multiple isomers in the reference database, confirm that the method ranks isomers by structural similarity to the query spectrum, not random ties.
- Database coverage: confirm reference database has been fully encoded and is searchable; spot-check that random reference database entries retrieve their own spectra with top-1 rank (sanity check).

## Limitations

- Contrastive model performance depends heavily on training data diversity and size; performance may degrade on spectra from underrepresented instruments (Orbitrap, quadrupole) or ionization modes.
- Similarity ranking assumes the true structure is present in the reference database; performance baseline is limited by database completeness and curation.
- Joint embedding space alignment quality depends on balanced training data; if training pairs are biased toward certain molecular classes (e.g., natural products), retrieval may fail for synthetic or rare metabolites.
- Nearest-neighbor ranking is sensitive to the choice of distance metric and normalization scheme; no consensus on optimal embedding space geometry for metabolite structures is documented.
- False-positive retrievals can occur if the query spectrum is highly similar (by embedding) to multiple non-isomeric structures; additional orthogonal evidence (e.g., retention time, chemical formula validation) is recommended for confirmation.

## Evidence

- [intro] when trained in a contrastive learning framework, MIST enables embedding and structure annotation by database lookup: "when trained in a contrastive learning framework, MIST enables embedding and structure annotation by database lookup"
- [other] Train MIST end-to-end using contrastive loss to align spectrum embeddings with fingerprint embeddings, with negative sampling from unpaired spectra-structure pairs in each batch: "Train MIST end-to-end using contrastive loss to align spectrum embeddings with fingerprint embeddings, with negative sampling from unpaired spectra-structure pairs"
- [other] For novel spectra, generate embeddings via the trained spectrum encoder and perform nearest-neighbor lookup in the reference database embeddings to retrieve candidate structures with similarity scores: "For novel spectra, generate embeddings via the trained spectrum encoder and perform nearest-neighbor lookup in the reference database embeddings to retrieve candidate structures with similarity scores"
- [other] After training convergence, encode a reference metabolite database (spectra and structures) into joint embedding space: "After training convergence, encode a reference metabolite database (spectra and structures) into joint embedding space"
- [other] Preprocess spectra (normalize intensities, filter noise) and encode chemical structures into fingerprints using a reference fingerprint scheme: "Preprocess spectra (normalize intensities, filter noise) and encode chemical structures into fingerprints using a reference fingerprint scheme"
- [readme] annotate spectra by ranking candidates in a reference smiles list: "annotate spectra by ranking candidates in a reference smiles list"