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. The stable release and public symbols were rechecked on 2026-10-01; development-branch changes are not automatically supported by the pinned release.

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:

from matchms.similarity import ModifiedCosine

metric = ModifiedCosine(tolerance=0.02)

Current greedy behavior:

from matchms.similarity import ModifiedCosineGreedy

metric = ModifiedCosineGreedy(tolerance=0.02)

Current exact assignment:

from matchms.similarity import ModifiedCosineHungarian

metric = ModifiedCosineHungarian(tolerance=0.02)

Update score field names too:

ModifiedCosine_score   -> ModifiedCosineGreedy_score
ModifiedCosine_matches -> ModifiedCosineGreedy_matches

Neutral losses

Old:

from matchms.filtering import add_losses

spectrum = add_losses(spectrum)

Current:

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:

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

Current:

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:

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

Current:

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:

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

Current:

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

Current matching types are equal_match and difference.

High-peak requirement

Old:

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

Current:

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:

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:

require_precursor_below_mz(spectrum, max_mz=1000)

Current:

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:

repair_parent_mass_is_mol_wt
repair_adduct_based_on_smiles

Current public helpers include:

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:

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:

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:

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

Installation

Old:

uv pip install matchms[chemistry]

Current:

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:

from matchms.exporting import save_as_pickle

save_as_pickle(spectra, "spectra.pkl")

Current public pattern:

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:

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:

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:

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