matchms

Matchms

概要

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

主な機能

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, ModifiedCosine, 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=ModifiedCosine(tolerance=0.1))

# Get best matches
best_matches = scores.scores_by_query(query_spectra[0], sort=True)[:10]

利用可能な類似度関数:

• CosineGreedy/CosineHungarian: 異なるマッチングアルゴリズムを用いたピークベースのコサイン類似度
• 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
processor = SpectrumProcessor([
    default_filters,
    normalize_intensities,
    lambda s: select_by_relative_intensity(s, intensity_from=0.01),
    lambda s: remove_peaks_around_precursor_mz(s, mz_tolerance=17)
])

# Apply to all spectra
processed_spectra = [processor(s) for s in spectra]

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 is automatically harmonized
spectrum.set("Precursor_mz", 250.5)  # Gets harmonized to lowercase key
print(spectrum.get("precursor_mz"))   # Returns 250.5

# 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)
spectrum = add_fingerprint(spectrum, fingerprint_type="morgan", nbits=2048)

一般的なワークフロー

一般的な質量分析解析ワークフローには、次のようなものがあります。

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

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

インストール

pip install matchms

分子構造の処理（SMILES、InChI）を行う場合:

pip install matchms[chemistry]

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

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

• filtering.md - 説明付きの完全なフィルター関数リファレンス
• similarity.md - すべての類似度指標と、それぞれの使用場面
• importing_exporting.md - ファイル形式の詳細と入出力操作
• workflows.md - 一般的な解析パターンと例

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