Migration to matchms 0.33.1

Use this guide when adapting code written for older matchms releases or the official tutorial notebooks last revised in 2024.

Release Timeline That Affects This Skill

0.27.0 (2024-07-10)

add_losses() was removed.
Neutral losses moved to on-demand computation through spectrum.losses and spectrum.compute_losses(...).
public names and parameters began changing from spectrums to spectra; compatibility spellings were deprecated.
Python support moved to 3.9-3.12 at that release.

0.29.x-0.30.x (2025)

importers gained broader pathlib.Path/MGF file-like support and writer behavior was revised.
NumPy 2 became the supported baseline.
Python 3.13 support was added.

0.31.0 (2025-10-06)

FlashSimilarity and BlinkCosine were added.
normalize_intensities(..., scaling=(low, high)) gained min-max scaling.
add_precursor_formula and remove_peaks_relative_to_precursor_mz were added.

0.32.0 (2026-03-04)

ModifiedCosine was renamed to ModifiedCosineGreedy.
ModifiedCosineHungarian was added for exact assignment.

0.33.0-0.33.1 (2026-05-12 to 2026-06-08)

CosineLinear was added.
v1 cleanup/deprecation work began, including migration away from add_fingerprint().
Python 3.14 support was added.

Required Code Changes

Modified cosine class

Old:

python

from matchms.similarity import ModifiedCosine

metric = ModifiedCosine(tolerance=0.02)

Current greedy behavior:

python

from matchms.similarity import ModifiedCosineGreedy

metric = ModifiedCosineGreedy(tolerance=0.02)

Current exact assignment:

python

from matchms.similarity import ModifiedCosineHungarian

metric = ModifiedCosineHungarian(tolerance=0.02)

Update score field names too:

text

ModifiedCosine_score   -> ModifiedCosineGreedy_score
ModifiedCosine_matches -> ModifiedCosineGreedy_matches

Neutral losses

Old:

python

from matchms.filtering import add_losses

spectrum = add_losses(spectrum)

Current:

python

losses = spectrum.losses
custom_losses = spectrum.compute_losses(
    loss_mz_from=5.0,
    loss_mz_to=200.0,
)

NeutralLossesCosine computes the needed losses directly; do not pre-add them.

`SpectrumProcessor`

Old:

python

processor = SpectrumProcessor(
    [
        normalize_intensities,
        lambda spectrum: select_by_relative_intensity(
            spectrum,
            intensity_from=0.01,
        ),
    ]
)
processed = [processor(spectrum) for spectrum in spectra]

Current:

python

processor = SpectrumProcessor(
    [
        normalize_intensities,
        (select_by_relative_intensity, {"intensity_from": 0.01}),
    ]
)
processed, report = processor.process_spectra(
    spectra,
    progress_bar=False,
    create_report=False,
)

For one spectrum, call processor.process_spectrum(spectrum).

The aggregate default_filters callable is not registered in SpectrumProcessor's built-in filter order. Run it before the processor or expand its nine component filters; otherwise it is treated as custom and moved after registered filters.

Score access

Old assumptions:

python

reference_index, score = scores.scores_by_query(query, sort=True)[0]
reference = references[reference_index]
numeric = scores.scores[j, i]

Current:

python

score_name = "CosineGreedy_score"
reference, value = scores.scores_by_query(
    query,
    name=score_name,
    sort=True,
)[0]

numeric = float(value[score_name])
matches = int(value["CosineGreedy_matches"])
matrix = scores.to_array(score_name)

Scores.scores is a layered sparse container. Always inspect scores.score_names.

Metadata matching

Old:

python

MetadataMatch(field="ionmode", matching_type="exact")

Current:

python

MetadataMatch(field="ionmode", matching_type="equal_match")

Current matching types are equal_match and difference.

High-peak requirement

Old:

python

require_minimum_number_of_high_peaks(
    spectrum,
    n_required=5,
    intensity_threshold=0.05,
)

Current:

python

require_minimum_number_of_high_peaks(
    spectrum,
    no_peaks=5,
    intensity_percent=5.0,
)

intensity_percent is expressed as a percentage.

Top-k peak filter

Old examples may use a ratio_desired argument. Current:

python

remove_peaks_outside_top_k(
    spectrum,
    k=6,
    mz_window=50,
)

For global peak-count reduction, use reduce_to_number_of_peaks(n_required=..., n_max=..., ratio_desired=...).

Precursor upper bound

Old:

python

require_precursor_below_mz(spectrum, maximum_accepted_mz=1000)

Current:

python

require_precursor_mz(
    spectrum,
    minimum_accepted_mz=10.0,
    maximum_mz=1000.0,
)

require_precursor_below_mz() is deprecated.

Parent-mass repair names

Older examples may refer to:

text

repair_parent_mass_is_mol_wt
repair_adduct_based_on_smiles

Current public helpers include:

text

repair_parent_mass_is_molar_mass
repair_adduct_and_parent_mass_based_on_smiles
repair_adduct_based_on_parent_mass
repair_parent_mass_from_smiles

Review semantics and supply required mass_tolerance arguments rather than performing a mechanical rename.

Fingerprints

Old:

python

spectra = [add_fingerprint(spectrum, fingerprint_type="morgan2")
           for spectrum in spectra]

add_fingerprint() still works in 0.33.1 but is marked for removal in matchms 1.0. Forward-oriented preparation:

python

from matchms import Fingerprints

fp_store = Fingerprints(
    fingerprint_algorithm="morgan2",
    fingerprint_method="bit",
    nbits=2048,
)
fp_store.compute_fingerprints(spectra)

Current FingerprintSimilarity still reads a "fingerprint" spectrum field. When that class is needed in 0.33.1, bridge the store explicitly:

python

for spectrum in spectra:
    fingerprint = fp_store.get_fingerprint_by_spectrum(spectrum)
    if fingerprint is not None:
        spectrum.set("fingerprint", fingerprint)

Installation

Old:

bash

uv pip install matchms[chemistry]

Current:

bash

uv pip install "matchms==0.33.1"

The 0.33.1 package metadata has no chemistry extra and includes RDKit as a regular dependency.

Spectrum serialization

Old:

python

from matchms.exporting import save_as_pickle

save_as_pickle(spectra, "spectra.pkl")

Current public pattern:

python

from matchms.exporting import save_spectra

save_spectra(spectra, "trusted-cache.pickle")

save_as_pickle is not exported in 0.33.1. The generic writer recognizes .pickle, not .pkl. Prefer portable MGF/MSP/JSON for exchanged data, and never load untrusted pickle.

Generic I/O and overwrite behavior

Prefer:

python

from matchms.exporting import save_spectra
from matchms.importing import load_spectra

spectra = list(load_spectra("input.mgf"))
save_spectra(spectra, "output.msp")

save_spectra() refuses an existing output unless appending MGF/MSP data. Direct save_as_mgf() and save_as_msp() default to append mode, so specify write mode explicitly when bypassing the generic writer.

Deprecated Compatibility Names

Replace these even if 0.33.1 still accepts some of them:

text

spectrums             -> spectra
process_spectrums()   -> process_spectra()
import_spectrums()    -> import_spectra()
spectrums_queries     -> spectra_queries
spectrums_references  -> spectra_references

Do not suppress deprecation warnings globally; they are migration signals for the forthcoming 1.0 API.

Tutorial Caveat

The separate matchms-docs user-guide repository was last revised on 2024-06-13. Its pipeline/filtering explanations remain useful, but the tutorial still contains examples using ModifiedCosine and older spelling. Prefer the current Read the Docs API and release notes for symbol names and signatures.

Migration Verification

After migration:

print matchms.__version__ and confirm 0.33.1;
run imports with deprecation warnings visible;
inspect processor.processing_steps;
compare spectrum counts before/after processing;
print scores.score_names;
test one known spectrum pair and one query/library search;
compare old and new result rankings on a representative subset;
verify serialized outputs by reopening them; and
document any score changes caused by algorithm renaming, filtering, or dependency updates.