tooluniverse-metabolomics-analysis

代谢组学分析

全面分析代谢组学数据，涵盖从代谢物鉴定到定量、统计分析、通路解读，以及与其他组学层的整合。

领域推理

代谢组学定量在很大程度上取决于归一化。总离子流（TIC）归一化可校正样本上样量的差异，适用于全局丰度变化；内标归一化在关注特定代谢物浓度的靶向分析中更准确。峰表中的缺失值可能表示信号低于检测限，而非真正不存在；应进行插补或明确处理，而不是将其视为零。未能考虑仪器运行批次之间的批次效应，是产生虚假差异代谢物的常见原因。

查询，不要猜测

• 代谢物身份：使用 Metabolite_search 和 Metabolite_get_info 确认名称、CID 和 HMDB ID；绝不要仅凭 m/z 推断身份。
• 通路归属：查询 KEGG、MetaCyc 或 Reactome 工具；不要凭记忆列出通路。
• 疾病关联：通过 Metabolite_get_diseases 从 CTD 获取；没有数据库证据时，不要推断其临床相关性。
• CV 阈值和 QC 标准：应用此工作流中定义的数值（CV < 30%，空白比值 > 3x）；不要凭猜测更改。

---

何时使用此技能

触发条件：

• 用户拥有代谢组学数据（LC-MS、GC-MS、NMR）
• 关于代谢物丰度或浓度的问题
• 差异代谢物分析请求
• 代谢通路分析
• 将代谢组学与其他组学进行整合
• 代谢生物标志物发现
• 通量平衡分析或代谢建模
• 代谢物与酶的相关性分析

示例问题：

1. “分析这些 LC-MS 代谢组学数据，找出差异代谢物。”
2. “不同条件下，哪些代谢通路发生了失调？”
3. “鉴定用于疾病分类的代谢物生物标志物。”
4. “分析代谢物水平与酶表达之间的相关性。”
5. “对差异代谢物进行通路富集分析。”
6. “将代谢组学与转录组学数据整合。”

---

核心能力

能力	描述
数据导入	LC-MS、GC-MS、NMR、靶向/非靶向平台
代谢物鉴定	与 HMDB、KEGG、PubChem 和谱库进行匹配
质量控制	峰质量、空白扣除、内标归一化
归一化	概率商归一化、总离子流、内标
统计分析	单变量和多变量分析（PCA、PLS-DA、OPLS-DA）
差异分析	识别显著的代谢物变化
通路富集	KEGG、Reactome、BioCyc 代谢通路分析
代谢物-酶整合	与表达数据进行相关性分析
通量分析	代谢通量平衡分析（FBA）
生物标志物发现	多代谢物特征

---

工作流概览

Input: Metabolomics Data (Peak Table or Spectra)
    |
    v
Phase 1: Data Import & Metabolite Identification
    |-- Load peak table or process raw spectra
    |-- Match features to HMDB, KEGG (accurate mass +/- 5 ppm)
    |-- Confidence scoring (Level 1-4)
    |
    v
Phase 2: Quality Control & Filtering
    |-- CV in QC samples (<30%)
    |-- Blank subtraction (sample/blank > 3)
    |-- Remove features with >50% missing
    |
    v
Phase 3: Normalization
    |-- Sample-wise: TIC, PQN, or internal standards
    |-- Transformation: log2, Pareto, or auto-scaling
    |-- Batch effect correction (if multi-batch)
    |
    v
Phase 4: Exploratory Analysis
    |-- PCA for sample clustering
    |-- PLS-DA for supervised separation
    |-- Outlier detection
    |
    v
Phase 5: Differential Analysis
    |-- t-test / ANOVA / Wilcoxon
    |-- Fold change + FDR correction
    |-- Volcano plots, heatmaps
    |
    v
Phase 6: Pathway Analysis
    |-- Metabolite set enrichment (MSEA)
    |-- KEGG/Reactome pathway mapping
    |-- Pathway topology (hub/bottleneck metabolites)
    |
    v
Phase 7: Multi-Omics Integration
    |-- Metabolite-enzyme Spearman correlation
    |-- Pathway-level concordance scoring
    |-- Metabolic flux inference
    |
    v
Phase 8: Generate Report
    |-- Summary statistics, differential metabolites
    |-- Pathway diagrams, biomarker panel

---

阶段摘要

阶段 1：数据导入与鉴定

加载峰表（CSV/TSV）或处理原始谱图（mzML）。按准确质量（+/- 5 ppm）与 HMDB 条目匹配特征。指定置信级别：L1（标准品匹配）、L2（MS/MS）、L3（仅质量）、L4（未知）。

