/matchms

name: matchms
description: Process, clean, compare, and search tandem mass spectra with matchms. Use for MS/MS file I/O, metadata harmonization, peak filtering, spectral similarity, library matching, score matrices, and molecular-similarity networks. Use pyopenms instead for LC-MS feature detection or proteomics pipelines.
allowed-tools: Read Write Edit Bash
license: Apache-2.0
compatibility: Requires Python >=3.10,<3.15, uv, and matchms 0.33.1. Local file workflows need no credentials; metabolomics-USI loading requires network access.
metadata:
  version: "2.1"
  skill-author: K-Dense Inc.

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

1. **Inspect the inputs.** Record format, spectrum count, MS level, precursor coverage, ion mode, peak counts, and identifier fields. 2. **Load with metadata harmonization enabled** unless preserving source keys is a deliberate requirement. 3. **Apply the same peak-processing steps** to query and reference spectra. Keep metadata enrichment separate when reference annotations are richer. 4. **Drop invalid spectra explicitly.** Many `require_*` filters return `None`. 5. **Choose the score from the scientific question**, not from convenience. Modified and neutral-loss scores require valid `precursor_mz`. 6. **Estimate `len(references) * len(queries)` before scoring.** A sparse result container does not automatically avoid computing every requested pair. 7. **Report score settings and evidence.** Include tolerance, preprocessing, score name, number of matched peaks when available, and candidate metadata. 8. **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()`.

• `process_spectra()` returns `(processed_spectra, processing_report)`.
• `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 pai