# Cosine Similarity Scoring Computation

> Use when when you have imported and filtered mass spectrometry spectral data (from mzML, mzXML, msp, MGF, or JSON formats) and need to identify similar or related spectra within a dataset or against a reference library.

- Skill: `holobiomicslab/cosine-similarity-scoring-computation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/cosine-similarity-scoring-computation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/cosine-similarity-scoring-computation/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/cosine-similarity-scoring-computation

---


# cosine-similarity-scoring-computation

## Summary

Compute pairwise Cosine-related similarity scores between mass spectrometry spectra to quantify spectral resemblance for large-scale spectral comparisons. This skill applies matchms' native Cosine similarity measures to transform spectrum pairs into numerical similarity matrices suitable for library searching, compound identification, and spectral clustering.

## When to use

When you have imported and filtered mass spectrometry spectral data (from mzML, mzXML, msp, MGF, or JSON formats) and need to identify similar or related spectra within a dataset or against a reference library. Use this skill when conducting many-to-many spectral comparisons, particularly when initial rapid pre-selection of candidate matches is required before applying more computationally expensive similarity measures.

## When NOT to use

- Input spectra have not been peak-filtered or cleaned; basic peak filtering must precede similarity computation to ensure accuracy.
- You need metadata-aware or molecular fingerprint-based comparisons; use alternative matchms similarity measures (e.g., metadata assessments or Spec2Vec) instead.
- The similarity metric must incorporate spectral intensity distributions beyond m/z matching; Cosine-related scores depend on aligned peak intensities but may not capture all spectral properties equally.

## Inputs

- Preprocessed mass spectrometry spectral data (Spectrum objects or collections)
- Spectral data in mzML, mzXML, msp, MGF, or JSON format
- Peak-filtered spectral datasets with m/z and intensity values

## Outputs

- Pairwise cosine similarity score matrix (sparse or dense)
- Structured similarity scores in numeric or sparse array format
- Indexed spectrum pair comparisons with computed cosine values

## How to apply

Load preprocessed spectral data from supported formats using matchms import utilities. Apply basic peak filtering to ensure data accuracy and remove noisy or low-intensity peaks. Use matchms' pairwise similarity computation functions to calculate Cosine-related scores across all spectrum pairs (or selected pairs for efficiency). Store results in a sparse matrix format to handle large datasets efficiently. Cosine similarity scores typically range from 0 (no resemblance) to 1 (identical spectra); validate that scores are non-null for computed pairs and null for non-computed pairs. For many-to-many comparisons of hundreds of thousands of spectra, the sparse storage format avoids memory overflow.

## Related tools

- **matchms** (Primary library providing pairwise Cosine similarity measure implementations and spectrum data structures) — https://github.com/matchms/matchms
- **pytest** (Testing framework to validate correctness of similarity computations and ensure reproducibility)
- **Spec2Vec** (Optional extension for enhanced spectrum similarity measures tailored for matchms workflows) — https://github.com/iomega/spec2vec
- **MS2DeepScore** (Optional extension for deep learning-based spectrum similarity measures integrated with matchms) — https://github.com/matchms/ms2deepscore

## Examples

```
from matchms import calculate_scores_legacy; from matchms.similarity import CosineGreedy; scores = calculate_scores_legacy(spectrum_list, spectrum_list, CosineGreedy())
```

## Evaluation signals

- All computed pairwise scores fall within the valid range [0, 1] for normalized Cosine similarity.
- Similarity matrix sparsity is correct: non-null values appear only for computed spectrum pairs; uncomputed or invalid pairs remain null.
- Diagonal or self-similarity scores (spectrum compared to itself) equal or approach 1.0 after peak normalization.
- Symmetric property holds for undirected comparisons: score(spectrum_A, spectrum_B) ≈ score(spectrum_B, spectrum_A).
- Memory consumption is proportional to the number of computed pairs, not the theoretical maximum (validating sparse storage benefit).

## Limitations

- Cosine similarity depends critically on accurate peak alignment (matching m/z values); misaligned peaks or different mass calibration can reduce score reliability.
- The measure is sensitive to peak intensity normalization; different normalization strategies may yield different similarity scores for the same spectrum pair.
- Large-scale comparisons (hundreds of thousands of spectra) require sparse matrix handling; dense matrix computation is prohibitively memory-intensive.
- Cosine-related scores alone do not incorporate metadata or chemical structure information; supplementary measures may be needed for comprehensive library matching.

## Evidence

- [other] Compute pairwise Cosine-related similarity scores between all spectrum pairs using matchms similarity measures.: "Compute pairwise Cosine-related similarity scores between all spectrum pairs using matchms similarity measures"
- [readme] A key feature of matchms is its ability to apply various pairwise similarity measures for comparing extensive amounts of spectra. This encompasses not only common Cosine-related scores but also molecular fingerprint-based comparisons and other metadata-related assessments.: "A key feature of matchms is its ability to apply various pairwise similarity measures for comparing extensive amounts of spectra. This encompasses not only common Cosine-related scores"
- [readme] The software supports a range of popular spectral data formats, including mzML, mzXML, msp, metabolomics-USI, MGF, and JSON.: "The software supports a range of popular spectral data formats, including mzML, mzXML, msp, metabolomics-USI, MGF, and JSON"
- [readme] Matchms offers an array of tools for metadata cleaning and validation, alongside basic peak filtering, to ensure data accuracy and integrity.: "Matchms offers an array of tools for metadata cleaning and validation, alongside basic peak filtering, to ensure data accuracy and integrity"
- [readme] Matchms enhances efficiency by using faster similarity measures for initial pre-selection and supports storing results in sparse data formats, enabling the comparison of several hundred thousands of spectra.: "Matchms enhances efficiency by using faster similarity measures for initial pre-selection and supports storing results in sparse data formats"