用于 L2 置信度的 MS/MS 谱库匹配（MassBank Europe）：当某个特征身份未知且只有碎片谱时，使用 src/tooluniverse/data/massbank_tools.json 中的 5 个工具，在 MassBank Europe 的开放获取参考谱库（约 139,000 条记录）中搜索，而不是根据质量猜测身份（仅按质量匹配的结果最多为 L3；只有匹配的 MS/MS 碎裂模式才足以判定为 L2）：

工具	用途
MassBank_spectral_similarity_search	未知 ID 的核心工作流。 提交查询 MS/MS 峰列表，格式为逗号分隔的 mz;intensity 对（例如 "163.0601;100,145.0495;60,127.0390;30"），即可获得按余弦评分排序的候选登录号（分数范围为 [0,1]，1.0 表示光谱完全相同）。默认阈值为 0.5；若只需要高置信度匹配，可提高到 0.8 以上；若要扩大候选范围，可降低到 0.3 左右。
MassBank_get_record_by_accession	将候选登录号（来自其他 4 个工具中的任意一个）解析为完整记录：化合物名称、分子式、精确质量、SMILES/InChI、仪器/采集参数，以及指向 CAS/CHEBI/KEGG/PubChem 的交叉引用。
MassBank_search_by_compound	按名称（例如 "glucose"）查找已怀疑的化合物对应的参考光谱——适用于确认假设或提取参考光谱进行比对，不适用于从头识别。
MassBank_search_by_formula	用途类似，但按分子式筛选（例如 "C6H12O6"）；适用于根据精确质量推断出分子式，但仍不确定具体化合物/异构体的情况。
MassBank_search_records_advanced	使用 AND 组合的筛选条件缩小大量候选范围：exact_mass+mass_tolerance、必需的碎片 peaks 值、neutral_loss、ion_mode、ms_type、instrument_type，或 SMILES/SMARTS substructure 匹配。仅返回登录号——使用 MassBank_get_record_by_accession 解析每个登录号。

已在线验证（MassBank Europe API，tu test/tu run，全部 5 个工具，11/11 个示例通过）：实际搜索 "glucose" 会返回葡萄糖及其生物衍生物的光谱（例如葡萄糖-6-磷酸，MSBNK-Antwerp_Univ-METOX_P100333_9EE2，分子式 C6H13O9P，质量 260.0297，并带有 CAS/CHEBI/KEGG/PUBCHEM/INCHIKEY 交叉引用）——搜索结果不局限于查询的确切化合物，因此在将某条结果视为已确认匹配之前，请检查每个候选的 formula/mass。请注意，这与 tooluniverse-metabolomics 基于 HMDB 的查找确实不同：当身份未知且你只有光谱时，使用 MassBank；当你已经怀疑某个名称或 ID，且想了解通路/生物学背景时，使用 tooluniverse-metabolomics/HMDB。

第二个 MS/MS 光谱库（GNPS），以及天然产物生物合成分类：src/tooluniverse/data/gnps_tools.json 中的 4 个工具覆盖 GNPS（全球天然产物社会分子网络）——它是 MassBank 的同类参考库，而非替代品。两者都是开放的、由社区整理的 MS/MS 库；GNPS 自身的社区和贡献流程（分子网络）使其收录内容更偏向天然产物以及微生物/环境代谢物，而 MassBank Europe 的贡献者则更偏向运行标准品的仪器实验室——实际而言，这意味着某个化合物可能未收录在其中一个库中，却收录在另一个库中，因此对于确实未知的特征，值得同时查询两个库，而不要将 MassBank 中的未命中结果视为定论。

工具	用途
GNPS_get_spectrum	通过其 USI（通用谱图标识符，格式为 mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB{id} — 一种跨存储库的谱图寻址标准，并非 GNPS 专用表示法）检索 GNPS 参考谱图。返回前体 m/z/电荷、峰数、m/z 范围，以及按强度排序的前 20 个峰。
GNPS_compare_spectra	并排比较两个 USI（分别显示前体 m/z 和峰数），并获取用于交互式可视化比较的 mirror_plot_url — 在最终确认前，可借此直观检查拟议匹配是否合理。
GNPS_get_library_record	将 CCMSLIB 登录号（来自分子网络匹配结果或 GNPS_get_spectrum USI）解析为完整的化合物注释：名称、加合物、SMILES、InChI/InChIKey、仪器、离子模式、贡献 PI 和库归属。这相当于 GNPS 版的 MassBank_get_record_by_accession。
GNPS_npclassifier_from_smiles	不是谱图匹配 — 而是一个独立的后续步骤。接收一个 SMILES（例如已通过 GNPS_get_library_record、MassBank 或 HMDB 解析得到的 SMILES），并返回其天然产物生物合成分类：pathway（例如 Alkaloids、Shikimates and Phenylpropanoids）、superclass、class（每项都是一个数组 — 一个结构可能属于多个类别，例如吗啡会同时返回 Isoquinoline alkaloids 和 Morphinan alkaloids），以及 is_glycoside 标志。适用于任何 SMILES，无需查询库，因此即使结构是根据基本原理进行碎片解析后提出的，而非来自数据库匹配，也很有用。获得（或正在提出）一个结构并希望了解其天然产物背景时使用 — 它并非用于识别未知谱图。

