pyopenms

PyOpenMS

概述

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

此技能在 scripts/ 中提供了可直接运行的脚本，涵盖最常见的高级工作流。优先运行脚本，而不是编写新代码——每个脚本都是参数化的 CLI 工具，可处理加载、处理和导出。仅当没有合适的脚本时，才使用 Python API（以及 references/）。

安装

uv pip install pyopenms

验证（注意：__version__ 可用，但导入时附带的二进制文件会打印一行内存状态提示，此提示无害）：

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	在 mzML/mzXML/MGF 之间转换，可选按 MS 级别、RT 和强度筛选。
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、二维特征图、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 需要用 ms.PeptideIdentificationList() 存放肽段 ID（普通 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 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()             # 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（机器学习）、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 – 核心对象与数据结构

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本，以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于任何会改变结果的值，不要猜测，应先询问。
3. 先运行小规模版本。 先在小型子集上运行管道（一个样本、一个染色体或几千个细胞）。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并统一（liftOver、ID 映射）后再继续。
这些说明中的函数、标志或端点在已安装版本中不存在	查看已安装版本自带的文档（help()、--help、官方文档），进行调整并告知用户。切勿虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

完整性规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请明确说明。
• 不要解读超出统计结果支持范围的生物学意义；报告多重检验校正情况。
• 此处与版本有关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• matchms：使用 matchms 处理、清理、比较和搜索串联质谱。