Spectral similarity and compound identification for metabolomics. Use for comparing mass spectra, computing similarity scores (cosine, modified cosine), and identifying unknown compounds from spectral libraries. Best for metabolite identification, spectral matching, library searching. For full LC-MS/MS proteomics pipelines use pyopenms.
SKILL.md
Matchms
Purpose and Scope
Matchms is a Python package for importing, cleaning, processing, and comparing
tandem mass spectra. This skill targets matchms 0.33.1, released 2026-06-08,
and corrects several breaking API changes that older tutorials do not reflect.
Use matchms for:
MS/MS library search and query-versus-reference scoring
Metadata harmonization, adduct/precursor handling, and peak filtering
Cosine, modified-cosine, neutral-loss, approximate, and entropy scoring
Structured score matrices, top-hit extraction, and spectral networks
MGF, MSP, mzML, mzXML, JSON, mzSpecLib, and metabolomics-USI workflows
Do not use matchms as a replacement for:
LC-MS feature detection, chromatographic alignment, peptide identification, or
protein quantification — use pyopenms
Vendor raw-file conversion — convert to mzML/mzXML first
A validated compound-identification protocol — similarity is evidence, not
proof of identity
Install the Verified Release
Create or activate an environment, then install the release used by this skill:
uv pip install "matchms==0.33.1"
Verify the runtime:
uv run python -c "import matchms; print(matchms.__version__)"
Matchms 0.33.1 supports Python 3.10-3.14 and installs RDKit as a regular
dependency. The old matchms[chemistry] extra is not part of the current
package metadata.
Operating Workflow
Inspect the inputs. Record format, spectrum count, MS level, precursor
coverage, ion mode, peak counts, and identifier fields.
Load with metadata harmonization enabled unless preserving source keys is
a deliberate requirement.
Apply the same peak-processing steps to query and reference spectra.
Keep metadata enrichment separate when reference annotations are richer.
Drop invalid spectra explicitly. Many require_* filters return None.
Choose the score from the scientific question, not from convenience.
Modified and neutral-loss scores require valid precursor_mz.
Estimate len(references) * len(queries) before scoring. A sparse result
container does not automatically avoid computing every requested pair.
Report score settings and evidence. Include tolerance, preprocessing,
score name, number of matched peaks when available, and candidate metadata.
Validate top hits visually and chemically. Use mirror plots, precursor
agreement, ion/adduct compatibility, and orthogonal evidence.
Current API Guardrails
These points prevent the most common failures from pre-0.33 examples:
Use ModifiedCosineGreedy or ModifiedCosineHungarian; ModifiedCosine was
removed in 0.32.0.
Do not call add_losses(). It was removed in 0.27.0; use
spectrum.losses, spectrum.compute_losses(...), or
NeutralLossesCosine directly.
SpectrumProcessor is not callable. Use process_spectrum() or
process_spectra().
Scores.scores is a StackedSparseArray, often with separate structured
fields such as CosineGreedy_score and CosineGreedy_matches.
scores_by_query() returns (reference_spectrum, score_record) pairs, not
reference indices.
Prefer spectra in parameter names. The legacy spelling spectrums is
deprecated.
Never load pickle files from an untrusted source; unpickling can execute code.
See references/migration.md for a complete old-to-current mapping.
Quick Start: Clean and Search a Library
from matchms import SpectrumProcessor, calculate_scores
from matchms.filtering import (
default_filters,
normalize_intensities,
require_minimum_number_of_peaks,
select_by_relative_intensity,
)
from matchms.importing import load_spectra
from matchms.similarity import ModifiedCosineGreedy
def load_and_process(path):
spectra = [default_filters(spectrum) for spectrum in load_spectra(path)]
processor = SpectrumProcessor(
[
normalize_intensities,
(select_by_relative_intensity, {"intensity_from": 0.01}),
(require_minimum_number_of_peaks, {"n_required": 5}),
]
)
processed, _ = processor.process_spectra(
spectra,
progress_bar=False,
create_report=False,
)
return processed
references = load_and_process("library.msp")
queries = load_and_process("queries.mgf")
metric = ModifiedCosineGreedy(tolerance=0.02)
scores = calculate_scores(
references=references,
queries=queries,
similarity_function=metric,
)
score_name = "ModifiedCosineGreedy_score"
matches_name = "ModifiedCosineGreedy_matches"
for query in queries:
ranked = scores.scores_by_query(query, name=score_name, sort=True)
for reference, values in ranked[:5]:
print(
query.get("spectrum_id", query.get("id")),
reference.get("compound_name", reference.get("spectrum_id")),
float(values[score_name]),
int(values[matches_name]),
)
SpectrumProcessor automatically orders built-in filters according to matchms's
filter order. The aggregate default_filters callable is not in that registry,
so run it first as above or expand its nine component filters. Inspect
processor.processing_steps and preserve it with results.
Pair Scoring
Similarity classes expose pair() for one reference/query pair. Cosine-family
results are structured NumPy scalars:
from matchms.similarity import CosineGreedy
result = CosineGreedy(tolerance=0.02).pair(reference, query)
similarity = float(result["score"])
matched_peaks = int(result["matches"])
Use calculate_scores() for matrix-oriented methods such as
FlashSimilarity; its single-pair path is supported but intentionally not the
optimized path.
Choose a Similarity Method
CosineGreedy — standard peak cosine with greedy peak assignment.
CosineHungarian — exact assignment; slower, useful for benchmarks.
CosineLinear — current linear-scaling cosine implementation.
ModifiedCosineGreedy — permits precursor-delta-shifted matches; common for
analog search.
For a precursor-gated search, compute and filter PrecursorMzMatch first, then
calculate the spectral metric only on retained coordinates through Pipeline
or Scores.calculate(...). See references/workflows.md.
Do not choose a universal "identification threshold." Score distributions
depend on preprocessing, mass accuracy, collision conditions, library quality,
and metric. At minimum, retain both score and matched-peak count for
cosine-family methods.
Bundled Library-Search CLI
scripts/library_search.py provides a reproducible query-versus-library search
with current score extraction, pair-count limits, preprocessing, and CSV output:
