PyOpenMS

PyOpenMS

概述

PyOpenMS 为 OpenMS 库提供 Python 绑定，用于计算质谱分析，支持蛋白质组学和代谢组学数据的分析。可用它读写质谱文件格式、处理原始谱图、检测并定量特征、鉴定肽段和蛋白质，以及运行端到端的 LC-MS/MS 流程。

本技能在 `scripts/` 目录中提供了开箱即用的脚本，涵盖最常见的高层工作流。优先运行脚本，而不是自己编写新代码——每个脚本都是一个带参数的命令行工具，负责加载、处理和导出。只有在没有合适脚本时，才直接使用 Python API（并参考 references/）。

安装

uv pip install pyopenms

验证安装（注意：__version__ 可正常使用，但内置二进制文件在导入时会打印一行内存状态提示，这是无害的）：

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

脚本（从这里开始）

使用 python scripts/<name>.py --help 查看完整选项。所有脚本都接受标准的质谱文件格式，并按需写出 featureXML/consensusXML/CSV/mzTab/PNG。

检查与转换

| 脚本 | 作用 |

|--------|--------------|

| inspect_ms_data.py | 汇总任意 mzML/mzXML/featureXML/consensusXML/idXML 文件（计数、RT/m/z 范围、TIC、元数据）；可选逐谱图 CSV 输出。 |

| convert_format.py | 在 mzML/mzXML/MGF 之间转换，可选按 MS 级别、RT、强度进行过滤。 |

| process_spectra.py | 可配置的信号处理链：平滑（Gauss/SGolay）、质心化（PeakPickerHiRes）、归一化、信噪比与强度阈值。 |

特征检测与定量

| 脚本 | 作用 |

|--------|--------------|

| 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、二维特征图、MS1 信号图。 |

常用脚本示例

# 检查文件
python scripts/inspect_ms_data.py sample.mzML --spectra-csv spectra.csv

# 非靶向代谢组学：单个样本的特征
python scripts/detect_features_metabo.py sample.mzML --out-csv features.csv

# 完整的多样本定量研究
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

# 肽段化学计算
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

# 鉴定结果后处理
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 仍然使用普通 list。

• 加合物去电荷：对应的类是 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 wheel 包中附带了 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()             # 列名包括小写的 rt、mz、intensity、charge、quality

cm = ms.ConsensusMap(); ms.ConsensusXMLFile().load("study.consensusXML", cm)
intensities = cm.get_intensity_df()   # 特征 x 样本
metadata = cm.get_metadata_df()       # rt、mz、charge、quality 等

与其他工具的集成

Pandas（DataFrame）、NumPy（峰值数组）、scikit-learn（机器学习）、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 – 核心对象与数据结构