/matchms-spectral-matching

name: matchms-spectral-matching
description: MS spectral matching and metabolite ID with matchms. Import spectra (mzML, MGF, MSP, JSON), filter/normalize peaks, score similarity (cosine, modified cosine, fingerprint), build reproducible pipelines, identify unknowns vs spectral libraries. Use pyopenms for full LC-MS/MS proteomics.
license: Apache-2.0

Matchms — Spectral Matching & Metabolite Identification

Overview

Matchms is a Python library for mass spectrometry data processing focused on spectral similarity calculation and compound identification. It provides multi-format I/O, 50+ spectrum filters for metadata harmonization and peak processing, 8 similarity scoring functions, and a pipeline framework for reproducible analytical workflows.

When to Use

• Identifying unknown metabolites by matching MS/MS spectra against reference libraries
• Computing spectral similarity scores (cosine, modified cosine, fingerprint-based)
• Processing and standardizing mass spectral data from multiple formats (mzML, MGF, MSP, JSON)
• Building reproducible spectral processing pipelines for quality control
• Harmonizing metadata across spectral databases (compound names, SMILES, InChI, adducts)
• Large-scale spectral library comparisons and duplicate detection
• For full LC-MS/MS proteomics workflows (feature detection, protein ID), use **pyopenms** instead
• For chemical structure similarity without mass spectra, use **rdkit** fingerprint comparison

Prerequisites

uv pip install matchms numpy pandas
# For chemical structure processing (SMILES, InChI, fingerprints):
uv pip install matchms[chemistry]

• Python 3.8+; NumPy for peak array operations
• Input: spectral data in MGF, MSP, mzML, mzXML, JSON, or pickle format
• Reference library in any supported format for matching

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: referenceLibrary
    kind: required
    source: user
    ask: "Which spectral library should queries be matched against?"
    default: null

  - id: D2
    param: similarityMeasure
    kind: required
    source: user
    ask: "Should matching require the same precursor mass, or allow a mass shift so modified analogues still match?"
    default: "cosine on matched peaks, precursor mass fixed"

  - id: D3
    param: peakMatchTolerance
    kind: required
    source: data
    ask: "How close must two peaks be in m/z to count as the same fragment?"
    default: "0.1 Da - tighten toward 0.005 for high-resolution data"

  - id: D4
    param: spectrumPreprocessing
    kind: required
    source: user
    ask: "Which peaks should be discarded before scoring - low-intensity noise, peaks near the precursor, or spectra with too few peaks to be informative?"
    default: "drop peaks under 1% relative intensity, require at least 10 peaks"

  - id: D5
    param: scoreCutoff
    kind: required
    source: user
    ask: "What similarity score, and how many matched peaks, should a hit need before it is reported as an identification?"
    default: null

  - id: D6
    param: peakWeighting
    kind: optional
    source: user
    ask: "Should the score weight fragment m/z as well as intensity, favouring informative high-mass fragments?"
    default: "intensity only"

  - id: D7
    param: fingerprintSettings
    kind: optional_conditional
    source: user
    ask: "Which molecular fingerprint should structural similarity use, when comparing hits to known structures?"
    default: "not computed"

D3 and D5 have no safe shared default because they trade off directly: a loose tolerance with a low score cutoff returns an identification for every query spectrum, all of them plausible-looking. Set the tolerance from the instrument's actual accuracy and the cutoff from what the library supports.

Quick Start

from matchms.importing import load_from_mgf
from matchms.filtering import default_filters, normalize_intensities
from matchms.filtering import select_by_relative_intensity, require_minimum_number_of_peaks
from matchms import calculate_scores
from matchms.similarity import CosineGreedy

# Load and process query spectra
queries = list(load_from_mgf("queries.mgf"))
queries = [default_filters(s) for s in queries]
queries = [normalize_intensities(s) for s in queries if s is not None]
queries = [require_minimum_number_of_peaks(s, n_required=5) for s in queries if s is not None]

# Load reference library
refs = list(load_from_mgf("library.mgf"))
refs = [default_filters(s) for s in refs]
refs = [normalize_intensities(s) for s in refs if s is not None]

# Calculate similarity scores
scores = calculate_scores(references=refs, queries=queries,
                          similarity_function=CosineGreedy(tolerance=0.1))
# Get best matches for first query
best = scores.scores_by_query(queries[0], sort=True)[:5]
for match, score_tuple in best:
    print(f"Score: {score_tuple['score']:.3f}, Matches: {score_tuple['matches']}")

Core API

Module 1: Spectrum I/O

Import spectra from multiple file formats and export processed data.

from matchms.importing import (load_from_mgf, load_from_mzml, load_from_msp,
                                load_from_json, load_from_mzxml, load_from_pickle,
                                load_from_usi)
from matchms.exporting import save_as_mgf, save_as_msp, save_as_json, save_as_pickle

# Import from various formats (returns generators)
spectra_mgf = list(load_from_mgf("library.mgf"))
spectra_mzml = list(load_from_mzml("data.mzML"))
spectra_msp = list(load_from_msp("nist_library.msp"))
spectra_json = list(load_from_json("gnps_spectra.json"))
print(f"Loaded: MGF={len(spectra_mgf)}, mzML={len(spectra_mzml)}")

# Export processed spectra
save_as_mgf(spectra_mgf, "processed.mgf")
save_as_json(spectra_mgf, "processed.json")
save_as_pickle(spectra_mgf, "spectra.pickle")  # Fast for intermediate results

# Pickle for large datasets (fastest I/O)
from matchm