pyopenms

PyOpenMS

概要

PyOpenMS は、計算質量分析向けの OpenMS ライブラリに Python バインディングを提供し、プロテオミクスおよびメタボロミクスのデータ解析を可能にします。MS ファイル形式の読み書き、未加工スペクトルの処理、特徴量の検出と定量、ペプチドおよびタンパク質の同定、LC-MS/MS のエンドツーエンドのパイプライン実行に使用できます。

このスキルには、最も一般的な高レベルのワークフローを網羅する、すぐに実行できるスクリプトが scripts/ に含まれています。 新しいコードを書くよりも、スクリプトの実行を優先してください。各スクリプトは、読み込み、処理、エクスポートを行うパラメーター指定可能な CLI ツールです。適合するスクリプトがない場合にのみ、Python API と references/ を使用してください。

インストール

uv pip install pyopenms

確認（注：__version__ は動作しますが、インポート時にバンドルされたバイナリが1行のメモリ状態通知を出力します。これは問題ありません）：

import pyopenms as ms
print(ms.__version__)  # 3.5.0

スクリプト（まずはこちら）

すべてのオプションを確認するには、python scripts/<name>.py --help を実行してください。すべてのスクリプトが標準的な MS ファイル形式を受け入れ、適宜 featureXML／consensusXML／CSV／mzTab／PNG に書き出します。

検査と変換

スクリプト	機能
inspect_ms_data.py	mzML／mzXML／featureXML／consensusXML／idXML の概要（件数、RT／m/z 範囲、TIC、メタデータ）を表示します。スペクトルごとの CSV も任意で出力できます。
convert_format.py	MS レベル、RT、強度による任意のフィルタリングを指定して、mzML／mzXML／MGF 間で変換します。
process_spectra.py	設定可能な信号処理チェーン：平滑化（Gauss／SGolay）、重心化（PeakPickerHiRes）、正規化、S/N および強度のしきい値処理。

特徴量の検出と定量

スクリプト	機能
detect_features_metabo.py	非標的メタボロミクスの特徴量検出：MassTraceDetection → ElutionPeakDetection → FeatureFindingMetabo。
detect_features_centroided.py	FeatureFinderAlgorithmPicked による、ペプチド／重心化データの特徴量検出。
align_link_quantify.py	複数サンプルのパイプライン：特徴量を検出（または読み込み）→ RT アラインメント → コンセンサスリンク → 定量マトリックス CSV。
consensus_to_matrix.py	consensusXML を、メタデータ付きのワイド形式強度マトリックスに変換します。中央値／分位点による正規化とロング形式も任意で指定できます。

アノテーション

スクリプト	機能
detect_adducts.py	同じ中性質量を持つ付加イオン／電荷バリアントをグループ化します（MetaboliteFeatureDeconvolution）。
accurate_mass_search.py	精密質量に基づいて HMDB と特徴量を照合し、アノテーションを付与します（AccurateMassSearchEngine → mzTab／CSV）。
export_gnps_sirius.py	GNPS FBMN の入力データ（MGF + 定量テーブル）または SIRIUS .ms ファイルをエクスポートします。

同定

スクリプト	機能
process_identifications.py	FASTA に対して再インデックス化し、FDR／q 値を推定し、フィルタリング（FDR／長さ／スペクトルごとの最良候補）を行って、idXML + CSV にエクスポートします。

化学

スクリプト	機能
mass_calculator.py	ペプチドまたは経験式の単同位体質量／平均質量、荷電 m/z、分子式、同位体パターンを計算します。
digest_protein.py	FASTA／配列を酵素切断して、質量と m/z を持つ理論ペプチドを生成します。
theoretical_spectrum.py	ペプチドの注釈付き理論フラグメントスペクトル（b／y／a／c／x／z、損失）を生成します。

標的解析と可視化

スクリプト	機能
extract_chromatograms.py	標的 m/z の TIC／BPC および XIC トレースを作成します（CSV + 任意のプロット）。
plot_ms_data.py	簡易プロット：単一スペクトル、TIC、2D 特徴量マップ、MS1 信号マップ。

よく使うスクリプトのレシピ

# Inspect a file
python scripts/inspect_ms_data.py sample.mzML --spectra-csv spectra.csv

# Untargeted metabolomics: features for one sample
python scripts/detect_features_metabo.py sample.mzML --out-csv features.csv

