AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

matchms

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.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--matchms at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

references/sources.md

Sources and Verification Record

This skill was refreshed on 2026-10-01 against the current stable release, matchms 0.33.1. Public PyPI metadata, current official API pages, the released wheel/source, and live public services were checked separately.

Version and Packaging

The 0.33.1 wheel was installed in isolated uv environments on macOS ARM64 with Python 3.13.3. Public objects in core, I/O, filtering, similarity, Pipeline, Fingerprints, and networking were inspected with inspect.signature; decorated writer signatures and return/side-effect semantics were checked in source. The project environment was not given scientific dependencies.

Release Notes Used for Migration

  • 0.27.0 — on-demand losses, removal of add_losses, and spectrums to spectra renaming.
  • 0.30.0 — NumPy 2 baseline and Python 3.13 support.
  • 0.31.0 — FlashSimilarity, BlinkCosine, min-max intensity scaling, and new filters.
  • 0.32.0 — ModifiedCosineGreedy rename and ModifiedCosineHungarian.
  • 0.33.0 — CosineLinear and preparation for the future 1.0 API.
  • 0.33.1 — current verified release.

Current API Documentation

Read the Docs pages identify 0.33.1, but individual cached source pages can be older. The installed released source resolves disagreements, including several docstring/implementation differences reproduced below.

User Guides

The tutorials are useful for workflow concepts but predate releases 0.27-0.33. In particular, the pipeline tutorial still uses ModifiedCosine. Current API docs and release notes supersede tutorial symbol names.

Primary Scientific References

These papers motivate methods and interpretation. The matchms implementation and its exact defaults remain defined by the 0.33.1 API/source.

Ecosystem References

The upstream ecosystem lists complementary tools; they were not runtime-tested as part of this matchms refresh:

Check each project's current compatibility matrix before combining environments; matchms 0.33.1 uses NumPy 2 and Python 3.10-3.14.

Released-Source Findings

  • Spectrum and metadata construction: metadata_harmonization=False still harmonizes keys; plot_against returns (figure, axis).
  • SpectrumProcessor: direct single-spectrum processing can mutate input, while list processing clones inputs without a report; registered filters are reordered.
  • Scores calculation: coordinate-only computation requires a left/inner join and fewer than half of all coordinates; 1-by-1 always calls pair.
  • CosineLinear: close peaks are merged before matching.
  • FlashSimilarity: sparse output still allocates a dense matrix. Entropy with neutral_loss adds fragment and loss terms and gave a self-score near 2 in both pair/matrix tests; the skill explicitly excludes that combination as a normalized score.
  • Metadata export mappings: MassBank-style precursor keys did not return to precursor_mz on reimport.
  • mzSpecLib writer: direct text output rounds intensities to two decimals and assumes collision energy text is expressed in eV.

Endpoint Verification

  • USI helper source and GNPS API documentation: public GET /json/?usi1=<USI> on https://metabolomics-usi.gnps2.org, no authentication or pagination, one JSON spectrum. Live retrieval of the two documented USIs produced 317 and 119 peaks. The first raw response included precursor_charge and splash, which matchms discards. Both were successfully loaded with matchms, identically normalized, and cosine-scored; this was an execution check, not a compound-identification validation.
  • Name-annotation filter source and PubChemPy name-search documentation: public name lookup via PubChemPy, optional local CSV cache, neutral-parent-mass gate, no credential. A live caffeine lookup at 0.001 Da tolerance returned the expected reference InChIKey. This does not establish identity for unknown spectra or ambiguity-free annotation for arbitrary names.

Execution Coverage and Limits

  • uv run skills-ref validate skills/matchms: passed.
  • PYTHONDONTWRITEBYTECODE=1 python tests/run_all.py --isolated matchms: 117 tests passed, including the original 58 and 59 API/CLI regressions.
  • Small synthetic smoke checks passed for mzML/mzXML MS-level selection, precursor and peak arrays; Pipeline/YAML; five network export formats; Fingerprints bridging and three structure metrics; binned and metadata scoring; mirror-plot export; and all ten bundled CLI metrics.
  • MGF/MSP/JSON roundtrips covered matchms, GNPS, NIST, and RIKEN metadata styles; separate regression cases record MassBank precursor loss. Score JSON serialization/reloading was exercised. No untrusted pickle was opened.
  • Flash pair and serial matrix paths were checked. Large-library performance, multiprocessing scaling, ANN recall, acquisition-specific thresholds, downstream mzSpecLib conformance, every repair heuristic, and other operating systems/Python versions were not experimentally validated. Broader snippets are workflow templates requiring representative local validation.
  • The ordinary project-environment pytest invocation skipped both modules because scientific dependencies are intentionally absent; the isolated run above is the executable validation.

No downloaded scientific datasets or research JSON artifacts are shipped.