K-Dense-AI/scientific-agent-skills / skills/matchms
matchms
VerifiedProcesses, 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| references/filtering.md | markdown | 11.9 KB |
| references/importing_exporting.md | markdown | 10.6 KB |
| references/migration.md | markdown | 8.4 KB |
| references/similarity.md | markdown | 13.8 KB |
| references/sources.md | markdown | 9.6 KB |
| references/workflows.md | markdown | 13.9 KB |
| scripts/library_search.py | script | 20.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |