---
name: spectral-retrieval-ranking-task
description: Use when when you have pre-computed dense embeddings for query spectra (unknown compounds) and reference spectra (spectral library), and you need to rank library entries by similarity to each query for compound identification or structural similarity retrieval.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3767
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0121
  tools:
  - Python
  - PyTorch
  - CUDA
  - numba
  - SpecEmbedding
  - ModelTester
  - Tokenizer
  techniques:
  - CE-MS
derived_from:
- doi: 10.1021/acs.analchem.5c02655
  title: SpecEmbedding
evidence_spans:
- Python：3.12
- PyTorch：2.6.0 + CUDA 12.4
- 该装饰器来自 numba
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_specembedding_cq
    doi: 10.1021/acs.analchem.5c02655
    title: SpecEmbedding
  dedup_kept_from: coll_specembedding_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1021/acs.analchem.5c02655
  all_source_dois:
  - 10.1021/acs.analchem.5c02655
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# spectral-retrieval-ranking-task

## Summary

Compute a cosine similarity matrix between query and reference MS/MS spectral embeddings to rank candidate compounds by retrieval score. This skill bridges embedding generation and compound identification by quantifying spectral similarity in the learned embedding space.

## When to use

When you have pre-computed dense embeddings for query spectra (unknown compounds) and reference spectra (spectral library), and you need to rank library entries by similarity to each query for compound identification or structural similarity retrieval. Use this when embeddings are already normalized and you want to retrieve top-k candidates without additional feature engineering.

## When NOT to use

- Query or reference embeddings are not normalized or were generated by a different model architecture (e.g., MSBERT) — cosine similarity assumes unit-normalized vectors from the same learned space.
- Input spectra contain malformed or invalid SMILES strings — these must be removed before embedding generation; the similarity matrix will reflect garbage-in-garbage-out.
- You need to score spectra that have not been embedded using SpecEmbedding's sinusoidal positional encoding and supervised contrastive learning framework — similarity scores are specific to the learned metric.

## Inputs

- query_spectra: list of MS/MS spectra objects loaded from MSP format files, each containing m/z–intensity peaks and SMILES strings
- reference_spectra: list of MS/MS spectra objects from spectral library (GNPS, MoNA, MTBLS1572, MassBank, or MassSpecGym), preprocessed to remove invalid SMILES and malformed entries
- pre_trained_model: SpecEmbedding model checkpoint (load_tanimoto_supcon_aug_model)
- tokenizer: initialized Tokenizer with vocabulary size 100 and normalization enabled

## Outputs

- cosine_similarity_matrix: NumPy array of shape (num_queries, num_reference) containing cosine similarity scores ∈ [0, 1]
- top_k_indices: array of shape (num_queries, k) containing indices of top-k most similar reference spectra for each query
- ranked_candidates: reference spectrum objects and metadata (SMILES, compound names) sorted by similarity score

## How to apply

Load pre-trained SpecEmbedding model (Tanimoto SupCon Aug variant) and initialize a ModelTester with the model and computational device (CPU or GPU). Generate normalized embeddings for query spectra using the embedding function with batch size 512 and normalized=True flag. Generate normalized embeddings for reference spectra using identical parameters. Compute the cosine similarity matrix between query and reference embeddings using the cosine_similarity function (note: on Windows, comment out @njit decorators from numba to avoid numerical errors). Retrieve top-k candidate indices using top_k_indices and map them back to reference spectra metadata. The batch size of 512 balances memory efficiency with throughput; use smaller batches (e.g., 256) on memory-constrained devices.

## Related tools

- **SpecEmbedding** (Pre-trained deep learning model that generates query and reference embeddings using sinusoidal positional encoding and supervised contrastive learning; used to initialize ModelTester and compute embeddings before similarity matrix construction) — https://github.com/sword-nan/SpecEmbedding
- **ModelTester** (Wrapper class that orchestrates embedding generation for batches of spectra on specified device (CPU/GPU); used to generate normalized dense embeddings with progress tracking) — https://github.com/sword-nan/SpecEmbedding
- **Tokenizer** (Converts MS/MS spectral peaks to token sequences for model input; vocabulary size 100, normalization enabled to ensure consistent input encoding) — https://github.com/sword-nan/SpecEmbedding
- **PyTorch** (Deep learning framework used to load pre-trained model and perform batch matrix operations on GPU (CUDA 12.4) or CPU)
- **numba** (Just-in-time compilation library used by @njit decorators to accelerate cosine_similarity computation; Windows users must comment out @njit to avoid numerical errors)

