Spectral similarity matrix computation

spectral-similarity-matrix-computation

Summary

Compute pairwise similarity scores across preprocessed mass spectra using matchms to generate a structured scores matrix. This skill enables large-scale spectral similarity comparisons essential for identifying spectral relationships and compound matches in untargeted metabolomics workflows.

When to use

Apply this skill after preprocessing and filtering mass spectra (peak filtering, metadata cleaning) when you need to compare all spectrum pairs within a dataset or between a query set and a reference library to identify similar or related spectra. Use it when your input is a collection of cleaned spectra in mzML, mzXML, msp, MGF, or JSON format and your goal is to generate a pairwise similarity matrix for downstream filtering, clustering, or library matching.

When NOT to use

• Input spectra have not been preprocessed or peak-filtered—apply preprocessing and cleaning steps first.
• Your goal is to compare individual spectra against a single query rather than generate comprehensive pairwise comparisons; use targeted search instead.
• You require real-time or streaming similarity computation across continuously arriving spectra; this skill assumes a static, complete input dataset.

Inputs

• preprocessed mass spectra in mzML, mzXML, msp, MGF, or JSON format
• peak-filtered spectra or reference spectral library
• spectrum metadata (compound names, retention times, molecular weights)

Outputs

• pairwise similarity scores matrix (CSV or pickle format)
• structured matrix with spectrum identifiers as row and column labels
• sparse scores array for large-scale comparisons (optional)

How to apply

Load preprocessed mass spectra from your input file using matchms's supported file parsers. Select an appropriate pairwise similarity measure—cosine-based scoring for straightforward spectral alignment, molecular fingerprint-based comparisons for structure-informed similarity, or metadata-based assessments for compound property matching. Apply the chosen measure across all spectrum pairs to compute similarity scores, constructing a scores matrix with spectrum identifiers as row and column labels. Store the resulting scores matrix in a structured format (CSV or pickle) with clear row/column indexing to enable downstream analysis. The choice of similarity metric should reflect your research question: use Cosine scores for peak-based spectral matching, fingerprint-based measures when structural information is available, or sparse storage formats when comparing hundreds of thousands of spectra to reduce memory overhead.

Related tools

• matchms (core library for loading preprocessed spectra, applying pairwise similarity measures (Cosine, fingerprint-based, metadata-based), and constructing scores matrices) — https://github.com/matchms/matchms
• Python (execution environment for matchms workflows and matrix I/O operations)
• Spec2Vec (optional extensible spectrum similarity measure tailored for matchms workflows) — https://github.com/iomega/spec2vec
• MS2DeepScore (optional deep learning-based spectrum similarity measure for matchms) — https://github.com/matchms/ms2deepscore

Examples

from matchms import Spectrum, calculate_scores
from matchms.similarity import CosineGreedy
import pickle

spectra = [Spectrum(...), Spectrum(...), ...]  # preprocessed spectra
similarity_measure = CosineGreedy()
scores = calculate_scores(spectra, spectra, similarity_measure)
with open('similarity_matrix.pickle', 'wb') as f:
    pickle.dump(scores, f)

Evaluation signals

• Scores matrix dimensions match expected spectrum count (n × n for all-vs-all comparison).
• Row and column identifiers are correctly mapped to spectrum identifiers with no missing or duplicate entries.
• Similarity scores fall within expected range (0–1 for normalized measures; check for NaN or infinite values).
• Diagonal values equal 1.0 (perfect self-similarity) for cosine-based metrics; off-diagonal values are symmetric.
• Output file parses without errors in downstream analysis tools; spot-check known high-similarity spectrum pairs to confirm expected ranking.

Limitations

• Similarity metric selection significantly influences results—cosine-based scores reflect peak overlap while fingerprint-based measures incorporate structural information; choose metric aligned with your research question.
• Memory usage scales quadratically with spectrum count (n²); for hundreds of thousands of spectra, sparse matrix formats are necessary to avoid memory exhaustion.
• Metadata-based assessments depend on data quality and completeness; missing or incorrect metadata can degrade comparison reliability.
• Preprocessing quality directly impacts scores—poor peak filtering or metadata cleaning upstream will propagate into the similarity matrix; validate preprocessing before computing scores.

Evidence

• [other] matchms applies various pairwise similarity measures for comparing spectra, including common Cosine-related scores among other approaches such as molecular fingerprint-based comparisons and metadata-related assessments: "Matchms applies various pairwise similarity measures for comparing spectra, including common Cosine-related scores among other approaches such as molecular fingerprint-based comparisons and"
• [readme] matchms enables large-scale spectral similarity comparisons: "enabling large-scale spectral similarity comparisons"
• [readme] matchms supports multiple spectral data formats: "The software supports a range of popular spectral data formats, including mzML, mzXML, msp, metabolomics-USI, MGF, and JSON"
• [readme] sparse matrix formats enable comparison of large spectrum sets: "supports storing results in sparse data formats, enabling the comparison of several hundred thousands of spectra"
• [readme] matchms facilitates reproducible workflows from raw to processed spectra: "It facilitates the implementation of straightforward, reproducible workflows, transforming raw data from common mass spectra file formats into pre- and post-processed spectral data"