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
- matchms on PyPI — 0.33.1, released
2026-06-08; Python
>=3.10,<3.15; release history and package metadata. - matchms 0.33.1 release — Python 3.14 support and maintenance changes.
- matchms repository — source,
pyproject.toml, tests, examples, and current README. - matchms releases — complete upstream release history.
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, andspectrumstospectrarenaming. - 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 —
ModifiedCosineGreedyrename andModifiedCosineHungarian. - 0.33.0 —
CosineLinearand preparation for the future 1.0 API. - 0.33.1 — current verified release.
Current API Documentation
- Documentation home
- Core package, Pipeline, Spectrum, and Scores
- Spectrum
- Filtering
- Importing
- Exporting
- Similarity
- Networking
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
- matchms user documentation
- Filtering tutorial
- Building an MS/MS analysis pipeline
- User-guide repository
- Latest recorded guide revision — 2024-06-13; still the newest guide commit on the review date.
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
- Huber et al., 2020 — matchms: processing and similarity evaluation of mass
spectrometry data,
Journal of Open Source Software 5(52), 2411,
DOI
10.21105/joss.02411. - Watrous et al., 2012 — Mass spectral molecular networking of living
microbial colonies,
PNAS 109, E1743-E1752, DOI
10.1073/pnas.1203689109. - Harwood et al., 2023 — BLINK enables ultrafast tandem mass spectrometry
cosine similarity scoring,
Scientific Reports 13, 13462, DOI
10.1038/s41598-023-40496-9. - Li & Fiehn, 2023 — Flash entropy search to query all mass spectral libraries
in real time,
Nature Methods 20, 1475-1478,
DOI
10.1038/s41592-023-02012-9. - Huber et al., 2021 — Spec2Vec: Improved mass spectral similarity scoring
through learning of structural relationships,
PLoS Computational Biology 17, e1008724,
DOI
10.1371/journal.pcbi.1008724.
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=Falsestill harmonizes keys;plot_againstreturns(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_lossadds 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_mzon 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>onhttps://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 includedprecursor_chargeandsplash, 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.