matchms

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 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.
• ModifiedCosineHungarian — exact modified-cosine assignment.
• NeutralLossesCosine — compares losses computed from precursor and fragments.
• BlinkCosine — fast BLINK-style cosine approximation for larger matrices.
• FlashSimilarity — optimized matrix scoring using spectral entropy or cosine with fragment, neutral-loss, or hybrid matching.
• BinnedEmbeddingSimilarity — binned spectral vectors and optional approximate nearest-neighbor indexing.
• PrecursorMzMatch, ParentMassMatch, MetadataMatch — candidate masks or metadata constraints, not rich spectral scores.
• FingerprintSimilarity — molecular-structure similarity; it is not spectral similarity and requires fingerprints prepared from valid structures.

Read references/similarity.md before choosing a fast method, combining scores, or interpreting structured outputs.

Large Comparisons

For all-vs-all scoring of one collection, set is_symmetric=True:

scores = calculate_scores(
    references=spectra,
    queries=spectra,
    similarity_function=CosineGreedy(tolerance=0.02),
    array_type="sparse",
    is_symmetric=True,
)

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:

uv run python scripts/library_search.py \
  queries.mgf library.msp hits.csv \
  --metric modified \
  --tolerance 0.02 \
  --top-k 10 \
  --min-score 0.6 \
  --min-matches 5

Run --help for fast metrics, preprocessing options, identifier fields, overwrite control, and the explicit large-matrix override.

Spectrum Objects and Visualization

import numpy as np
from matchms import Spectrum

spectrum = Spectrum(
    mz=np.array([100.0, 150.0, 200.0]),
    intensities=np.array([0.2, 1.0, 0.4]),
    metadata={"spectrum_id": "query-1", "precursor_mz": 250.5},
)

print(spectrum.peaks.mz)
print(spectrum.get("precursor_mz"))
losses = spectrum.compute_losses(loss_mz_from=5.0, loss_mz_to=200.0)
spectrum.plot()
spectrum.plot_against(reference_spectrum)

References

Read only the reference needed for the task:

• references/importing_exporting.md — formats, return types, generic I/O, mzSpecLib, score serialization, and pickle safety
• references/filtering.md — current filter catalog, clone/None semantics, default filters, ordering, and SpectrumProcessor
• references/similarity.md — all current similarity classes, outputs, candidate masking, performance, and interpretation
• references/workflows.md — library search, sparse gating, Pipeline, networks, plotting, and provenance
• references/migration.md — breaking changes and deprecated APIs
• references/sources.md — authoritative docs, release notes, user guides, and scientific publications used for this refresh

Non-Negotiable Checks

• Never compare raw queries against differently processed references.
• Never use modified or neutral-loss scoring without valid precursor metadata.
• Never assume a Scores value is a plain float; inspect score_names.
• Never treat a high similarity score alone as confirmed identification.
• Never deserialize untrusted pickle data.
• Never launch an unbounded all-pairs comparison without estimating pair count.

Agent operating procedure

1. Check the environment. Confirm tool versions, the reference genome/annotation build and the input formats (FASTQ, BAM, VCF, h5ad).
2. Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
3. Run a small version first. Run the pipeline on a small subset (one sample, one chromosome, a few thousand cells) first.
4. Execute the full task using the instructions and references above.
5. Validate the result. Check QC metrics, sample identities, genome build consistency and batch effects before interpreting results.
6. Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.

If this happens	Do this
Genome builds or identifiers do not match between inputs	Stop and harmonize (liftover, ID mapping) before continuing.
A function, flag or endpoint in these instructions is missing in the installed version	Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API.
A required input, identifier or parameter is ambiguous	Ask the user, or state the assumption explicitly before running.

Integrity rules

• Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
• Do not interpret biological significance beyond what the statistics support; report multiple-testing correction.
• Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
• Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.

Related skills

• pyopenms: Complete mass spectrometry analysis platform.
• qdrant-vector-search: High-performance vector similarity search engine for RAG and semantic search.
• faiss: Facebook's library for efficient similarity search and clustering of dense vectors.