alterlab-pyopenms

PyOpenMS

概要

PyOpenMS は、計算質量分析用の OpenMS ライブラリに対する Python バインディングを提供し、プロテオミクスおよびメタボロミクスデータの解析を可能にします。質量分析ファイル形式の処理、スペクトルデータの加工、特徴量の検出、ペプチド／タンパク質の同定、定量解析に使用します。

インストール

uv を使ってインストールします（pyOpenMS 3.x — 以下の例は 3.5 で検証済みです）。

uv pip install "pyopenms>=3.4"

インストールを確認します。

import pyopenms
print(pyopenms.__version__)

バージョンに関する注意：pyOpenMS 3.x では旧式の FeatureFinder ファサードが削除されました。 FeatureFinderAlgorithmPicked（旧 "centroided" アルゴリズム）を使用するか、 メタボロミクスの場合は MassTraceDetection → ElutionPeakDetection → FeatureFindingMetabo のチェーンを使用してください。references/feature_detection.md を参照してください。

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

ユーザーが次のことを希望する場合に、このスキルを使用します。

• MS ファイル形式（mzML、mzXML、idXML、featureXML、consensusXML、mzTab）を読み取る、変換する、または調べる。
• 生スペクトルを処理する（平滑化、ベースライン除去、セントロイディング／ピークピッキング、正規化）。
• LC-MS ランで特徴量検出とラベルフリー定量を実行する。
• ペプチド／タンパク質の同定と FDR 制御（検索エンジンアダプター、PeptideIndexer、 FalseDiscoveryRate）を行う、または完全な LC-MS/MS パイプラインを構築する。
• ノンターゲットメタボロミクスの特徴量検出（MassTraceDetection -> ElutionPeakDetection -> FeatureFindingMetabo）と付加イオン／分子式の解析を行う。
• TOPP のコマンドラインではなく、Param オブジェクトを使って OpenMS アルゴリズムをプログラムから実行する。

対象外

シナリオ	代わりに使用
小分子の MS/MS のスペクトル類似度スコアリング／ライブラリ照合	alterlab-matchms
同定済み分子のケモインフォマティクス（記述子、部分構造、SMILES）	alterlab-rdkit
定量済みの存在量マトリックスの統計解析（検定、PCA、クラスタリング）	alterlab-statistical-analysis
質量スペクトルではなくタンパク質配列／構造を扱う作業	alterlab-biopython または alterlab-alphafold
RNA-seq リードからの転写産物定量	alterlab-rnaseq-quant

主な機能

PyOpenMS の機能は、次の領域に分類されています。

1. ファイル I/O とデータ形式

質量分析ファイル形式を処理し、異なる表現形式間で変換します。

対応形式：mzML、mzXML、TraML、mzTab、FASTA、pepXML、protXML、mzIdentML、featureXML、consensusXML、idXML

基本的なファイル読み込み：

import pyopenms as ms

# Read mzML file
exp = ms.MSExperiment()
ms.MzMLFile().load("data.mzML", exp)

# Access spectra
for spectrum in exp:
    mz, intensity = spectrum.get_peaks()
    print(f"Spectrum: {len(mz)} peaks")

詳細なファイル処理について：references/file_io.md を参照してください。

2. 信号処理

平滑化、フィルタリング、セントロイディング、正規化によって生スペクトルデータを処理します。

基本的なスペクトル処理：

# Smooth spectrum with Gaussian filter
gaussian = ms.GaussFilter()
params = gaussian.getParameters()
params.setValue("gaussian_width", 0.1)
gaussian.setParameters(params)
gaussian.filterExperiment(exp)

アルゴリズムの詳細について：references/signal_processing.md を参照してください。

3. 特徴量検出

定量解析のために、スペクトルやサンプル全体にわたって特徴量を検出し、対応付けます。

# Detect features in centroided data (pyOpenMS 3.x API)
ff = ms.FeatureFinderAlgorithmPicked()
params = ff.getParameters()          # defaults for the "centroided" algorithm
ff.setParameters(params)

