Spectral structural similarity computation

Spectral-Structural Similarity Computation

Summary

Compute pairwise structural similarity between tandem mass spectra by applying cosine similarity on learned embedding vectors. This skill validates whether embedding spaces capture chemical rationality by quantifying structural correspondence between spectra.

When to use

When you have pre-trained embedding vectors (e.g., from MSBERT) for a collection of mass spectra and need to establish which spectra are chemically similar for validation, clustering, or library matching. Use this skill after dimensionality reduction if you want to validate that reduced embeddings preserve chemical structure relationships, or on full-dimensional embeddings for exhaustive pairwise comparisons.

When NOT to use

• Raw, unaggregated mass spectra (m/z, intensity pairs) without pre-computed embeddings; use embedding generation first.
• Similarity computation on spectra from instruments not represented in the MSBERT training data (GNPS Orbitrap); retrain or validate applicability on instrument-specific test sets.
• When comparing spectra across vastly different chemical domains (e.g., metabolomics vs. proteomics fragments) without domain-specific embedding retraining or validation.

Inputs

• Pre-trained embedding vectors (numpy array or PyTorch tensor, shape: [n_spectra, embedding_dim])
• MSBERT model checkpoint (.pkl file)
• Demo or test mass spectra in .msp format
• Reference chemical structure labels or GNPS dataset annotations (for validation)

Outputs

• Pairwise similarity matrix (dense or sparse, shape: [n_spectra, n_spectra], values in [0, 1])
• Library matching rank scores (top-1, top-5, top-10 accuracy or matched candidate lists)
• Validated cluster coherence metrics (e.g., silhouette score, Davies-Bouldin index if clustering applied)

How to apply

Load pre-trained embedding vectors from a trained model checkpoint (e.g., MSBERT.pkl). Compute cosine similarity between all pairs of embedding vectors to produce a similarity matrix. The cosine metric is chosen because embeddings are normalized vector representations where angular distance reflects chemical structure divergence. Validate the resulting similarity scores by cross-referencing clusters or pairs against known chemical classifications in the reference dataset (e.g., GNPS structural families). Score ranges near 1.0 indicate high structural similarity; scores near 0 indicate structural dissimilarity. Use the similarity matrix as input to downstream clustering (k-means, hierarchical) or for library matching rank ordering (e.g., top-1, top-5, top-10 matches).

Related tools

• MSBERT (Provides pre-trained embedding model and similarity computation utilities (ModelEmbed, MSBERTSimilarity functions)) — https://github.com/zhanghailiangcsu/MSBERT
• PyTorch (Loads pre-trained model checkpoints and executes cosine similarity computations on GPU/CPU) — https://pytorch.org/
• matchms (Integrates MSBERT similarity calculation into spectral matching workflows for library searching) — https://github.com/zhanghailiangcsu/MSBERT/tree/main/matchms_workflow
• scikit-learn (Optional: clustering (k-means, hierarchical) and cohesion validation on similarity matrices)

Examples

from model.utils import ModelEmbed, ProcessMSP, MSBERTSimilarity
import torch
from model.MSBERTModel import MSBERT

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

• Similarity matrix is symmetric and diagonal equals 1.0 (self-similarity)
• Top-1, top-5, top-10 library matching accuracy on Orbitrap test dataset matches or exceeds reported scores (0.7871, 0.8950, 0.9080 respectively)
• Cosine similarity scores between spectra with identical or near-identical chemical structure (same compound, different instrument runs) cluster near 1.0; unrelated compounds cluster near 0
• Spectral clustering (k-means, hierarchical) on similarity matrix produces coherent clusters matching known chemical families or compound classes in GNPS reference annotations
• Pairwise similarity substantially outperforms baseline methods (Spec2Vec, raw cosine similarity on unreduced spectra) in recall/precision metrics for known compound pairs

Limitations

• Similarity computation assumes embeddings are derived from MSBERT or a compatible pre-trained model; embeddings from other methods or models may not preserve chemical rationality.
• MSBERT was trained and validated on GNPS Orbitrap data; transferability to other mass spectrometry instruments or spectral formats (e.g., MALDI, APCI) is not established.
• Cosine similarity on embeddings depends critically on the quality and dimensionality of the learned representation; poor embedding quality or dimension mismatch will yield uninformative or misleading similarity scores.
• No changelog is maintained for MSBERT model versions or training hyperparameters, limiting reproducibility and interpretation of changes across releases.

Evidence

• [intro] Compute pairwise structural similarity between mass spectra using cosine similarity on the reduced embeddings.: "Compute pairwise structural similarity between mass spectra using cosine similarity on the reduced embeddings."
• [intro] 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.: "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."
• [readme] The rationality of embedding was demonstrated by reducing the dimensionality of the embedding vectors, calculating structural similarity, and spectra clustering.: "The rationality of embedding was demonstrated by reducing the dimensionality of the embedding vectors, calculating structural similarity, and spectra clustering."
• [readme] Calculate the similarity after MSBERT embedding: cos = MSBERTSimilarity(demo_arr,demo_arr): "Calculate the similarity after MSBERT embedding: cos = MSBERTSimilarity(demo_arr,demo_arr)"
• [readme] MSBERT was trained and tested on GNPS dataset.: "MSBERT was trained and tested on GNPS dataset."