已进行实时验证（通过 gnps2 调用 GNPS API，使用 tu test/tu run，全部 4 个工具的 7/7 个示例均通过）：GNPS_get_library_record("CCMSLIB00005435737") 会解析为 "Lovastatin M+H; Mevinolin annotated in standard"，并返回完整的 SMILES/InChI；annotations 数组中包含底层 GNPS 记录字段（Scan、Library_Class、task_id 等），同时还提供扁平化的顶层字段；GNPS_npclassifier_from_smiles 将槲皮素正确分类为 Flavonols/Flavonoids/Shikimates and Phenylpropanoids，将吗啡正确分类为上述包含两个类别的 Isoquinoline alkaloids+Morphinan alkaloids 结果 — 证实 class 可以合法地包含多个条目。

阶段 2：质量控制

评估 QC 样本中的 CV（拒绝 >30%），计算空白比值（保留 >3 倍空白的特征），过滤缺失值 >50% 的特征。检查内标回收率（95-105% 为可接受范围）。

阶段 3：归一化

提供三种方法：TIC（简单，假设总丰度相近）、PQN（对大幅变化具有稳健性，推荐）和内标法（使用加标标准品时最准确）。之后进行 log2 转换或 Pareto 缩放。

阶段 4：探索性分析

PCA 可揭示样本分组和批次效应。PLS-DA 可进行有监督的分离（报告 R2 和 Q2 以评估模型质量）。标记并调查异常值。

阶段 5：差异分析

使用 Welch's t 检验（两组）或 ANOVA（多组），并进行 Benjamini-Hochberg FDR 校正。显著性阈值：adj. p < 0.05 且 |log2FC| > 1.0。

阶段 6：通路分析

将差异代谢物映射到 KEGG 化合物 ID。进行 MSEA 通路富集分析。考虑拓扑结构：位于通路枢纽（度数/介数中心性高）的代谢物影响更大。

阶段 7：多组学整合

将代谢物水平与酶表达量进行相关性分析（Spearman）。预期结果：底物-酶负相关（消耗），产物-酶正相关（生成）。结合代谢物与基因证据，对通路失调进行评分。

阶段 8：报告

完整示例输出请参阅 report_template.md。

---

与 ToolUniverse 集成

技能	用途	阶段
tooluniverse-gene-enrichment	通路富集分析	阶段 6
tooluniverse-rnaseq-deseq2	用于整合的酶表达	阶段 7
tooluniverse-proteomics-analysis	用于整合的蛋白质水平	阶段 7
tooluniverse-multi-omics-integration	全面整合	阶段 7

---

最低量化要求

组成部分	要求
代谢物	至少鉴定出 50 种代谢物
重复样本	每种条件至少 3 个
质控	QC 样本中的 CV < 30%，并扣除空白
统计检验	使用 t 检验或 Wilcoxon 检验，并进行 FDR 校正
通路分析	使用 KEGG 或 Reactome 进行 MSEA
报告	包含 QC、差异代谢物、通路和可视化结果

---

局限性

• 鉴定：许多特征仍未鉴定（Level 4）
• 覆盖范围：无法检测所有代谢物（取决于方法）
• 定量：相对丰度（没有标准品时无法进行绝对定量）
• 异构体：难以区分结构异构体
• 离子抑制：基质效应可能影响定量
• 动态范围：与靶向方法相比有限

---

参考资料

方法：

• MetaboAnalyst: https://doi.org/10.1093/nar/gkab382
• XCMS: https://doi.org/10.1021/ac051437y
• MSEA: https://doi.org/10.1186/1471-2105-11-395

数据库：

• HMDB: https://hmdb.ca
• KEGG Compound: https://www.genome.jp/kegg/compound/
• Reactome: https://reactome.org

---

参考文件

• code_examples.md - 所有阶段的 Python 代码（数据加载、QC、归一化、统计分析、通路分析）
• report_template.md - 完整报告示例（LC-MS 疾病组与对照组比较）