features = ms.FeatureMap()
seeds = ms.FeatureMap()              # empty seeds = detect de novo
ff.run(exp, features, params, seeds)

ワークフロー全体について：references/feature_detection.md を参照してください。

4. ペプチドおよびタンパク質の同定

検索エンジンと連携し、同定結果を処理します。

対応エンジン：Comet、Mascot、MSGFPlus、XTandem、OMSSA、Myrimatch

基本的な同定ワークフロー：

# Load identification data.
# pyOpenMS 3.x: protein_ids is a plain list, peptide_ids MUST be a
# PeptideIdentificationList (a plain [] is rejected by load()).
protein_ids = []
peptide_ids = ms.PeptideIdentificationList()
ms.IdXMLFile().load("identifications.idXML", protein_ids, peptide_ids)

# Compute q-values (target-decoy FDR), then filter at 1%.
# fdr.apply() requires target/decoy hits annotated with a 'target_decoy'
# meta value (run PeptideIndexer on a concatenated target-decoy search first).
fdr = ms.FalseDiscoveryRate()
fdr.apply(peptide_ids)               # rewrites scores to q-values (lower = better)
ms.IDFilter().filterHitsByScore(peptide_ids, 0.01)
ms.IDFilter().removeEmptyIdentifications(peptide_ids)

詳細なワークフローについて：references/identification.md を参照してください。

5. メタボロミクス解析

ノンターゲットメタボロミクスの前処理と解析を行います。

一般的なワークフロー：

1. 生データを読み込み、処理する
2. 特徴量を検出する
3. サンプル間の保持時間をアラインメントする
4. 特徴量をコンセンサスマップに対応付ける
5. 化合物データベースを使ってアノテーションする

メタボロミクスのワークフロー全体について：references/metabolomics.md を参照してください。

データ構造

PyOpenMS では、次の主要なオブジェクトを使用します。

• MSExperiment：スペクトルとクロマトグラムのコレクション
• MSSpectrum：m/z と強度のペアで構成される単一の質量スペクトル
• MSChromatogram：クロマトグラフィーのトレース
• Feature：品質指標を備えた検出済みクロマトグラフィーピーク
• FeatureMap：フィーチャーのコレクション
• PeptideIdentification：ペプチドの検索結果
• ProteinIdentification：タンパク質の検索結果

詳細なドキュメント：references/data_structures.md を参照してください。

一般的なワークフロー

クイックスタート：データの読み込みと確認

import pyopenms as ms

# Load mzML file
exp = ms.MSExperiment()
ms.MzMLFile().load("sample.mzML", exp)

# Get basic statistics
print(f"Number of spectra: {exp.getNrSpectra()}")
print(f"Number of chromatograms: {exp.getNrChromatograms()}")

# Examine first spectrum
spec = exp.getSpectrum(0)
print(f"MS level: {spec.getMSLevel()}")
print(f"Retention time: {spec.getRT()}")
mz, intensity = spec.get_peaks()
print(f"Peaks: {len(mz)}")

パラメーター管理

ほとんどのアルゴリズムでは、パラメーターシステムを使用します。

# Get algorithm parameters
algo = ms.GaussFilter()
params = algo.getParameters()

# View available parameters
for param in params.keys():
    print(f"{param}: {params.getValue(param)}")

# Modify parameters
params.setValue("gaussian_width", 0.2)
algo.setParameters(params)

Pandas へのエクスポート

分析用にデータを pandas DataFrame に変換します。

import pyopenms as ms
import pandas as pd

# Load feature map
fm = ms.FeatureMap()
ms.FeatureXMLFile().load("features.featureXML", fm)

# Convert to DataFrame
df = fm.get_df()
print(df.head())

他のツールとの連携

PyOpenMS は次のツールと連携できます。

• Pandas：データを DataFrame にエクスポート
• NumPy：ピーク配列を処理
• Scikit-learn：MS データを用いた機械学習
• Matplotlib/Seaborn：可視化
• R：rpy2 ブリッジ経由

リソース

• 公式ドキュメント：https://pyopenms.readthedocs.io
• 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 - コアオブジェクトとデータ構造