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/similarity.md

View on GitHub
# Similarity and Scores (matchms 0.33.1)

Use this reference to select a similarity class, interpret its output, extract
top hits, or scale a comparison. The authoritative API is
[`matchms.similarity`](https://matchms.readthedocs.io/en/latest/api/matchms.similarity.html).

## Core Calculation

```python
from matchms import calculate_scores
from matchms.similarity import CosineGreedy

metric = CosineGreedy(tolerance=0.02)
scores = calculate_scores(
    references=reference_spectra,
    queries=query_spectra,
    similarity_function=metric,
    array_type="numpy",
    is_symmetric=False,
)
```

Set `is_symmetric=True` only when references and queries are the same collection
in the same order and the metric is symmetric.

## Understand the Output Before Indexing

`Scores.scores` is a `sparsestack.StackedSparseArray`, not a plain two-dimensional
NumPy array. Its shape is `(n_references, n_queries, n_score_fields)`.

Cosine-family methods produce two fields:

```python
print(scores.score_names)
# ('CosineGreedy_score', 'CosineGreedy_matches')

similarities = scores.to_array("CosineGreedy_score")
matched_peaks = scores.to_array("CosineGreedy_matches")
```

Scalar methods such as `FlashSimilarity`, `PrecursorMzMatch`, and
`FingerprintSimilarity` produce one field named after the class.

### Top hits for one query

```python
score_name = "CosineGreedy_score"
matches_name = "CosineGreedy_matches"

ranked = scores.scores_by_query(query_spectrum, name=score_name, sort=True)
for reference, value in ranked[:10]:
    print(
        reference.get("spectrum_id"),
        float(value[score_name]),
        int(value[matches_name]),
    )
```

The first tuple item is the actual reference `Spectrum`, not an integer index.
The second item can be a structured NumPy record containing every score field.

### Iterate stored pairs

```python
for reference, query, values in scores:
    print(reference.get("id"), query.get("id"), values)
```

Iteration covers stored coordinates. After sparse filtering, that may be only a
subset of the Cartesian product.

## Peak-Based Cosine Methods

All cosine classes below use:

```text
tolerance=0.1, mz_power=0.0, intensity_power=1.0
```

unless noted otherwise. Tolerance is in daltons for these classes.

### `CosineGreedy`

Greedily assigns candidate peak pairs within tolerance.

Use for:

- routine spectral-library comparisons;
- a transparent baseline;
- moderate collections where exact assignment is not essential.

Output fields: `CosineGreedy_score`, `CosineGreedy_matches`.

### `CosineHungarian`

Uses optimal assignment rather than greedy assignment.

Use for:

- benchmarking peak-assignment effects;
- smaller datasets;
- cases where greedy ambiguity materially affects results.

It is computationally more expensive than `CosineGreedy`.

### `CosineLinear`

Added in 0.33.0. It first greedily merges nearby peaks using a `2 * tolerance`
separation criterion, then performs linear-time matching on the merged spectra.
The score and matched-peak count therefore need not equal `CosineGreedy` on the
original peaks, even with identical tolerance and intensity powers.

Use when:

- cosine is the intended metric;
- matrix size makes assignment cost important; and
- you have benchmarked agreement and runtime on representative spectra.

Output fields: `CosineLinear_score`, `CosineLinear_matches`.

## Modified Cosine

Modified cosine allows unshifted peak matches and matches shifted by the
difference in precursor m/z. Both spectra need valid `precursor_mz`.

### `ModifiedCosineGreedy`

```python
from matchms.similarity import ModifiedCosineGreedy

metric = ModifiedCosineGreedy(tolerance=0.02)
```

This is the current name for the implementation formerly called
`ModifiedCosine`. It uses greedy assignment.

### `ModifiedCosineHungarian`

```python
from matchms.similarity import ModifiedCosineHungarian

metric = ModifiedCosineHungarian(tolerance=0.02)
```

Use for exact modified-cosine assignment in benchmarks or method development.
It is slower than the greedy variant.

Do not infer that a shifted match proves a specific chemical transformation.
Inspect precursor delta, adduct/charge compatibility, shifted peaks, and
orthogonal annotations.

## Neutral-Loss Cosine

```python
from matchms.similarity import NeutralLossesCosine

metric = NeutralLossesCosine(
    tolerance=0.02,
    ignore_peaks_above_precursor=True,
)
```

`NeutralLossesCosine` computes losses from `precursor_mz - fragment_mz`.
Both spectra require precursor m/z. Do not call the removed `add_losses()`
filter; losses are computed on demand in current matchms.

Output fields: `NeutralLossesCosine_score`,
`NeutralLossesCosine_matches`.

## Fast Matrix-Oriented Methods

### `BlinkCosine`

BLINK-style approximate cosine:

```python
from matchms.similarity import BlinkCosine

metric = BlinkCosine(
    tolerance=0.01,
    bin_width=0.001,
    min_relative_intensity=0.01,
    top_k=None,
    batch_size=1024,
    sparse_score_min=0.0,
)
```

Important parameters include peak preprocessing, precursor cropping, batch
size, and sparse score minimum. By default `crop_above_precursor=True` crops
where a precursor is available; record precursor coverage or disable this
option when that extra step is inappropriate. Output contains a float32 score
and matched-peak count. Validate approximation behavior against `CosineGreedy` on a subset
before changing production workflows.

### `FlashSimilarity`

Fast matrix scoring based on the Flash Entropy approach:

```python
from matchms.similarity import FlashSimilarity

entropy = FlashSimilarity(
    score_type="spectral_entropy",
    matching_mode="fragment",
    tolerance=0.02,
)

fast_modified_cosine = FlashSimilarity(
    score_type="cosine",
    matching_mode="hybrid",
    tolerance=0.02,
)
```

Current choices and behavior:

- `score_type`: `spectral_entropy` or `cosine`
- `matching_mode`: `fragment`, `neutral_loss`, or `hybrid`
- `use_ppm=True` switches fragment tolerance to symmetric ppm; default is Da
- `remove_precursor=False`, `noise_cutoff=0.01`, `merge_within=0`, and
  `normalize_to_half=True` are defaults; entropy weighting is internal
- neutral-loss/hybrid matching and an identity precursor gate need valid
  precursor metadata
- `identity_precursor_tolerance` and `identity_use_ppm` control a separate
  precursor gate

`pair()` exists but emits a warning because it is not the optimized use. Call
`calculate_scores()` for multi-spectrum matrices. A 1-by-1 `Scores.calculate`
call still uses `pair()`. Flash output is a scalar field named `FlashSimilarity`,
not a score/matches pair. Hybrid matching gives unshifted fragment matches
priority; do not assume equality with greedy or Hungarian modified cosine.

In 0.33.1, `matrix()` allocates a dense output even for `array_type="sparse"`,
and `is_symmetric=True` does not reduce Flash runtime. Its default worker count
uses available CPUs on Unix; call `metric.matrix(..., n_jobs=1)` for an explicit
serial calculation (this returns a raw array, not `Scores`). Do not assume a
sparse output is a bounded-memory or bounded-CPU search.

**Verified 0.33.1 defect:** `score_type="spectral_entropy"` with
`matching_mode="neutral_loss"` adds fragment and loss contributions, producing
a self-score near 2 on the tested three-peak spectrum. Do not use that
combination as a normalized entropy score; choose fragment entropy or
`NeutralLossesCosine` as appropriate. Do not silently clip or rescale it.

### `BinnedEmbeddingSimilarity`

```python
from matchms.similarity import BinnedEmbeddingSimilarity

metric = BinnedEmbeddingSimilarity(
    similarity="cosine",
    max_mz=1005,
    bin_width=1.0,
    intensity_power=1.0,
)
```

This creates fixed-width binned spectral embeddings. Bin width controls both
resolution and dimensionality. Reject empty/all-zero embeddings, including
spectra with no retained peak below `max_mz`, before scoring. The class also supports approximate-neighbor
indexing through the current PyNNDescent backend; use it only after checking
recall against exact neighbors. In 0.33.1 the matrix method accepts only dense
output and `is_symmetric=True`; use it for all-vs-all input. A normal rectangular
`calculate_scores` call with its default `is_symmetric=False` raises an error.
For rectangular embedding comparisons, compute the embeddings explicitly and
compare those with the intended vector metric.

## Candidate and Metadata Matches

These methods are useful as gates or additional evidence. They are not
substitutes for peak-pattern similarity.

### `PrecursorMzMatch`

```python
from matchms.similarity import PrecursorMzMatch

absolute = PrecursorMzMatch(tolerance=0.02, tolerance_type="Dalton")
relative = PrecursorMzMatch(tolerance=10, tolerance_type="ppm")
```

Output field: `PrecursorMzMatch` (boolean).

### `ParentMassMatch`

```python
from matchms.similarity import ParentMassMatch

metric = ParentMassMatch(tolerance=0.02)
```

Requires `parent_mass`. Output field: `ParentMassMatch` (boolean). The current
constructor does not expose a ppm mode.

### `MetadataMatch`

```python
from matchms.similarity import MetadataMatch

same_mode = MetadataMatch(field="ionmode", matching_type="equal_match")
near_rt = MetadataMatch(
    field="retention_time",
    matching_type="difference",
    tolerance=0.2,
)
```

Current matching types are `equal_match` and `difference`. Older examples that
use `matching_type="exact"` are invalid.

### `IntersectMz`

`IntersectMz(scaling=1.0)` is a simple m/z-intersection score useful in tests or
specialized workflows. It is not a drop-in replacement for tolerance-aware,
intensity-weighted spectral scoring.

## Molecular Fingerprint Similarity

`FingerprintSimilarity` compares molecular fingerprints derived from known
structures. It therefore measures structure similarity, not spectral
similarity.

```python
from matchms import Fingerprints, calculate_scores
from matchms.similarity import FingerprintSimilarity

fp_store = Fingerprints(
    fingerprint_algorithm="morgan2",
    fingerprint_method="bit",
    nbits=2048,
)
fp_store.compute_fingerprints(spectra)

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

scores = calculate_scores(
    usable,
    usable,
    FingerprintSimilarity(similarity_measure="jaccard"),
    is_symmetric=True,
)
```

Similarity measures are `jaccard`, `dice`, and `cosine`.

The old `add_fingerprint()` filter still satisfies the 0.33.1
`FingerprintSimilarity` interface, but it is marked for removal in matchms 1.0.
The `Fingerprints` bridge above avoids calling that deprecated filter while
remaining compatible with the current similarity class.

## Efficient Precursor-Gated Search

Filter score coordinates before calculating an expensive spectral metric:

```python
from matchms import calculate_scores
from matchms.similarity import ModifiedCosineGreedy, PrecursorMzMatch

scores = calculate_scores(
    references,
    queries,
    PrecursorMzMatch(tolerance=10, tolerance_type="ppm"),
    array_type="sparse",
)
scores.filter_by_range(name="PrecursorMzMatch", low=0.5)
if len(scores.scores.row) == 0:
    raise ValueError("No candidates passed the precursor gate")
scores.calculate(
    ModifiedCosineGreedy(tolerance=0.02),
    array_type="sparse",
    join_type="left",
)
```

In 0.33.1, `Scores.calculate` selects its coordinate-only `sparse_array` path
only with an existing score layer, `join_type="left"` or `"inner"`, and **fewer
than half** of all coordinates retained. Otherwise it computes the full matrix
then joins; setting `array_type="sparse"` alone does not change this. A 1-by-1
input always uses `pair()`, even after a rejecting gate. Stop explicitly when
no candidate coordinates remain. Confirm score names and coordinate counts
after each stage. An overly narrow precursor gate removes analogs or different
adducts; this example is for identity-oriented candidate search.

The `Pipeline` class formalizes the same pattern and can persist a YAML
workflow. See `workflows.md`.

## Filtering and Exporting Scores

```python
print(scores.score_names)

scores.filter_by_range(
    name="ModifiedCosineGreedy_score",
    low=0.6,
    above_operator=">=",
)

dense = scores.to_array("ModifiedCosineGreedy_score")
coo = scores.to_coo("ModifiedCosineGreedy_score")
scores.to_json("scores.json")
```

`filter_by_range()` mutates the stored score coordinates. Preserve an unfiltered
copy or serialize first when alternative thresholds must be compared.

Dense arrays require memory proportional to
`n_references * n_queries`. A sparse container is most useful only when a mask
or score threshold leaves relatively few stored pairs.

## Combining Metrics

Do not directly index `scores.scores[j, i]` and assume a scalar. Extract named
layers:

```python
cosine = scores.to_array("CosineGreedy_score")
matches = scores.to_array("CosineGreedy_matches")
```

If combining metrics:

- define whether missing/filtered pairs are zero, missing, or excluded;
- normalize only when score semantics justify it;
- fit or justify weights on an appropriate validation set;
- avoid leaking query identities into tuning;
- retain each component score in the output; and
- report the exact formula and package version.

## Interpretation Checklist

- Was identical preprocessing applied to references and queries?
- Is the tolerance appropriate for the instrument and calibration?
- Are precursor m/z, charge, ion mode, and adduct metadata valid?
- How many peaks matched, and what fraction of each spectrum do they represent?
- Is the hit driven by one dominant/common fragment?
- Are collision energy and acquisition conditions comparable?
- Is the query actually present in the searched library?
- Was the threshold validated on representative positives and negatives?
- Has the top hit been inspected with a mirror plot?

A high score ranks a candidate under a chosen metric. It does not, by itself,
establish compound identity.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated 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