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"
1---2name: structure-annotation-via-similarity-ranking3description: 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.4license: CC-BY-4.05---67# structure-annotation-via-similarity-ranking89## Summary1011Annotate 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.1213## When to use1415Apply 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.1617## When NOT to use1819- Input spectra are from instruments or ionization modes not represented in the training data; model generalization may be poor.20- Reference database is very small (<100 unique structures) or lacks diversity similar to the query spectrum's molecular class.21- Query spectrum has low signal-to-noise ratio or sparse fragmentation pattern; embeddings may be unreliable.22- No pre-trained or trainable contrastive model is available; standard database search methods (e.g., spectral cosine matching) are more appropriate.2324## Inputs2526- tandem mass spectrometry spectrum (MGF format or .ms file with m/z and intensity peak pairs)27- reference metabolite database with paired spectra and molecular structures (SMILES or structural fingerprints)28- pre-trained spectrum encoder model (MIST or equivalent transformer architecture)29- pre-trained chemical structure encoder model (fingerprint or formula transformer)3031## Outputs3233- ranked list of candidate structures with embedding similarity scores34- spectrum embedding vector in joint chemical space35- structure annotations with confidence metrics based on nearest-neighbor distance3637## How to apply3839Load 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.4041## Related tools4243- **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/mist44- **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-cf4546## Examples4748```49. quickstart/00_download_models.sh && . quickstart/01_run_models.sh && ls quickstart/model_predictions/retrieval/50```5152## Evaluation signals5354- Retrieve-rank evaluation: measure if true structure appears in top-k (k=1, 5, 10) retrieved candidates; report accuracy or mean reciprocal rank (MRR).55- Embedding space coherence: verify that spectra from the same molecular structure cluster together and are separated from spectra of different structures by larger distances.56- Similarity score distribution: confirm that true structure matches have higher embedding similarity scores (e.g., cosine > 0.7) than decoy or false-positive candidates.57- 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.58- 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).5960## Limitations6162- Contrastive model performance depends heavily on training data diversity and size; performance may degrade on spectra from underrepresented instruments (Orbitrap, quadrupole) or ionization modes.63- Similarity ranking assumes the true structure is present in the reference database; performance baseline is limited by database completeness and curation.64- 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.65- 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.66- 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.6768## Evidence6970- [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"71- [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"72- [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"73- [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"74- [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"75- [readme] annotate spectra by ranking candidates in a reference smiles list: "annotate spectra by ranking candidates in a reference smiles list"
