alterlab-matchms

Matchms

概要

Matchms は、質量分析データの処理と解析を行うオープンソースの Python ライブラリです。さまざまな形式からスペクトルをインポートし、メタデータを標準化し、ピークをフィルタリングし、スペクトル類似度を計算して、再現可能な分析ワークフローを構築できます。

このスキルを使用する場面

次のような場合にこのスキルを使用してください。

• MS/MS スペクトル（MGF、MSP、mzML、mzXML、JSON、USI）とそのメタデータの読み込み、クリーニング、統一
• クエリと参照ライブラリ間のスペクトル類似度（cosine、modified cosine、neutral-loss cosine）のスコアリング
• ライブラリとの照合による未知代謝物のアノテーション、またはスペクトルメタデータからの InChI／InChIKey／フィンガープリントの導出
• メタボロミクスのスペクトル向けの再現可能な前処理パイプライン（SpectrumProcessor）の構築

該当しない場合

シナリオ	代わりに使用
LC-MS/MS プロテオミクスや特徴量検出の包括的なパイプライン（ペプチド ID、定量、raw ファイル処理）	alterlab-pyopenms
HMDB で代謝物の参照レコード、経路、公開済みスペクトルを検索する	alterlab-hmdb
Metabolomics Workbench の研究、RefMet 名、m/z 質量検索を照会する	alterlab-metabolomics-wb
アノテーション済み化合物の構造レベルのケモインフォマティクス（部分構造、記述子）	alterlab-rdkit

主な機能

1. 質量分析データのインポートとエクスポート

複数のファイル形式からスペクトルを読み込み、処理済みデータをエクスポートします。

from matchms.importing import load_from_mgf, load_from_mzml, load_from_msp, load_from_json
from matchms.exporting import save_as_mgf, save_as_msp, save_as_json

# Import spectra
spectra = list(load_from_mgf("spectra.mgf"))
spectra = list(load_from_mzml("data.mzML"))
spectra = list(load_from_msp("library.msp"))

# Export processed spectra
save_as_mgf(spectra, "output.mgf")
save_as_json(spectra, "output.json")

対応形式：

• mzML および mzXML（質量分析の生データ形式）
• MGF（Mascot Generic Format）
• MSP（スペクトルライブラリ形式）
• JSON（GNPS 対応）
• metabolomics-USI 参照
• Pickle（Python シリアライゼーション）

インポート／エクスポートの詳細なドキュメントについては、references/importing_exporting.md を参照してください。

2. スペクトルのフィルタリングと処理

包括的なフィルターを適用して、メタデータを標準化し、ピークデータを精選します。

from matchms.filtering import default_filters, normalize_intensities
from matchms.filtering import select_by_relative_intensity, require_minimum_number_of_peaks

# Apply default metadata harmonization filters
spectrum = default_filters(spectrum)

# Normalize peak intensities
spectrum = normalize_intensities(spectrum)

# Filter peaks by relative intensity
spectrum = select_by_relative_intensity(spectrum, intensity_from=0.01, intensity_to=1.0)

# Require minimum peaks
spectrum = require_minimum_number_of_peaks(spectrum, n_required=5)

フィルターのカテゴリ：

• メタデータ処理：化合物名の統一、化学構造の導出、付加体の標準化、電荷の補正
• ピークのフィルタリング：強度の正規化、m/z または強度による選択、プリカーサーピークの除去
• 品質管理：最小ピーク数の指定、プリカーサー m/z の検証、メタデータの完全性の確認
• 化学アノテーション：フィンガープリントの追加、InChI／SMILES の導出、構造の不一致の修復

Matchms には 40 種類以上のフィルターが用意されています。すべてのフィルターについては、references/filtering.md を参照してください。

3. スペクトル類似度の計算

さまざまな類似度指標を使用してスペクトルを比較します。

from matchms import calculate_scores
from matchms.similarity import CosineGreedy, ModifiedCosineGreedy, CosineHungarian

# Calculate cosine similarity (fast, greedy algorithm)
scores = calculate_scores(references=library_spectra,
                         queries=query_spectra,
                         similarity_function=CosineGreedy())

# Calculate modified cosine (accounts for precursor m/z differences)
scores = calculate_scores(references=library_spectra,
                         queries=query_spectra,
                         similarity_function=ModifiedCosineGreedy(tolerance=0.1))

# Get best matches. The cosine functions return a structured score
# (score + matched-peak count), so to SORT you must name the field to
# sort by — `sort=True` alone raises IndexError. The field is
# "<FunctionName>_score", e.g. "ModifiedCosineGreedy_score" / "CosineGreedy_score".
best_matches = scores.scores_by_query(query_spectra[0],
                                      name="ModifiedCosineGreedy_score",
                                      sort=True)[:10]

使用可能な類似度関数：

• CosineGreedy/CosineHungarian：異なるマッチングアルゴリズムによるピークベースのコサイン類似度
• ModifiedCosineGreedy（および ModifiedCosineHungarian）：プリカーサー質量の差を考慮したコサイン類似度です。名称が変更されており、このクラスは ModifiedCosine とは呼ばれなくなった点に注意してください。
• NeutralLossesCosine：中性脱離パターンに基づく類似度
• FingerprintSimilarity：フィンガープリントを使用した分子構造の類似度
• MetadataMatch：ユーザー定義のメタデータフィールドの比較
• PrecursorMzMatch/ParentMassMatch：質量に基づくシンプルなフィルタリング

