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）和加合物/分子式分析。
• 使用 Param 对象以编程方式运行 OpenMS 算法，而非使用 TOPP 命令行。

不适用场景

场景	改用
小分子 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 - 核心对象和数据结构