Skip to content

K-Dense-AI/scientific-agent-skills / skills/matchms

matchms

Verified

Processes, cleans, compares, and searches 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.

FileKindSize
SKILL.mdskill md12.5 KB
references/filtering.mdmarkdown11.9 KB
references/importing_exporting.mdmarkdown10.6 KB
references/migration.mdmarkdown8.4 KB
references/similarity.mdmarkdown13.8 KB
references/sources.mdmarkdown9.6 KB
references/workflows.mdmarkdown13.9 KB
scripts/library_search.pyscript20.6 KB

references/migration.md

View on GitHub
# 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:

```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, max_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:

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.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall