matchms

Matchms

目的と対象範囲

Matchms は、タンデム質量スペクトルのインポート、クリーニング、処理、比較を行うための Python パッケージです。このスキルは、2026-06-08 にリリースされた matchms 0.33.1 を対象としており、古いチュートリアルに反映されていない、いくつかの破壊的な API 変更に対応しています。

Matchms は、次の用途に使用します。

• MS/MS ライブラリ検索とクエリ対リファレンスのスコアリング
• メタデータの統一、付加体／プリカーサーの処理、ピークのフィルタリング
• コサイン、修正版コサイン、ニュートラルロス、近似、エントロピーのスコアリング
• 構造化スコア行列、上位ヒットの抽出、スペクトルネットワーク
• MGF、MSP、mzML、mzXML、JSON、mzSpecLib、metabolomics-USI のワークフロー

Matchms は、次の用途の代替として使用しないでください。

• LC-MS の特徴量検出、クロマトグラフィーのアラインメント、ペプチド同定、タンパク質定量 — pyopenms を使用してください
• ベンダーの RAW ファイル変換 — まず mzML／mzXML に変換してください
• 検証済みの化合物同定プロトコル — 類似性は根拠の一つであり、同一性の証明ではありません

検証済みリリースのインストール

環境を作成または有効化してから、このスキルで使用するリリースをインストールします。

uv pip install "matchms==0.33.1"

ランタイムを確認します。

uv run python -c "import matchms; print(matchms.__version__)"

Matchms 0.33.1 は Python 3.10-3.14 をサポートしており、RDKit を通常の依存関係としてインストールします。従来の matchms[chemistry] エクストラは、現在のパッケージメタデータには含まれていません。

運用ワークフロー

1. 入力を確認します。 形式、スペクトル数、MS レベル、プリカーサーの網羅状況、イオンモード、ピーク数、識別子フィールドを記録します。
2. ソースのキーを保持することが明確な要件でない限り、メタデータの統一を有効にして読み込みます。
3. クエリスペクトルとリファレンススペクトルに、同じピーク処理を適用します。リファレンスの注釈がより充実している場合は、メタデータの補完を別に行います。
4. 無効なスペクトルを明示的に除外します。 多くの require_* フィルターは None を返します。
5. 利便性ではなく、科学的な問いに基づいてスコアを選びます。修正版スコアとニュートラルロススコアには、有効な precursor_mz が必要です。
6. スコアリング前に len(references) * len(queries) を見積もります。スパース結果コンテナーを使用しても、要求されたすべてのペアの計算が自動的に回避されるわけではありません。
7. スコア設定と根拠を報告します。 許容誤差、前処理、スコア名、取得可能な場合は一致したピーク数、候補のメタデータを記載します。
8. 上位ヒットを視覚的かつ化学的に検証します。 ミラープロット、プリカーサーの一致、イオン／付加体との適合性、独立した根拠を使用します。

現行 API の注意事項

以下は、0.33 より前の例でよく発生する失敗を防ぐための事項です。

• ModifiedCosineGreedy または ModifiedCosineHungarian を使用します。ModifiedCosine は 0.32.0 で削除されました。
• add_losses() を呼び出さないでください。これは 0.27.0 で削除されました。代わりに spectrum.losses、spectrum.compute_losses(...)、または NeutralLossesCosine を直接使用します。
• SpectrumProcessor は呼び出し可能ではありません。process_spectrum() または process_spectra() を使用します。
• process_spectra() は (processed_spectra, processing_report) を返します。
• Scores.scores は StackedSparseArray で、多くの場合、CosineGreedy_score や CosineGreedy_matches などの個別の構造化フィールドを持ちます。
• scores_by_query() は、リファレンスのインデックスではなく、(reference_spectrum, score_record) のペアを返します。
• パラメーター名には spectra を優先して使用します。旧式の表記 spectrums は非推奨です。
• 信頼できないソースの pickle ファイルは読み込まないでください。アンピックリングによってコードが実行される可能性があります。

旧 API から現行 API への完全な対応表は references/migration.md を参照してください。

クイックスタート：ライブラリのクリーニングと検索

from matchms import SpectrumProcessor, calculate_scores
from matchms.filtering import (
    default_filters,
    normalize_intensities,
    require_minimum_number_of_peaks,
    select_by_relative_intensity,
)
from matchms.importing import load_spectra
from matchms.similarity import ModifiedCosineGreedy


def load_and_process(path):
    spectra = [default_filters(spectrum) for spectrum in load_spectra(path)]
    processor = SpectrumProcessor(
        [
            normalize_intensities,
            (select_by_relative_intensity, {"intensity_from": 0.01}),
            (require_minimum_number_of_peaks, {"n_required": 5}),
        ]
    )
    processed, _ = processor.process_spectra(
        spectra,
        progress_bar=False,
        create_report=False,
    )
    return processed


references = load_and_process("library.msp")
queries = load_and_process("queries.mgf")

metric = ModifiedCosineGreedy(tolerance=0.02)
scores = calculate_scores(
    references=references,
    queries=queries,
    similarity_function=metric,
)

score_name = "ModifiedCosineGreedy_score"
matches_name = "ModifiedCosineGreedy_matches"
for query in queries:
    ranked = scores.scores_by_query(query, name=score_name, sort=True)
    for reference, values in ranked[:5]:
        print(
            query.get("spectrum_id", query.get("id")),
            reference.get("compound_name", reference.get("spectrum_id")),
            float(values[score_name]),
            int(values[matches_name]),
        )

SpectrumProcessor は、Matchms のフィルター順序に従って、組み込みフィルターを自動的に並べ替えます。集約された default_filters 呼び出し可能オブジェクトはそのレジストリーに含まれないため、上記のように先に実行するか、9 個の構成フィルターに展開してください。processor.processing_steps を確認し、結果とともに保持してください。

ペアスコアリング

類似度クラスでは、参照スペクトルとクエリスペクトルの1ペアに対してpair()を使用できます。コサイン系の結果は、構造化されたNumPyスカラーです。

from matchms.similarity import CosineGreedy

result = CosineGreedy(tolerance=0.02).pair(reference, query)
similarity = float(result["score"])
matched_peaks = int(result["matches"])

FlashSimilarityなどの行列指向のメソッドには、calculate_scores()を使用してください。単一ペアの処理もサポートされていますが、最適化された処理経路ではありません。

類似度メソッドを選ぶ

• CosineGreedy — 標準的なピークコサイン類似度で、ピークを貪欲に割り当てます。
• CosineHungarian — 厳密な割り当てを行います。処理は遅くなりますが、ベンチマークに役立ちます。
• CosineLinear — 現在の線形スケーリング型コサイン類似度の実装です。
• ModifiedCosineGreedy — プリカーサー差分でシフトしたマッチを許容します。アナログ検索でよく使われます。
• ModifiedCosineHungarian — 厳密な修正コサイン類似度の割り当てを行います。
• NeutralLossesCosine — プリカーサーとフラグメントから算出した損失を比較します。
• BlinkCosine — 大きな行列向けの高速なBLINKスタイルのコサイン類似度近似です。
• FlashSimilarity — フラグメント、ニュートラルロス、またはハイブリッドのマッチングを用いて、スペクトルエントロピーまたはコサイン類似度で最適化された行列スコアリングを行います。
• BinnedEmbeddingSimilarity — ビン分割されたスペクトルベクトルと、オプションの近似最近傍インデックスを使用します。
• PrecursorMzMatch、ParentMassMatch、MetadataMatch — 候補のマスクまたはメタデータ制約であり、詳細なスペクトルスコアではありません。
• FingerprintSimilarity — 分子構造の類似度です。スペクトル類似度ではなく、有効な構造から準備したフィンガープリントが必要です。

高速なメソッドの選択、スコアの組み合わせ、または構造化出力の解釈を行う前に、references/similarity.mdをお読みください。

大規模な比較

1つのコレクション内の全ペアをスコアリングするには、is_symmetric=Trueを設定します。

scores = calculate_scores(
    references=spectra,
    queries=spectra,
    similarity_function=CosineGreedy(tolerance=0.02),
    array_type="sparse",
    is_symmetric=True,
)

プリカーサーで候補を絞り込む検索では、まずPrecursorMzMatchを計算してフィルタリングし、その後、PipelineまたはScores.calculate(...)を通じて、残った座標のみでスペクトル指標を計算してください。references/workflows.mdを参照してください。

あらゆる状況に適用できる「同定しきい値」を選ばないでください。スコアの分布は、前処理、質量精度、衝突条件、ライブラリの品質、指標に左右されます。最低限、コサイン系メソッドではスコアとマッチしたピーク数の両方を保持してください。

同梱のライブラリ検索CLI

scripts/library_search.pyは、最新のスコア抽出、ペア数の上限、前処理、CSV出力を備えた、再現可能なクエリ対ライブラリ検索を提供します。

uv run python scripts/library_search.py \
  queries.mgf library.msp hits.csv \
  --metric modified \
  --tolerance 0.02 \
  --top-k 10 \
  --min-score 0.6 \
  --min-matches 5

--helpを実行すると、高速な指標、前処理オプション、識別子フィールド、上書き制御、明示的な大規模行列のオーバーライドを確認できます。

スペクトルオブジェクトと可視化

import numpy as np
from matchms import Spectrum

spectrum = Spectrum(
    mz=np.array([100.0, 150.0, 200.0]),
    intensities=np.array([0.2, 1.0, 0.4]),
    metadata={"spectrum_id": "query-1", "precursor_mz": 250.5},
)

print(spectrum.peaks.mz)
print(spectrum.get("precursor_mz"))
losses = spectrum.compute_losses(loss_mz_from=5.0, loss_mz_to=200.0)
spectrum.plot()
spectrum.plot_against(reference_spectrum)

リファレンス

タスクに必要なリファレンスのみをお読みください。

• references/importing_exporting.md — フォーマット、戻り値の型、汎用I/O、mzSpecLib、スコアのシリアライズ、pickleの安全性
• references/filtering.md — 現在のフィルター一覧、clone／Noneのセマンティクス、デフォルトフィルター、順序、SpectrumProcessor
• references/similarity.md — 現在のすべての類似度クラス、出力、候補のマスキング、パフォーマンス、解釈
• references/workflows.md — ライブラリ検索、スパースな絞り込み、Pipeline、ネットワーク、プロット、プロベナンス
• references/migration.md — 破壊的変更と非推奨のAPI
• references/sources.md — この更新で参照した信頼できるドキュメント、リリースノート、ユーザーガイド、科学論文

必ず守る確認事項

• 生のクエリを、異なる方法で処理した参照スペクトルと比較しないでください。
• 有効なプリカーサーメタデータなしに、修正コサインスコアまたはニュートラルロススコアを使用しないでください。
• Scoresの値が単なる浮動小数点数だと仮定せず、score_namesを確認してください。
• 類似度スコアが高いというだけで、同定が確定したと判断しないでください。
• 信頼できないpickleデータをデシリアライズしないでください。
• ペア数を見積もらずに、上限のない全ペア比較を開始しないでください。

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を確定します。 データまたはユーザーに確認し、形式、識別子、パラメーターを確定します。結果に影響する値を推測するのではなく、質問してください。
3. まず小規模に実行します。 最初に少数のサブセット（サンプル1件、染色体1本、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの識別情報、ゲノムビルドの一貫性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

次のことが起きた場合	対応
入力間でゲノムビルドまたは識別子が一致しない	いったん停止し、続行前に調整します（liftover、ID マッピング）。
インストールされているバージョンに、これらの手順に記載された関数、フラグ、エンドポイントがない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

完全性に関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できないことがあれば、率直に伝えます。
• 統計的な裏付けを超えて生物学的な意義を解釈してはいけません。多重検定補正について報告します。
• ここに記載されているバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する操作、共有 GPU またはクラウドのクォータを消費する操作、個人データまたは患者データに触れる操作、取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• pyopenms：質量分析の完全な解析プラットフォームです。
• qdrant-vector-search：RAG とセマンティック検索に対応した、高性能なベクトル類似性検索エンジンです。
• faiss：高密度ベクトルの効率的な類似性検索とクラスタリングを実現する、Facebook のライブラリです。