# Full multi-sample quantification study
python scripts/align_link_quantify.py s1.mzML s2.mzML s3.mzML --out-prefix study
python scripts/consensus_to_matrix.py study.consensusXML --out quant.csv --normalize median

# Peptide chemistry
python scripts/mass_calculator.py --peptide "PEPTIDEM(Oxidation)K" --charges 1 2 3 --isotopes 5
python scripts/digest_protein.py proteins.fasta --enzyme Trypsin --missed 2 --out peptides.csv

# Identification post-processing
python scripts/process_identifications.py search.idXML --fasta db.fasta --fdr 0.01 --out filtered.idXML --csv hits.csv

重要な 3.5.0 API に関する注意事項

以下は以前の OpenMS リリースから変更されています。以前のチュートリアルやコードは動作しなくなります。

• フィーチャー検出：FeatureFinder("centroided") は削除されました。FeatureFinderAlgorithmPicked（プロテオミクス／セントロイドデータ）または MassTraceDetection → ElutionPeakDetection → FeatureFindingMetabo パイプライン（メタボロミクス）を使用してください。detect_features_*.py を参照してください。
• idXML の入出力：IdXMLFile().load/store でペプチド ID を扱うには、ms.PeptideIdentificationList() が必要です（通常の Python list を渡すと「can not handle type」エラーが発生します）。タンパク質 ID は引き続き通常のリストを使用します。
• 付加体の脱荷電：クラス名は MetaboliteFeatureDeconvolution で、付加体には Elements:Charge:Probability 構文（例：H:+:0.4、H-2O-1:0:0.05）を使用します。[M+H]+ のような角括弧表記ではありません。
• DataFrame の列：FeatureMap.get_df() では小文字の rt／mz が使われます（RT ではありません）。ConsensusMap は get_intensity_df() と get_metadata_df() を提供します。
• 同梱データに関する注意：pip ホイールには HMDBMappingFile.tsv は含まれていますが、HMDB2StructMapping.tsv は含まれていません。accurate_mass_search.py はこれを検出し、ファイルの指定方法を説明します。

コアデータ構造

• MSExperiment – スペクトルとクロマトグラムのコレクション
• MSSpectrum / MSChromatogram – 単一のスペクトル／クロマトグラムのトレース
• Feature / FeatureMap – 検出された LC-MS ピーク／フィーチャーのコレクション
• ConsensusMap – サンプル間でリンクされたフィーチャー（定量テーブル）
• PeptideIdentification / ProteinIdentification – 検索結果
• AASequence / EmpiricalFormula – 配列と化学式

詳細：references/data_structures.md を参照してください。

パラメーター管理

ほとんどのアルゴリズムは OpenMS の Param オブジェクトを公開しています。

algo = ms.FeatureFindingMetabo()
p = algo.getDefaults()
for key in p.keys():
    print(key.decode(), "=", p.getValue(key), "|", p.getDescription(key))
p.setValue("charge_lower_bound", 1)
algo.setParameters(p)

pandas へのエクスポート

fm = ms.FeatureMap(); ms.FeatureXMLFile().load("features.featureXML", fm)
df = fm.get_df()             # columns include lowercase rt, mz, intensity, charge, quality

cm = ms.ConsensusMap(); ms.ConsensusXMLFile().load("study.consensusXML", cm)
intensities = cm.get_intensity_df()   # features x samples
metadata = cm.get_metadata_df()       # rt, mz, charge, quality, ...

他のツールとの統合

Pandas（DataFrame）、NumPy（ピーク配列）、scikit-learn（ML）、Matplotlib/Seaborn（プロット）、およびエクスポートによる下流ツールとの連携：GNPS（FBMN）、SIRIUS、mzTab。

リソース

• 公式ドキュメント（3.5.0）：https://pyopenms.readthedocs.io/en/release-3.5.0/
• OpenMS：https://www.openms.org
• GitHub：https://github.com/OpenMS/OpenMS

参考資料

• references/file_io.md – ファイル形式の処理
• references/signal_processing.md – シグナル処理アルゴリズム
• references/feature_detection.md – フィーチャーの検出とリンク
• references/identification.md – ペプチドおよびタンパク質の同定
• references/metabolomics.md – メタボロミクス固有のワークフロー
• references/data_structures.md – コアオブジェクトとデータ構造

エージェントの作業手順

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

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

整合性に関するルール

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

関連スキル

• matchms：matchms でタンデム質量スペクトルを処理、クリーニング、比較、検索します。