# Mass Spectrometry Library Ranking

> Use when you have a set of unidentified tandem mass spectra (queries) and need to identify them by matching against a curated reference library (e.g., GNPS Orbitrap dataset).

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

---


# mass-spectrometry-library-ranking

## Summary

Rank tandem mass spectra (MS/MS) against a reference spectral library using learned embeddings to retrieve top-k spectral matches. This skill evaluates library matching accuracy by computing cosine-similarity scores between query and reference spectrum embeddings, returning ranked hit lists and top-k accuracy metrics.

## When to use

You have a set of unidentified tandem mass spectra (queries) and need to identify them by matching against a curated reference library (e.g., GNPS Orbitrap dataset). Use this skill when you want to move beyond raw cosine-similarity or Spec2Vec baselines and assess whether a learned embedding model (such as MSBERT) improves top-1, top-5, and top-10 hit rates on holdout test spectra.

## When NOT to use

- Reference library is unlabeled or does not contain ground-truth compound identities — rank metrics cannot be computed.
- Query spectra are from a different instrument type (e.g., Orbitrap-trained model applied to QTOF spectra without retraining) — embedding space may not generalize, degrading accuracy.
- You only need to retrieve spectral neighbors without ranking quality metrics — use raw cosine-similarity or embedding lookup instead.

## Inputs

- Test MS/MS spectra (MSP file format with m/z and intensity pairs)
- Reference spectral library (MSP file format)
- Pre-trained MSBERT model checkpoint (PyTorch .pkl file)
- Query-to-reference ground-truth labels (compound identifiers)

## Outputs

- Top-k ranked matches per query spectrum (list of reference spectrum IDs, scores)
- Top-1, top-5, top-10 hit-rate accuracy metrics (float, range [0, 1])
- P-values from statistical significance tests
- Summary comparison table (method × accuracy metric)

## How to apply

Load a pre-trained MSBERT encoder and generate fixed-size embeddings (e.g., 512 dimensions) for all test query spectra and reference library spectra from MSP or pickle format. Compute pairwise cosine-similarity scores between each query embedding and all reference embeddings. Rank reference spectra by descending similarity and extract top-k (k=1, 5, 10) matches for each query. Calculate hit-rate accuracy as the fraction of queries whose true label appears in the top-k ranked list. Report top-1, top-5, and top-10 accuracy scores alongside p-values from paired statistical tests (e.g., paired t-test or chi-squared) to confirm improvement over baseline methods (cosine-similarity on raw spectra or Spec2Vec embeddings).

## Related tools

- **MSBERT** (Pre-trained transformer encoder for generating chemically rational MS/MS embeddings) — https://github.com/zhanghailiangcsu/MSBERT
- **PyTorch** (Deep learning framework for loading and running the MSBERT encoder) — https://pytorch.org/
- **matchms** (Library for MS/MS spectrum processing, filtering, and similarity workflow integration) — https://github.com/zhanghailiangcsu/MSBERT/tree/main/matchms_workflow
- **Spec2Vec** (Baseline embedding method for comparative evaluation) — https://github.com/zhanghailiangcsu/MSBERT/tree/main/Spec2VecModel

## Examples

```
from model.MSBERTModel import MSBERT
from model.utils import ModelEmbed, ProcessMSP, MSBERTSimilarity
import torch
model = MSBERT(100002, 512, 6, 16, 0, 100, 3)
model.load_state_dict(torch.load('model/MSBERT.pkl'))
demo_data, demo_smiles = ProcessMSP('example/demo.msp')
demo_arr = ModelEmbed(model, demo_data, 16)
cos = MSBERTSimilarity(demo_arr, demo_arr)
```

## Evaluation signals

- Top-1, top-5, top-10 accuracy scores fall within expected ranges (0.0–1.0) and improve monotonically (top-1 ≤ top-5 ≤ top-10).
- P-value from paired significance test is <0.05, confirming MSBERT outperforms cosine-similarity and Spec2Vec baselines.
- Embedding vectors have expected shape (query_count, 512) and are normalized or comparable via cosine metric.
- Ground-truth label appears in retrieved top-k list for ≥70% of test queries (baseline expectation for Orbitrap dataset).
- Ranking is reproducible: same query–reference pair yields identical cosine-similarity score and rank position across runs.

## Limitations

- Model performance is dataset- and instrument-specific; MSBERT trained on GNPS Orbitrap may not generalize to other MS/MS platforms or fragmentation conditions without retraining.
- Accuracy depends on reference library completeness and quality; missing or mislabeled reference spectra degrade ranking correctness.
- Computational cost scales with library size (O(n) embeddings, O(n²) pairwise similarities for n reference spectra); large libraries (>100k spectra) may require GPU acceleration.
- Ground-truth labels must be available to compute hit-rate metrics; method is unsuitable for fully unsupervised or open-search scenarios.

## Evidence

- [intro] MSBERT achieved top-1, top-5, and top-10 library matching scores of 0.7871, 0.8950, and 0.9080 on Orbitrap test dataset: "MSBERT had a stronger ability in library matching, with top 1, top5, and top 10 were 0.7871, 0.8950, and 0.9080 on Orbitrap test dataset."
- [intro] Results are significantly better than Spec2Vec and cosine similarity: "The results are significantly better than Spec2Vec and cosine similarity."
- [other] Generate embeddings for all test spectra and reference library spectra using the MSBERT encoder, then compute cosine-similarity matching scores: "Generate embeddings for all test spectra and reference library spectra using the MSBERT encoder. Compute cosine-similarity matching scores between test and library embeddings, retrieving top-1,"
- [other] Calculate rank-based accuracy metrics (top-1, top-5, top-10 hit rates) and perform statistical significance testing: "Calculate rank-based accuracy metrics (top-1, top-5, top-10 hit rates) for all three methods. Perform statistical significance testing (e.g., paired t-test or chi-squared) to confirm MSBERT"
- [readme] Load demo file in MSP format and compute MSBERT embeddings and similarity within matchms workflow: "# Load demo file
demofile = 'matchms_workflow/demo_msms.msp'
spectra = list(load_from_msp(demofile))
# Calculate MSBERT similarity scores between all spectra in matchms workflow
MSBERT_Similarity ="