# Spectral Similarity Matching Algorithms

> Use when when you have experimental MS/MS spectra (from mzML or .rda preprocessed format) and need to annotate them against a reference fragmentation library.

- Skill: `holobiomicslab/spectral-similarity-matching-algorithms` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/spectral-similarity-matching-algorithms`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/spectral-similarity-matching-algorithms/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/spectral-similarity-matching-algorithms

---


# spectral-similarity-matching-algorithms

## Summary

High-throughput spectral similarity matching against large fragmentation libraries using mass-error-tolerant fragment matching and cosine similarity to annotate experimental MS/MS spectra. Critical for identifying lipids and other metabolites when working with mass spectrometry datasets.

## When to use

When you have experimental MS/MS spectra (from mzML or .rda preprocessed format) and need to annotate them against a reference fragmentation library. Specifically applicable when processing lipidomics data with MS1 and MS2 measurements, and you require high-throughput matching (millions to billions of queries) against hierarchically organized spectral libraries with defined mass tolerances (e.g., 5–10 ppm).

## When NOT to use

- Input spectra are already pre-identified or de-replicated; use this skill only on raw or minimally processed MS/MS data.
- Library is unstructured or not indexed for rapid lookup; hierarchical organization and in-memory indexing are prerequisites for achieving stated throughput.
- Mass tolerances are incompatible with your instrument calibration or experimental design (e.g., if your ppm error systematically exceeds 10 ppm, matching will fail or produce false positives).

## Inputs

- Preprocessed MS/MS spectral data (.rda format or in-memory array of MS1 m/z, MS2 fragments, and intensities)
- Hierarchical fragmentation library (indexed structure with chain compositions, double-bond locations, and reference spectra)
- MS1 mass tolerance parameter (ppm1, typically 5 ppm)
- MS2 mass tolerance parameter (ppm2, typically 10 ppm)
- MS2 intensity filter threshold (0–1 scale, e.g., 0.10)

## Outputs

- Matched spectrum annotations with library entry identifiers and similarity scores
- CSV-format identification results with ranked candidates
- Query throughput metrics (queries/second, wall-clock execution time)

## How to apply

Load the hierarchical fragmentation library (e.g., 168.6 million lipid entries organized by chain composition and double-bond locations) into an indexed in-memory data structure optimized for rapid lookup. Implement spectral querying logic using cosine similarity or mass-error-tolerant fragment matching to compare experimental MS/MS spectra against library entries, applying MS1 tolerance (ppm1) and MS2 tolerance (ppm2) thresholds. Execute the query engine on preprocessed spectral data, measuring wall-clock time and query throughput (queries/second). Apply MS2 intensity filtering (e.g., MS2_filter=0.10 to remove fragments below 10% of max intensity) before matching. Validate achievement of target throughput (e.g., ~70 billion queries in <1 second for large libraries) and record actual performance metrics to confirm efficiency gains over sequential matching.

## Related tools

- **XCMS** (Upstream MS data processing: peak alignment, matching, and retention-time normalization before spectral similarity matching)
- **CAMERA** (Compound spectra extraction and annotation to support spectral querying workflow)
- **RaMS** (Data preprocessing to convert mzML format to .rda format for input to spectral matching module)
- **LipidIN EQ module** (Core implementation of expeditious querying with cosine similarity and mass-error-tolerant fragment matching) — https://github.com/LinShuhaiLAB/LipidIN

## Examples

```
source('EQ.r'); EQ(filename='QC_POS1.rda', ppm1=5, ppm2=10, ESI='p')
```

## Evaluation signals

- Query throughput meets or exceeds target (e.g., ~70 billion queries/second for 168.6 million library entries on standardized hardware).
- Wall-clock execution time for a benchmark query set is <1 second (or scales linearly with number of queries).
- Similarity scores for known positive matches fall above a credible cosine similarity threshold (e.g., >0.7); false-positive rates remain low when combined with secondary filtering (LCI module).
- Output CSV contains expected fields (lipid ID, m/z, MS/MS match score, ranked candidates) with no missing or malformed entries.
- Mass error for matched fragments falls within specified tolerances (ppm1 for MS1, ppm2 for MS2) across >95% of matches.

## Limitations

- Throughput depends critically on library indexing and in-memory availability; very large libraries (>1 billion entries) may require distributed or on-disk strategies not detailed here.
- Cosine similarity matching alone produces high false-positive rates; the workflow requires downstream filtering via the LCI module (relative retention time rules) to achieve 5.7% FDR and reduce false annotations.
- Performance metrics (70 billion queries/second) were benchmarked on specific hardware (13th Gen Intel i7-13700F, 64 GB RAM, Windows 11); throughput will vary with system configuration.
- MS2 intensity filtering (MS2_filter parameter) is sensitive to instrumental noise and detector saturation; threshold must be tuned per instrument and sample type to avoid loss of weak but real fragments.
- Library coverage is limited to lipid species with documented fragmentation patterns; novel lipids or heavily modified variants not represented in the 168.6 million entries will fail to match.

## Evidence

- [other] Implement spectral querying logic using cosine similarity or mass-error-tolerant fragment matching to compare experimental MS/MS spectra against library entries.: "Implement spectral querying logic using cosine similarity or mass-error-tolerant fragment matching to compare experimental MS/MS spectra against library entries."
- [other] LipidIN implements an expeditious querying module that performs spectral matching against a 168.6 million lipid fragmentation hierarchical library, achieving throughput of approximately 70 billion spectral queries in less than 1 second.: "LipidIN implements an expeditious querying module that performs spectral matching against a 168.6 million lipid fragmentation hierarchical library, achieving throughput of approximately 70 billion"
- [other] Load the hierarchical lipid fragmentation library (168.6 million entries organized by chain composition and double-bond locations) into an indexed in-memory data structure optimized for rapid spectral similarity lookup.: "Load the hierarchical lipid fragmentation library (168.6 million entries organized by chain composition and double-bond locations) into an indexed in-memory data structure optimized for rapid"
- [readme] MS2_filter: a value of 0-1, MS2 fragments with intensity lower than the MS2_filter*max intensity will be deleted: "MS2_filter: a value of 0-1, MS2 fragments with intensity lower than the MS2_filter*max intensity will be deleted"
- [readme] ppm1: MS1 m/z tolerance at parts per million (ppm); ppm2: MS2 m/z tolerance at parts per million (ppm): "ppm1: MS1 m/z tolerance at parts per million (ppm); ppm2: MS2 m/z tolerance at parts per million (ppm)"