Cosine similarity computation

cosine-similarity-computation

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Compute cosine similarity between two MS/MS spectra by normalizing their fragment peak intensity vectors and calculating their dot product. This foundational similarity measure is used to discover structurally related molecules in mass spectral library searching.

When to use

When comparing two MS/MS spectra (query and reference) to quantify their spectral resemblance for compound identification or molecular networking, particularly when you need a simple, symmetric measure that is insensitive to precursor mass differences and does not require peak alignment across m/z shifts.

When NOT to use

• When spectra have different precursor masses and you want to align peaks allowing for mass offset — use modified cosine similarity instead.
• When you want to compare spectra using neutral loss peaks (fragments relative to precursor m/z) — use neutral loss similarity instead.
• When input spectra contain unfiltered noise or very weak peaks; consider preprocessing to remove low-intensity peaks first.

Inputs

• Query MS/MS spectrum (m/z array and intensity array)
• Reference MS/MS spectrum (m/z array and intensity array)

Outputs

• Cosine similarity score (float, range 0–1)

How to apply

Extract the m/z and intensity values from both the query and reference MS/MS spectra. Create normalized intensity vectors for all fragment peaks in each spectrum. Compute the cosine similarity as the dot product of the two normalized intensity vectors, which ranges from 0 (orthogonal/completely dissimilar spectra) to 1 (identical spectra). The measure is symmetric and does not account for mass offsets between spectra; if such offsets matter, use modified cosine similarity instead. Return the cosine similarity score as a float between 0 and 1.

Related tools

• spectrum_utils (MS/MS spectrum data structure and I/O, used to load and manipulate spectra for similarity computation) — github.com/bittremieux/cosine_neutral_loss
• cosine_neutral_loss repository (Reference implementation of cosine, modified cosine, and neutral loss similarity measures for spectrum comparison) — github.com/bittremieux/cosine_neutral_loss

Examples

import spectrum_utils.spectrum as sus
spectrum1 = sus.MsmsSpectrum.from_usi('mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000424840')
spectrum2 = sus.MsmsSpectrum.from_usi('mzspec:MSV000086109:BD5_dil2x_BD5_01_57213:scan:760')
plot.plot_mirror(spectrum1, spectrum2, 'cosine', 'cosine.png')

Evaluation signals

• Output score is a float in the range [0, 1] with no NaN or infinite values.
• Identical spectra (same peaks and intensities) yield a cosine similarity of ~1.0.
• Completely disjoint spectra (no overlapping m/z peaks) yield a cosine similarity of 0.
• The measure is symmetric: cosine_similarity(spectrum_A, spectrum_B) == cosine_similarity(spectrum_B, spectrum_A).
• Normalized intensity vectors have magnitude 1 before dot product computation (unit vector check).

Limitations

• Cosine similarity is insensitive to precursor mass differences; spectra with the same fragments but different parent ions will score high, which may or may not reflect true structural similarity.
• The measure treats all peak matches equally regardless of their m/z values; it does not penalize mass offset or peak alignment errors.
• Very low-intensity peaks contribute minimally to the similarity score after normalization, potentially obscuring minor structural differences.
• No built-in handling for isotope patterns, in-source fragmentation, or adduct variants.

Evidence

• [readme] Similarity measures that are currently implemented are: - Cosine similarity: "Similarity measures that are currently implemented are: - Cosine similarity"
• [readme] Stein, S. E. & Scott, D. R. Optimization and testing of mass spectral library search algorithms for compound identification: "Stein, S. E. & Scott, D. R. Optimization and testing of mass spectral library search algorithms for compound identification"
• [intro] Comparison of cosine, modified cosine, and neutral loss based spectral alignment for discovery of structurally related molecules: "Comparison of cosine, modified cosine, and neutral loss based spectral alignment for discovery of structurally related molecules"
• [other] Compute cosine similarity on the aligned peak intensities. Return the modified cosine similarity score as a float between 0 and 1.: "Compute cosine similarity on the aligned peak intensities. Return the modified cosine similarity score as a float between 0 and 1."