## Examples

```
from SpecEmbedding.utils.model import embedding, cosine_similarity, load_tanimoto_supcon_aug_model, top_k_indices
from SpecEmbedding.utils.clean import read_raw_spectra
from SpecEmbedding.trainer.trainer import ModelTester
from SpecEmbedding.data.tokenizer import Tokenizer

q = read_raw_spectra('./q.msp')
r = read_raw_spectra('./r.msp')
tokenizer = Tokenizer(100, True)
model = load_tanimoto_supcon_aug_model('cpu')
tester = ModelTester(model, 'cpu', True)
q_emb, _ = embedding(tester, tokenizer, 512, q, True)
r_emb, _ = embedding(tester, tokenizer, 512, r, True)
similarity_matrix = cosine_similarity(q_emb, r_emb)
indices = top_k_indices(similarity_matrix, 1)
```

## Evaluation signals

- Cosine similarity matrix shape matches (num_queries, num_reference) and all values fall in [0, 1] range with no NaNs or infinities.
- Top-k indices are valid row and column indices with no duplicates within each query's ranking; indices correspond to reference spectrum objects that can be retrieved from the library.
- Manual inspection: for known query–reference pairs (e.g., identical or near-identical spectra), verify that similarity scores are close to 1.0 and retrieval rank is 1.
- Cross-validation: averaged top-1, top-5, top-10 hit rates across 10-fold query/reference splits should match published SpecEmbedding benchmarks (reported on figshare).
- Robustness test: embeddings generated with batch size 256 vs 512 should produce identical (or numerically near-identical) similarity matrices, confirming batch invariance.

## Limitations

- Cosine similarity is sensitive to embedding quality; poor embeddings (e.g., from a weakly trained model or spectra outside the training domain) will produce low discriminative scores and poor retrieval ranking.
- On Windows systems, @njit decorators in numba cause numerical errors during cosine_similarity computation; users must manually comment out these decorators in the source code.
- Generalization is limited to spectral libraries similar to training data (GNPS, MoNA, MTBLS1572); performance degrades on curated high-quality libraries (MassBank, MassSpecGym) with different spectral distributions or collision energies.
- Malformed or invalid SMILES strings in input spectra are not automatically filtered; contaminated libraries will reduce ranking precision. Data must be cleaned before embedding.
- Similarity scores assume normalized embeddings; if embeddings are scaled or unnormalized, cosine similarity values become unreliable.

## Evidence

- [other] SpecEmbedding generates embeddings for query and reference spectra using a deep learning model with sinusoidal positional encoding and supervised contrastive learning, then computes a cosine similarity matrix between them for retrieval scoring.: "SpecEmbedding generates embeddings for query and reference spectra using a deep learning model with sinusoidal positional encoding and supervised contrastive learning, then computes a cosine"
- [other] Generate embeddings for query and reference spectra using the embedding function with batch size 512 and normalized flag True. Compute the cosine similarity matrix between query and reference embeddings using cosine_similarity function.: "Generate dense embeddings for query spectra using the embedding function with batch size 512 and normalized flag True...Compute the cosine similarity matrix between query and reference embeddings"
- [readme] When running on Windows, you may encounter numerical errors during cosine similarity computation. This is caused by @njit decorators from the numba library. You can fix it by commenting out all @njit decorators in the code.: "When running on Windows, you may encounter numerical errors during cosine similarity computation. This is caused by @njit decorators from the numba library"
- [intro] To further improve data quality, we removed entries with malformed or invalid SMILES strings.: "To further improve data quality, we removed entries with malformed or invalid SMILES strings"
- [readme] Generate embeddings for query and reference spectra...Compute the cosine similarity matrix...Retrieve the indices of the top-1 candidates: "Generate embeddings for query and reference spectra...Retrieve the indices of the top-1 candidates"