類似度関数の詳細なドキュメントについては、references/similarity.md を参照してください。

4. 処理パイプラインの構築

再現可能な複数ステップの分析ワークフローを作成します。

from matchms import SpectrumProcessor
from matchms.filtering import default_filters, normalize_intensities
from matchms.filtering import select_by_relative_intensity, remove_peaks_around_precursor_mz

# Define a processing pipeline. Each step is a callable, a registered filter
# name (str), or a ("filter_name", {kwargs}) tuple (introspectable via
# processor.processing_steps). NOTE: default_filters is a composite, so pass it
# as the callable — the string "default_filters" is not a registered name.
processor = SpectrumProcessor([
    default_filters,
    "normalize_intensities",
    ("select_by_relative_intensity", {"intensity_from": 0.01}),
    ("remove_peaks_around_precursor_mz", {"mz_tolerance": 17}),
])

# A SpectrumProcessor is NOT callable. Use .process_spectrum() for one
# spectrum, or .process_spectra() for a list (returns a (spectra, report)
# tuple — unpack it, don't treat the result as the spectra list).
processed_spectra, report = processor.process_spectra(spectra)
# single spectrum: processed = processor.process_spectrum(spectrum)

5. Spectrum オブジェクトの操作

コアとなる Spectrum クラスには、質量スペクトルデータが含まれます。

from matchms import Spectrum
import numpy as np

# Create a spectrum
mz = np.array([100.0, 150.0, 200.0, 250.0])
intensities = np.array([0.1, 0.5, 0.9, 0.3])
metadata = {"precursor_mz": 250.5, "ionmode": "positive"}

spectrum = Spectrum(mz=mz, intensities=intensities, metadata=metadata)

# Access spectrum properties
print(spectrum.peaks.mz)           # m/z values
print(spectrum.peaks.intensities)  # Intensity values
print(spectrum.get("precursor_mz")) # Metadata field

# Visualize spectra
spectrum.plot()
spectrum.plot_against(reference_spectrum)

6. メタデータ管理

スペクトルのメタデータを標準化し、統一します。

# Metadata keys are automatically harmonized
spectrum.set("Compound_Name", "caffeine")   # stored under 'compound_name'
print(spectrum.get("compound_name"))        # 'caffeine'
# Setting a variant spelling of a key that already exists (e.g. "Precursor_mz" when
# "precursor_mz" is set) raises ValueError — update it with the canonical key instead.

# Derive chemical information
from matchms.filtering import derive_inchi_from_smiles, derive_inchikey_from_inchi
from matchms.filtering import add_fingerprint

spectrum = derive_inchi_from_smiles(spectrum)
spectrum = derive_inchikey_from_inchi(spectrum)
# fingerprint_type must be one of: "daylight", "morgan1", "morgan2", "morgan3"
# (the digit is the Morgan radius). Plain "morgan" is NOT valid.
spectrum = add_fingerprint(spectrum, fingerprint_type="morgan2", nbits=2048)

一般的なワークフロー

次の内容を含む、一般的な質量分析のワークフローについては、

• スペクトルライブラリの読み込みと前処理
• 未知スペクトルと参照ライブラリの照合
• 品質フィルタリングとデータクリーニング
• 大規模な類似度比較
• ネットワークベースのスペクトルクラスタリング

詳細な例については、references/workflows.md を参照してください。

インストール

uv pip install matchms

分子構造の処理（SMILES／InChI／フィンガープリント）には rdkit が必要です。現行バージョンでは matchms の基本インストールに含まれているため、個別の [chemistry] エクストラはありません。import rdkit が失敗する場合は、明示的に uv pip install rdkit を実行してください。

以下の API に関する注意事項は、matchms 0.33.x で確認済みです。

バージョンに関する注意点（matchms 0.33.x で確認済み）

次の点は混乱を招きやすいため、ここでのコード例では対応済みです。

• SpectrumProcessor のインスタンスは呼び出し可能ではありません。 1 つのスペクトルには processor.process_spectrum(spectrum) を、リストには processor.process_spectra(spectra) を使用してください。後者は リスト単体ではなく、(processed_spectra, report) のタプルを返します。
• scores_by_query(query, sort=True) は、コサイン系のスコアで IndexError を発生させます。 構造化スコアが並べ替え対象のフィールドを判断できるよう、name="<FunctionName>_score"（例： "CosineGreedy_score"）を渡す必要があります。
• scores.scores[i, j] は構造化要素であり、浮動小数点数ではありません。 ..._score と ..._matches の両方のフィールドを持ちます。浮動小数点数のみの行列を取得するには scores.to_array("CosineGreedy_score") を使用してください。to_dataframe／to_list はありません。
• add_fingerprint(fingerprint_type=...) が受け付ける値は "daylight"、 "morgan1"、"morgan2"、"morgan3" のみです（"morgan" と radius= 引数は使用できません）。

リファレンスドキュメント

詳細なリファレンスドキュメントは references/ ディレクトリにあります。

• filtering.md - フィルター関数の説明を含む完全なリファレンス
• similarity.md - すべての類似度指標とその使用場面
• importing_exporting.md - ファイル形式の詳細と I/O 操作
• workflows.md - 一般的な分析パターンと例

matchms の特定の機能に関する詳細情報が必要な場合は、これらのリファレンスを適宜参照してください。

AlterLab Academic Skills スイートの一部です。