spectral-similarity-score-computation
Summary
Compute pairwise structural similarity scores between tandem mass spectra by predicting Tanimoto coefficients from spectrum pairs using a deep learning Siamese network, enabling large-scale spectral library searching and compound retrieval. This skill predicts structural similarity without requiring explicit molecular fingerprint computation.
When to use
When you have pairs of MS/MS spectra (in mgf, msp, mzml, mzxml, json, or usi format) and need to retrieve structurally related compounds or rank spectral similarity on a continuous scale (Tanimoto prediction). Use this instead of classical cosine similarity when you need improved precision-recall trade-offs for high structural similarity pairs (Tanimoto > 0.6) or when you want to avoid computing molecular fingerprints explicitly. Appropriate for large-scale comparisons (>100K spectra pairs) where speed and scalability matter.
When NOT to use
- Input spectra have not been cleaned (peaks not filtered by intensity, metadata not standardized); use matchms cleaning pipeline first.
- You only have individual spectra, not pairs; this skill requires spectrum pairs as input.
- You need interpretable molecular structural information (e.g., which functional groups drive similarity); MS2DeepScore predictions are black-box and do not provide atom-level or fragment explanations.
Inputs
- Pair of cleaned MS/MS spectra (spectrum objects with m/z and intensity arrays)
- Trained MS2DeepScore model checkpoint (PyTorch .pt file)
- Spectrum metadata (optional: parent mass, ionization mode, elemental formula)
Outputs
- Predicted Tanimoto structural similarity score (continuous value, 0–1 per pair)
- Uncertainty estimate (interquartile range from Monte-Carlo Dropout ensemble)
- Spectrum embeddings (fixed-dimension vector per spectrum for clustering/visualization)
How to apply
Load the trained MS2DeepScore Siamese network model (available from zenodo). Prepare input spectra by cleaning metadata using matchms, removing peaks with intensities < 0.1% of maximum, limiting to the 1000 highest-intensity peaks, and applying square-root transformation to peak intensities. For each spectrum pair, pass the binned spectrum data (10,000 equally-sized bins from 10 to 1000 m/z) through the base network to obtain embeddings, then compute cosine similarity between embedding pairs to yield Tanimoto score predictions. Optionally apply Monte-Carlo Dropout (sample predictions across 10+ model variations with dropout enabled) to quantify prediction uncertainty via interquartile range; filter predictions with IQR above a user-defined threshold to improve accuracy. Vary the similarity score threshold from 0 to 1.0 to generate precision-recall curves if ground-truth structural similarity labels (RDKit Daylight fingerprint Tanimoto ≥ 0.6) are available for validation.
Related tools
- ms2deepscore (Core library providing the Siamese network model, embedding computation, and prediction API for spectral similarity scoring) — https://github.com/matchms/ms2deepscore
- matchms (Data preparation and spectrum cleaning (metadata standardization, peak filtering, adduct extraction) prior to similarity computation) — https://github.com/matchms/matchms
- RDKit (Molecular fingerprint generation (Daylight fingerprints, 2048 bits) for ground-truth Tanimoto labels during validation and model training)
- scikit-learn (Dimensionality reduction (t-SNE) for visualizing spectra in chemical space after embedding computation)
- PyTorch (Deep learning framework underlying the Siamese network model and Monte-Carlo Dropout uncertainty quantification)
Examples
from ms2deepscore.models import load_model
from ms2deepscore import MS2DeepScore
model = load_model("ms2deepscore_model.pt")
ms2ds = MS2DeepScore(model)
similarity_score = ms2ds.pair_to_distance(spectrum_1, spectrum_2)
Evaluation signals
- Predicted Tanimoto scores fall within the expected range [0, 1] with a distribution that matches the training set structural similarity label distribution.
- On a validation set of 3600+ spectra with known high structural similarity pairs (Tanimoto > 0.6), precision-recall curve of MS2DeepScore predictions lies above classical spectral similarity measures (modified cosine, Spec2Vec) across the full threshold range.
- Root mean squared error (RMSE) between predicted and actual Tanimoto scores on a held-out test set is ≤ 0.15 without uncertainty filtering, and ≤ 0.10 when filtering predictions with IQR below user-defined threshold.
- Monte-Carlo Dropout ensemble (10+ samples per pair) yields stable, low-variance uncertainty estimates; interquartile range correlates inversely with prediction error.
- Spectrum embeddings computed from the base network are suitable for clustering and UMAP visualization, with known structurally similar compounds (same InChIKey) appearing proximal in 2D reduced space.
Limitations
- Model requires >100K spectra for effective training; smaller custom datasets may suffer from poor generalization. Pre-trained model on public libraries (GNPS, MoNA, MassBank, MSnLib) may not transfer well to highly specialized or proprietary mass spectrometry datasets.
- Predictions are trained to approximate Tanimoto on RDKit Daylight fingerprints (2048 bits); structural similarity is limited to molecular features captured by this fingerprint type and does not guarantee chemically meaningful similarity in all domains.
- Root mean squared error is approximately 0.15 without uncertainty restrictions; predictions for borderline structural similarity cases (Tanimoto ≈ 0.5–0.65) may be unreliable. Uncertainty filtering via IQR improves accuracy but at the cost of reduced coverage.
- Model does not use spectrum metadata (parent mass, elemental formula, ionization mode details) in the version described in the primary article; version 2.0+ supports cross-ionization mode predictions but requires different training and model checkpoint.
- Computational cost scales quadratically with the number of spectra (all unique pairs); comparison of >1M spectra requires efficient pairwise computation and GPU acceleration to remain practical.
Evidence
- [intro] MS2DeepScore, a deep learning approach that is trained to predict structural similarities (Tanimoto or Dice scores based on molecular fingerprints) directly from pairs of MS/MS spectra without first: "MS2DeepScore, a deep learning approach that is trained to predict structural similarities (Tanimoto or Dice scores based on molecular fingerprints) directly from pairs of MS/MS spectra"
- [other] MS2DeepScore outperforms both modified Cosine and Spec2Vec across the full precision-recall range for identifying structurally related compounds, achieving notably better precision/recall combinations for retrieving high Tanimoto pairs (Tanimoto > 0.6).: "MS2DeepScore outperforms both modified Cosine and Spec2Vec across the full precision-recall range for identifying structurally related compounds, achieving notably better precision/recall"
- [methods] Spectrum peaks were binned in 10,000 equally-sized bins ranging from 10 to 1000 m/z: "Spectrum peaks were binned in 10,000 equally-sized bins ranging from 10 to 1000 m/z"
- [methods] Unless noted otherwise, we used Tanimoto scores on RDKit Daylight fingerprints (2048 bits) to compute structural similarities: "Tanimoto scores on RDKit Daylight fingerprints (2048 bits) to compute structural similarities"
- [methods] Peak intensities were square root transformed to avoid a too strong focus on the highest intensity peaks only: "Peak intensities were square root transformed to avoid a too strong focus on the highest intensity peaks only"
- [methods] To estimate the uncertainty of a prediction we used Monte-Carlo Dropout ensembles. At inference time, dropout was applied to all but the first layer of the base network: "To estimate the uncertainty of a prediction we used Monte-Carlo Dropout ensembles. At inference time, dropout was applied to all but the first layer"
- [intro] achieve a root mean squared error for predicted Tanimoto scores of about 0.15 when run without uncertainty restrictions, and down to 0.1 with stronger restrictions on model uncertainty: "achieve a root mean squared error for predicted Tanimoto scores of about 0.15 when run without uncertainty restrictions, and down to 0.1 with stronger restrictions on model uncertainty"
- [readme] To compute the similarities between spectra of your choice you can run the code below. There is a small example dataset available in the folder "./tests/resources/pesticides_processed.mgf". Alternatively you can of course use your own spectra, most common formats are supported, e.g. msp, mzml, mgf, mzxml, json, usi.: "most common formats are supported, e.g. msp, mzml, mgf, mzxml, json, usi"
1---2name: spectral-similarity-score-computation3description: Use when when you have pairs of MS/MS spectra (in mgf, msp, mzml, mzxml, json, or usi format) and need to retrieve structurally related compounds or rank spectral similarity on a continuous scale (Tanimoto prediction).4license: CC-BY-4.05---67# spectral-similarity-score-computation89## Summary1011Compute pairwise structural similarity scores between tandem mass spectra by predicting Tanimoto coefficients from spectrum pairs using a deep learning Siamese network, enabling large-scale spectral library searching and compound retrieval. This skill predicts structural similarity without requiring explicit molecular fingerprint computation.1213## When to use1415When you have pairs of MS/MS spectra (in mgf, msp, mzml, mzxml, json, or usi format) and need to retrieve structurally related compounds or rank spectral similarity on a continuous scale (Tanimoto prediction). Use this instead of classical cosine similarity when you need improved precision-recall trade-offs for high structural similarity pairs (Tanimoto > 0.6) or when you want to avoid computing molecular fingerprints explicitly. Appropriate for large-scale comparisons (>100K spectra pairs) where speed and scalability matter.1617## When NOT to use1819- Input spectra have not been cleaned (peaks not filtered by intensity, metadata not standardized); use matchms cleaning pipeline first.20- You only have individual spectra, not pairs; this skill requires spectrum pairs as input.21- You need interpretable molecular structural information (e.g., which functional groups drive similarity); MS2DeepScore predictions are black-box and do not provide atom-level or fragment explanations.2223## Inputs2425- Pair of cleaned MS/MS spectra (spectrum objects with m/z and intensity arrays)26- Trained MS2DeepScore model checkpoint (PyTorch .pt file)27- Spectrum metadata (optional: parent mass, ionization mode, elemental formula)2829## Outputs3031- Predicted Tanimoto structural similarity score (continuous value, 0–1 per pair)32- Uncertainty estimate (interquartile range from Monte-Carlo Dropout ensemble)33- Spectrum embeddings (fixed-dimension vector per spectrum for clustering/visualization)3435## How to apply3637Load the trained MS2DeepScore Siamese network model (available from zenodo). Prepare input spectra by cleaning metadata using matchms, removing peaks with intensities < 0.1% of maximum, limiting to the 1000 highest-intensity peaks, and applying square-root transformation to peak intensities. For each spectrum pair, pass the binned spectrum data (10,000 equally-sized bins from 10 to 1000 m/z) through the base network to obtain embeddings, then compute cosine similarity between embedding pairs to yield Tanimoto score predictions. Optionally apply Monte-Carlo Dropout (sample predictions across 10+ model variations with dropout enabled) to quantify prediction uncertainty via interquartile range; filter predictions with IQR above a user-defined threshold to improve accuracy. Vary the similarity score threshold from 0 to 1.0 to generate precision-recall curves if ground-truth structural similarity labels (RDKit Daylight fingerprint Tanimoto ≥ 0.6) are available for validation.3839## Related tools4041- **ms2deepscore** (Core library providing the Siamese network model, embedding computation, and prediction API for spectral similarity scoring) — https://github.com/matchms/ms2deepscore42- **matchms** (Data preparation and spectrum cleaning (metadata standardization, peak filtering, adduct extraction) prior to similarity computation) — https://github.com/matchms/matchms43- **RDKit** (Molecular fingerprint generation (Daylight fingerprints, 2048 bits) for ground-truth Tanimoto labels during validation and model training)44- **scikit-learn** (Dimensionality reduction (t-SNE) for visualizing spectra in chemical space after embedding computation)45- **PyTorch** (Deep learning framework underlying the Siamese network model and Monte-Carlo Dropout uncertainty quantification)4647## Examples4849```50from ms2deepscore.models import load_model51from ms2deepscore import MS2DeepScore52model = load_model("ms2deepscore_model.pt")53ms2ds = MS2DeepScore(model)54similarity_score = ms2ds.pair_to_distance(spectrum_1, spectrum_2)55```5657## Evaluation signals5859- Predicted Tanimoto scores fall within the expected range [0, 1] with a distribution that matches the training set structural similarity label distribution.60- On a validation set of 3600+ spectra with known high structural similarity pairs (Tanimoto > 0.6), precision-recall curve of MS2DeepScore predictions lies above classical spectral similarity measures (modified cosine, Spec2Vec) across the full threshold range.61- Root mean squared error (RMSE) between predicted and actual Tanimoto scores on a held-out test set is ≤ 0.15 without uncertainty filtering, and ≤ 0.10 when filtering predictions with IQR below user-defined threshold.62- Monte-Carlo Dropout ensemble (10+ samples per pair) yields stable, low-variance uncertainty estimates; interquartile range correlates inversely with prediction error.63- Spectrum embeddings computed from the base network are suitable for clustering and UMAP visualization, with known structurally similar compounds (same InChIKey) appearing proximal in 2D reduced space.6465## Limitations6667- Model requires >100K spectra for effective training; smaller custom datasets may suffer from poor generalization. Pre-trained model on public libraries (GNPS, MoNA, MassBank, MSnLib) may not transfer well to highly specialized or proprietary mass spectrometry datasets.68- Predictions are trained to approximate Tanimoto on RDKit Daylight fingerprints (2048 bits); structural similarity is limited to molecular features captured by this fingerprint type and does not guarantee chemically meaningful similarity in all domains.69- Root mean squared error is approximately 0.15 without uncertainty restrictions; predictions for borderline structural similarity cases (Tanimoto ≈ 0.5–0.65) may be unreliable. Uncertainty filtering via IQR improves accuracy but at the cost of reduced coverage.70- Model does not use spectrum metadata (parent mass, elemental formula, ionization mode details) in the version described in the primary article; version 2.0+ supports cross-ionization mode predictions but requires different training and model checkpoint.71- Computational cost scales quadratically with the number of spectra (all unique pairs); comparison of >1M spectra requires efficient pairwise computation and GPU acceleration to remain practical.7273## Evidence7475- [intro] MS2DeepScore, a deep learning approach that is trained to predict structural similarities (Tanimoto or Dice scores based on molecular fingerprints) directly from pairs of MS/MS spectra without first: "MS2DeepScore, a deep learning approach that is trained to predict structural similarities (Tanimoto or Dice scores based on molecular fingerprints) directly from pairs of MS/MS spectra"76- [other] MS2DeepScore outperforms both modified Cosine and Spec2Vec across the full precision-recall range for identifying structurally related compounds, achieving notably better precision/recall combinations for retrieving high Tanimoto pairs (Tanimoto > 0.6).: "MS2DeepScore outperforms both modified Cosine and Spec2Vec across the full precision-recall range for identifying structurally related compounds, achieving notably better precision/recall"77- [methods] Spectrum peaks were binned in 10,000 equally-sized bins ranging from 10 to 1000 m/z: "Spectrum peaks were binned in 10,000 equally-sized bins ranging from 10 to 1000 m/z"78- [methods] Unless noted otherwise, we used Tanimoto scores on RDKit Daylight fingerprints (2048 bits) to compute structural similarities: "Tanimoto scores on RDKit Daylight fingerprints (2048 bits) to compute structural similarities"79- [methods] Peak intensities were square root transformed to avoid a too strong focus on the highest intensity peaks only: "Peak intensities were square root transformed to avoid a too strong focus on the highest intensity peaks only"80- [methods] To estimate the uncertainty of a prediction we used Monte-Carlo Dropout ensembles. At inference time, dropout was applied to all but the first layer of the base network: "To estimate the uncertainty of a prediction we used Monte-Carlo Dropout ensembles. At inference time, dropout was applied to all but the first layer"81- [intro] achieve a root mean squared error for predicted Tanimoto scores of about 0.15 when run without uncertainty restrictions, and down to 0.1 with stronger restrictions on model uncertainty: "achieve a root mean squared error for predicted Tanimoto scores of about 0.15 when run without uncertainty restrictions, and down to 0.1 with stronger restrictions on model uncertainty"82- [readme] To compute the similarities between spectra of your choice you can run the code below. There is a small example dataset available in the folder "./tests/resources/pesticides_processed.mgf". Alternatively you can of course use your own spectra, most common formats are supported, e.g. msp, mzml, mgf, mzxml, json, usi.: "most common formats are supported, e.g. msp, mzml, mgf, mzxml, json, usi"
HolobiomicsLab 