Metabolomics Workbench — 代谢组 NIH 国家存储库 AI-Ready Wikipedia

NIH 资助：4,570 项公开代谢组研究与 RefMet 标准命名中枢

来源 UCSD San Diego Supercomputer Center（NIH Common Fund NMDR） url: https://www.metabolomicsworkbench.org/发布时间: 2026-09-16最后更新: 2026-09-25 阅读 53
Metabolomics Workbench — 代谢组 NIH 国家存储库 AI-Ready Wikipedia

信息速览

数据集名称Metabolomics Workbench — 代谢组 NIH 国家存储库 AI-Ready Wikipedia
数据类型4,570 项公开研究,6,125 个分析（2025-10 口径）,164,000+ 化合物结构,mwTab/JSON/mzML 格式,免费开放获取
规模官方未披露全库累计样本数（5,106 项研究，覆盖人、动物、植物与微生物）
接入方式UCSD San Diego Supercomputer Center（NIH Common Fund NMDR） url: https://www.metabolomicsworkbench.org/
AI 就绪度

数据集封面

Metabolomics Workbench（代谢组工作台） — 代谢组 NIH 国家存储库 AI-Ready Wikipedia

INFOBOX
数据集名称 Metabolomics Workbench（代谢组工作台）
英文全称 Metabolomics Workbench — NIH Common Fund National Metabolomics Data Repository（NMDR）
别名/简称 MW、NMDR、UCSD Metabolomics Workbench
疾病分类 全疾病谱代谢表型（ICD-11：5A11 2 型糖尿病 / BA41 急性心肌梗死 / 1G40 脓毒症 / 5B80 肥胖症等多系统，详见 §2.1）
SNOMED CT 44054006 Diabetes mellitus / 22298006 Myocardial infarction / 162863004 Obesity / 108252007 Laboratory procedure（详见 §2.1b）
数据模态 代谢组（LC-MS/GC-MS 质谱、NMR 波谱）+ 原始二进制谱图 + 处理后定量表 + 实验元数据
AI 任务类型 代谢物名称标准化、跨研究 meta 分析、疾病分型/分类、生物标志物发现、批次效应校正、缺失值插补
样本总数 累计处理 5,106 项研究、公开 4,570 项（截至 2026-09-15）；6,125 个分析（截至 2025-10-22 官方口径）
数据大小 官方未披露全库总量；单研究原始数据可达数十 GB，支持 100 GB 以上提交
数据格式 mwTab（文本）/ JSON / mzML / mzXML / 厂商格式（Thermo raw、WIFF、.d）/ NMR FID/FT
许可证 官网 Terms of Use（as-is、开放访问）；主论文 CC BY 4.0
访问级别 开放（公开数据免注册下载；部分研究处于 embargo 期）
语言 英文
首发日期 2013（平台上线）/ 2016-01-04（Nucleic Acids Research 论文刊出）
最后更新 持续滚动更新（截至 2026-09 仍定期发布新研究）
发布机构 加州大学圣地亚哥分校圣地亚哥超级计算中心（UCSD/SDSC）× NIH Common Fund NMDR
官方主页 https://www.metabolomicsworkbench.org/
下载地址 https://www.metabolomicsworkbench.org/data/browse.php
DOI 10.1093/nar/gkv1042（主论文）；数据集 DOI 前缀 10.21228（如 PR000001 为 10.21228/M8159B）
引用次数 635+（Europe PMC，截至 2026-06-13）
AI 就绪度评分 ⭐⭐⭐⭐（4/5）— REST API 与 mwTab/JSON 高度结构化、RefMet 统一命名、配套 mwtab Python/R 工具链；扣分项：非靶向特征无现成名称矩阵、跨研究单位与批次不统一、无官方 ML 划分
页面状态 published

§0 E-E-A-T 信任声明与免责声明

医学审核者：千方病案医学编辑部交叉审核：§2 医学背景（ICD-11/SNOMED CT 映射、代谢表型与临床任务定义、金标准描述）、§7 偏倚分析。

数据工程审核者：千方病案医学编辑部交叉审核：§4 DAIMS 数据字典（Project/Study/Analysis 三级标识、mwTab 字段体系）、§5 数据划分策略、§6 预处理 Pipeline 和坑点。

审核日期：2026-09-05

审核方式：交叉审核

利益冲突声明：千方病案医数集与 UCSD/SDSC、NIH 无任何商业利益关联。本页面不销售 Metabolomics Workbench 数据集本身，仅提供 AI 就绪指南与学术信息服务。编辑者未接受 UCSD、SDSC 或 NIH 的任何形式资助。

医疗免责声明：本页面提供的医学信息仅供研究和教育目的，不构成医疗建议、诊断或治疗方案。数据集的医学描述基于公开发表的文献，未经逐一临床验证。任何基于该数据集训练的 AI 模型在应用于临床决策前，必须经过独立的临床验证和监管审批。

技术免责声明：本页面的代码示例、预处理建议和基准性能数据基于公开资料整理，不保证在特定环境下的准确性和适用性。使用者应自行验证代码安全性和数据预处理流程的正确性。千方病案医数集不对因使用本页面信息而导致的任何直接或间接损失承担责任。

数据使用合规：使用本页面描述的数据集前，请务必阅读并遵守数据集原始许可协议。Metabolomics Workbench 公开数据按官网 Terms of Use 开放访问（as-is，无担保），提交方数据另有 embargo 期约定。DUO 类使用限制在本库无官方标签体系，具体使用条件以官网条款与各研究页面说明为准。

§1 数据集概览

§1.0 📌 30 秒速览

这是什么？ Metabolomics Workbench（代谢组工作台）是美国国立卫生研究院（NIH）Common Fund 出资建设的国家代谢组数据存储库（National Metabolomics Data Repository，NMDR），由加州大学圣地亚哥分校圣地亚哥超级计算中心（UCSD/SDSC）运行。全球任何实验室都可以把质谱（MS）或核磁共振（NMR）代谢组研究的原始谱图和定量结果提交上来，截至 2026-09-15 已累计处理 5,106 项研究，其中 4,570 项公开可下载，提交者遍布 60 个国家。

为什么重要？ 代谢组数据长期散落在各实验室，代谢物命名不统一导致跨研究无法比较。该平台用 RefMet 体系把 3,500 多项研究里出现过的 70 万多个名称整理成一套标准命名，把 16.4 万多个化合物结构与各研究定量值关联起来，让"不同研究测到的代谢物能不能对上"这个老大难问题第一次有了系统解法。

我能用它做什么？ 免注册下载任何公开研究的定量表（mwTab/JSON）和原始谱图文件；用 REST API 批量拉取数据训练疾病分型或生物标志物模型；把自家实验的代谢物名称批量映射到 RefMet 标准名；做跨研究的 meta 分析和教学演示。

§1.1 技术摘要

Metabolomics Workbench 采用 Project → Study → Analysis 三级组织结构：Project（PR######）对应一次提交及其 DataCite DOI（前缀 10.21228），Study（ST######）对应一项实验设计，Analysis（AN######）对应一次具体分析运行（如某一极性的 LC-MS 或某一 NMR 实验），截至 2025-10-22 官方口径为 2,466 个 Project、3,795 项 Study、6,125 个 Analysis [Sud M et al., 2016, Nucleic Acids Research. https://doi.org/10.1093/nar/gkv1042；Thompson PT & Moseley HNB, 2026, Metabolites. https://doi.org/10.3390/metabo16010076]。

每个分析必须提交标准化实验元数据（采样、色谱、质谱/波谱参数），处理后数据以 mwTab 平面文本格式存储（含因子表与代谢物×样本定量矩阵），同时提供 JSON 等价文件；原始数据保留厂商二进制格式（Thermo raw、WIFF 等）或 mzML/mzXML 交换格式。平台配套 REST API（7 类 context，默认 JSON 返回）、在线统计工具（PLS-DA、DSPC 相关网络、RDKit 结构相似性网络）以及 mwtab（Python）、RefMet（R）等官方编程包。数据策展由 NMDR 团队完成，处理周期通常在 30 天以内，公开数据经 Project DOI 可稳定引用。

REST 的 7 类 context 值得单独记忆：study（研究元数据与定量数据）、compound（化合物结构与外部 ID）、refmet（名称标准化）、metstat（代谢物频次统计，8 槽位分号语法）、gene / protein（基因-蛋白对应）、moverz（质量数检索与脂质精确质量计算）。本页 §6 的代码即围绕 study、refmet、moverz 三个最常用 context 展开，其余四个覆盖化学与组学关联查询。

§1.2 战略价值

维度一：命名标准的"公共基础设施"价值。 代谢组学最大的互操作性障碍是命名混乱：同一化合物可能以俗名、缩写、同位素修饰名等十几种写法出现，而 MS 检测的许多脂质（如 PC 34:1、TG 54:2）只以等压物种（isobaric species）形式存在，根本没有唯一结构。RefMet 用"分析化学为中心"的四层分辨率命名统一处理这两类对象，并提供批量名称映射接口、R/Python 脚本和 REST 端点。对 AI 团队而言，这相当于免费获得了别人花数万小时策展的"代谢物别名词典"，直接决定跨研究模型能否把同一列数据当成同一个特征。这层价值随库增长还在复利：每新增一项研究，RefMet 的名称来源池就扩大一分，映射覆盖率随之抬升。

维度二：美国官方背书的长期可用性。 平台由 NIH Common Fund 代谢组计划（2012-2022）建立，其后由 NIDDK 持续资助（U2C-DK119886 等），数据发布带 DataCite DOI、提交记录含资助号，已被 FAIRsharing、re3data 等注册系统收录。自 2013 年以来数据集规模约每 2-3 年翻倍，2024-04 至 2025-10 期间增长 50% [Thompson PT & Moseley HNB, 2026, Metabolites. https://doi.org/10.3390/metabo16010076]。对需要长期维护数据资产的企业与研究组，这种"资助线 + 注册标识 + DOI"的组合显著降低了数据消失或漂移的风险。

维度三：编程访问与工具链的"开箱即用"价值。 多数生物数据库止步于网页下载，本库则把三层访问通道全部官方化：REST API（7 类 context、JSON 默认返回、交互式 URL 构造器）、FTP 全库镜像、以及两个官方维护的编程包（Python 的 mwtab 2.0 负责 mwTab/JSON 解析与校验，R 的 RefMet 包负责批量名称映射与绘图）。对 AI 工程团队，这意味着从"拿到数据"到"进入训练循环"之间没有必须人工搬运的环节；对平台团队，意味着可以把本库直接当作上游数据源接入调度系统，而不是当作一个需要爬虫的网页。

§1.3 同类数据集横向对比

数据集 管理机构 数据模态 规模要点 标注/命名体系 与本库的差异化
Metabolomics Workbench UCSD/SDSC（NIH 资助） MS + NMR，原始谱图 + 定量表 4,570 项公开研究（截至 2026-09-15） RefMet 四层命名 + 164,000+ 结构库 美国官方库，元数据强制策展，mwTab/JSON 双格式
MetaboLights 欧洲生物信息学研究所（EBI） MS + NMR，研究级存储 化合物库此前核实口径为 33,253 个化合物 ISA-Tab 衍生元数据体系 欧洲对应库，与本库被文献类比作 SRA/ENA 关系
GNPS 加州大学圣地亚哥分校 LC-MS/MS 分子网络 以谱图匹配与分子网络社区著称 基于谱图相似性的分子网络 侧重碎片谱图社交化注释，非研究级定量表
HMDB 加拿大阿尔伯塔大学 人类代谢物注释与参考谱图 以人工策展的化合物条目见长 化合物-centric 注释 参考知识库而非原始研究数据存储库
MassBank 日本等多机构联盟 高质量二级质谱参考谱图 覆盖多仪器厂商的标准谱图记录 谱图-centric 记录 为本库 MS 检索功能提供交叉参考源

注：表中他库名称仅作纯文字对比，规模数字以各自官方页面为准，不与本章统计口径混用。

选库速判：要"研究级原始+处理数据与美国官方背书"选本库；要"欧洲体系与 ISA-Tab 生态"选 MetaboLights；要"谱图分子网络社区注释"选 GNPS；要"化合物参考知识"选 HMDB。四库并非竞争关系，成熟研究常同时在两库留有交叉引用。

§1.4 版本与里程碑时间轴

时间 里程碑
2012 NIH Common Fund 代谢组计划启动，DRCC 获资助 U01 DK097430
2013 平台建立并开始接收提交（官方口径 establishment in 2013）
2015-10-13 NAR 主论文在线发表；2016-01-04 刊于 Nucleic Acids Research 44(D1):D463-D470
2016 首个 Project（PR000001）获 DOI 10.21228/M8159B，DOI 前缀体系确立
2017 mwtab Python 包首个版本发布，开放编程访问
2020-11 RefMet 命名论文发表于 Nature Methods 17(12):1173-1174
2022 Common Fund 代谢组计划资助期结束，NIDDK 以 U2C-DK119886 等资助延续运营
2024-04 至 2025-10 库内数据集数量增长 50%，恢复约每 2-3 年翻倍的增速
2025-07-22 REST API 文档更新至 v1.2
2025-10-22 官方统计口径：2,466 Projects / 3,795 Studies / 6,125 Analyses
2026-01 mwtab 2.0 论文刊出（Metabolites 16(1):76），全库校验能力上线
2026-09-15 官网首页口径：累计处理 5,106 项研究，公开 4,570 项，embargo 中 536 项

§1.5 典型应用场景

  1. 跨研究 meta 分析：以 RefMet 标准名对齐多项研究的同名列，合并效应量，评估某代谢物（如胆固醇、柠檬酸）在不同疾病队列中的方向一致性。落地路径：REST refmet/match 对齐 → 各研究内标准化 → 随机效应汇总；对 AI 团队而言这是检验候选标志物稳健性的最低成本方式。
  2. 疾病分型与生物标志物建模：取一项人源临床研究（如血浆靶向 LC-MS），用因子表作监督标签，训练分类模型并做交叉验证。样本量与类别分布见各研究 factors 输出，建模前先跑 §4.2 的分布统计脚本。
  3. 代谢物名称清洗流水线：把自家实验导出的数千个代谢物名通过 RefMet 映射端点批量标准化，并连带获取 KEGG、PubChem 等外部 ID。输出物可直接充当院内数据湖的代谢物维表（dim_metabolite）。
  4. FAIR 质量评估研究：利用 mwtab 包的校验功能对全库数据集做格式合规性审计（已有同行评审先例）。该路线产出的不是模型而是数据质量报告，适合数据治理团队立项。
  5. 教学与培训：用公开研究的"元数据 + 定量表 + 原始谱图"完整链条演示代谢组分析全流程，官方 Exemplary Studies 清单可作为教学样板。对没有代谢组背景的算法工程师，一条 Study 的元数据读下来约等于一次免费的分析化学导论课。

§2 医学背景

§2.1 ICD-11 编码映射

Metabolomics Workbench 不按 ICD-11 组织数据，但库内研究通过 REST 的 disease 端点标注疾病关联。下表为库内高频疾病场景与 ICD-11 的示例映射（用于检索聚合，非官方标注）：

疾病/表型 ICD-11 编码 ICD-11 中文名 库内研究示例场景
Type 2 diabetes mellitus 5A11 2 型糖尿病 血浆靶向代谢组比较糖耐量异常人群
Acute myocardial infarction BA41 急性心肌梗死 心肌缺血相关脂质组变化
Sepsis 1G40 脓毒症 危重症血清代谢谱与预后
Obesity 5B80 肥胖症 减重干预前后的代谢物动态
Chronic kidney disease GB61 慢性肾脏病 尿素循环与尿毒症毒素谱
Malignant neoplasms（多个编码） 2A00-2F9Z 恶性肿瘤（按部位细分） 肿瘤组织/血浆代谢重编程研究

§2.1b SNOMED CT 映射

标签 ICD-11 SNOMED CT 码 SNOMED 术语
2 型糖尿病 5A11 44054006 Diabetes mellitus (disorder)
急性心肌梗死 BA41 22298006 Myocardial infarction (disorder)
肥胖症 5B80 162863004 Obesity (disorder)
实验室代谢检测（父类） 第 18 章 108252007 Laboratory procedure (procedure)

注：SNOMED CT 映射同样为编辑部落成的检索聚合辅助，官方数据模型使用 RefMet 与 KEGG/PubChem 等化学标识而非医学术语系统。

§2.2 疾病与代谢表型简介

代谢组学测量的是小分子代谢物（分子量通常低于 1,500 Da）在血液、尿液、组织等样本中的浓度或相对丰度，是基因组、转录组、蛋白组下游的"功能读出层"。与"编码基因数量固定"的基因组不同，可检测代谢物集合随平台、色谱与仪器而变，这决定了代谢组数据天然异质、必须在命名层先统一再比较。

库内疾病研究集中在三条主线：

  • 代谢性疾病——2 型糖尿病、肥胖与非酒精性脂肪肝研究借助空腹血糖、脂质物种与支链氨基酸谱刻画胰岛素抵抗；此类研究多为靶向定量设计，注释层级高，适合作为建模首选。
  • 心脑血管与危重症——急性心肌梗死、卒中和脓毒症研究追踪能量代谢、磷脂降解与炎症介质的动态；危重症研究的采样时点密集，时序建模价值高。
  • 肿瘤代谢重编程——肺癌、乳腺癌等研究利用瓦博格效应相关代谢物（乳酸、谷氨酰胺衍生物）寻找诊断与分型标志物；肿瘤研究常含癌旁对照，是配对设计的天然素材。

截至 2026-09，库内人源研究覆盖上述场景，同时保留大量动物（小鼠、大鼠）、植物（拟南芥、水稻、大麦）、微生物与昆虫研究，构成跨物种比较的背景语料。跨物种研究的价值在于方法学锚定：同一代谢物在不同物种中的响应方向，可以提示保守通路与物种特异性机制。

此外，HHEAR 暴露组专项数据为环境健康研究提供了独特切口：外源化合物及其代谢物在人体内的浓度谱，是连接环境污染与疾病终点之间的分子证据层，这部分研究的元数据规范与主库一致，可直接复用本页的分析管线。

§2.3 临床任务定义

任务类型 定义 在本库中的实现方式
疾病筛查/诊断 用代谢谱区分病例与对照 因子表提供 case/control 标签，定量表作特征矩阵
疾病分型 在同一疾病内细分分子亚型 多因子研究（如治疗前后、应答/不应答）支持无监督聚类
预后预测 以基线代谢谱预测终点事件 部分研究附随访信息；建模时需核对各研究元数据
生物标志物发现 筛选差异代谢物并跨研究验证 RefMet 对齐后做多研究方向一致性检验
暴露组分析 环境暴露与代谢表型关联 平台托管 HHEAR（人类健康暴露分析资源）专项研究
治疗反应监测 干预前后代谢谱动态 时序因子研究（治疗前/后、应答/不应答）
通路富集与机制解释 差异代谢物映射到代谢通路 kegg_id 映射 + 外部通路工具

§2.4 患者人群构成

维度 描述
来源 全球 60 个国家的实验室提交；人源研究以美国 NIH 资助核心设施（如密歇根大学、加州大学戴维斯分校、梅奥诊所）与各国合作队列为主
时间跨度 平台 2013 年上线至今滚动收录；各研究采样时间以其元数据为准
年龄/性别 由各研究自行设定（成人为主，含儿科与老年专项研究）；全库无统一人口学汇总
种族/族群 各研究元数据按需记录；全库未强制收集，公平性分析需逐研究核查
就医类型 覆盖门诊筛查、住院与 ICU 危重症、健康体检队列与社区流行病学队列
非人源样本 大量动植物与微生物研究，适合方法学基准而非临床推断

§2.5 临床价值

对临床 AI 而言，本库的价值不在"直接可部署"，而在证据链的先导层：任何候选代谢标志物在进入前瞻性验证前，都可以在此先回答三个问题——别的队列是否复现了同样方向的变化、测量该代谢物用的什么平台与内标、该代谢物的标准名与结构是什么。这三个问题分别对应可复现性、测量可比性与语义互操作，是临床决策支持系统对证据的最基本要求。

官方 Exemplary Studies 清单示范了"研究摘要 + 采集/色谱/质谱元数据 + 对照样本 + 原始数据一一对应"的完整披露标准，可作为临床数据管理计划（DMP）中代谢组部分的模板。对医院端团队，把"数据 deposit 到 NMDR 并引用 Project DOI"写进 DMP 流程，既满足 NIH 式资助合规，也让回顾性研究的数据资产可审计。

需要注意的是，库内定量值为研究内相对量居多，直接外推为临床参考区间是不成立的，临床决策场景必须经过独立前瞻验证。合理的用法是：本库产出"候选 + 证据方向"，前瞻队列产出"阈值 + 决策曲线"，两段证据链在论文与监管材料中都应分开陈述。

§2.6 金标准与参考依据

维度 内容
划分金标准 无官方 ML 划分；以 Study 为不可跨越的分组单元是社区默认铁律（详见 §5）
标注金标准 代谢物注释：靶向研究以标准品保留时间与谱图比对为准；非靶向研究以提交者报告的命名 + RefMet 映射为准
标注者 各提交实验室的分析化学团队 + NMDR 策展团队（Neela Srinivasan、Srini Ramachandran、Shashidhar Rao 等）
性质 研究级存储库（repository），非基准数据集；"金标准"体现为元数据强制与策展流程，而非统一标签
引用金标准 官方 How to Cite 模板（Project ID + Project DOI + 资助致谢）
质量标杆 Exemplary Studies 八项标准（摘要/元数据/对照/内标/原始数据映射等）

理解本库"金标准"的正确姿势：它是披露标准而非标签标准——官方保证的是"元数据完整、来源可溯、原始与处理数据对应"，而不是"某代谢物与某疾病的关联已定论"。后者仍属于各提交研究的科学判断，需要使用者带着批判眼光复核。

§3 数据集规格

§3.0 版本抉择矩阵

本库为滚动更新型存储库，不存在"选 v1 还是 v2"的问题，版本决策实为获取口径决策：

你的需求 推荐口径 获取方式 理由
建模某一项研究，要可复现快照 Project DOI 固定版本 引用具体 Project DOI（前缀 10.21228） DOI 指向策展后的固定内容，论文引用合规
全库扫描做 meta 分析 REST API 即时口径 rest/study/study_id/ST/available 列全库 始终拿到最新公开集合，自动跳过 embargo
大批量原始谱图归档 FTP 批量下载 ftp://www.metabolomicsworkbench.org/ 适合拿到磁盘配额后一次性镜像
单研究深挖 网页端 Browse/Download 每分析页面附原始文件与结果表下载 有界面引导，可先看再下

§3.1 模态详情

  • LC-MS（液相色谱-质谱）：库内主力模态，覆盖正/负离子两种极性、HILIC 与反相色谱；靶向研究提供浓度或峰面积表，非靶向研究另入 m/z-RT 特征库。
  • GC-MS（气相色谱-质谱）：多用于衍生化后的中心碳代谢物与有机酸，靶向定量表常见于早期核心设施研究。
  • NMR（核磁共振）：接受 FID 自由感应衰减或傅里叶变换后谱图作原始数据，处理后数据为分箱面积或绝对浓度，适合绝对定量场景。
  • 直接进样质谱与脂质组： lipidomics 研究沿用 LIPID MAPS 缩写体系（如 PC 34:1），经 RefMet 层级映射到等压物种名。
  • 元数据层：所有模态强制携带采样方案、样本来源、色谱条件、仪器参数等 mwTab 元数据段，这是区别于一般"文件堆"存储库的关键。
  • 衍生模态： fluxomics（通量）与 IROA 同位素示踪研究亦有收录，其数值语义（同位素丰度比）与常规定量不同，建模前须单独核实元数据说明。

§3.2 按子集的规模表

子集 规模口径 说明
全部研究 5,106 项（截至 2026-09-15） 官网首页"已处理"总数
公开研究 4,570 项（截至 2026-09-15） 免注册直接下载
Embargo 研究 536 项（截至 2026-09-15） 到期自动转入公开
分析数 6,125 个（截至 2025-10-22） 官方论文口径，晚于该日期的新提交未含
Project 数 2,466 个（截至 2025-10-22） 同上
非靶向 m/z 特征库 450 万+ 特征，来自 890+ 研究、1,500+ LC-MS 分析 官方非靶向检索门户口径
化合物结构库 164,000+ 独立结构 官方 Metabolite Database 口径
RefMet 名称库 70 万+ 原始名称策展，覆盖 3,500+ 研究 官方 RefMet 页面口径
提交国家 60 个 官网首页口径

读表提示：上述口径分属三个日期（2026-09-15 首页、2025-10-22 论文、2026-09 各功能页），引用时务必带各自口径日期，不可互相换算或相加。

§3.3 数据格式表

内容 格式 获取方式
处理后定量表 + 元数据 mwTab（制表符文本） 每分析页下载 / REST mwtab 输出
等价结构化文件 JSON REST 默认输出 / 下载页 JSON 文件
MS 原始谱图 Thermo .raw、Sciex WIFF、Agilent .d、mzML、mzXML 等 分析页"Uploaded data"链接
NMR 原始谱图 FID 或 FT 数据（厂商格式） 同上
结果统计表 datatable（REST 输出） rest/study/analysis_id/AN…/datatable
化合物描述 SMILES、InChIKey、molfile、SDF、PNG REST compound context
名称标准化 RefMet 名称 + 分类层级 REST refmet context / R 包 / Python 脚本
实验协议 网页/文档 Protocols 栏目（通用协议 + 研究级协议）
培训材料 教程/视频 Tutorials 与 FAQ 栏目
非靶向特征检索 网页查询 search_untarg_mz_form 门户（450 万+ 特征）

§3.4 存储规模

官方未披露全库累计字节数。可参考的锚点：单研究原始数据可达数十 GB（如某结核血浆非靶向研究上传 34.4 GB Thermo 原始文件），官方上传接口支持 100 GB 以上提交、最高 100 Gbit/s 速率；网页端按分析给出具体"Uploaded data"体积。规划镜像时建议按"全库数十 TB"作保守预留，并以 FTP 目录实测为准。

容量规划的工程提示：定量表（mwTab/JSON）体积与原始谱图相差 3-4 个数量级，"全库分析建模"与"全库谱图复处理"是两个相差数十 TB 的存储方案，应按业务目标二选一或分期建设，不要一开始就为谱图全镜像买单。

§3.5 标注方式

标注（即代谢物注释与因子标签）分四类：① 靶向定量——用标准品校准的绝对浓度，注释可信度最高；② 稳健命名注释——以保留时间 + 谱图比对确认的注释；③ 推测注释——仅凭精确质量/保留时间匹配的命名，多见于非靶向研究；④ 无名特征——非靶向库里只有 m/z 与保留时间的峰。因子标签（诊断、处理、时间点等）由提交者定义、策展团队复核格式，语义质量因研究而异。这种"注释可信度分层"是建模前必须显式处理的现实。

四类标注对应四种建模姿态：① 可直接用于绝对量结论与临床阈值讨论；② 适合跨研究特征对齐与 meta 分析；③ 只支持研究内相对比较，结论须带"注释等级"限定；④ 仅用于方法学验证（特征检测重现性、批次效应量化），不得进入生物学解释。本页 §6.5 坑点 2 与坑点 3 的处理规则均建立在这一分层之上。

§3.6 标注者资质与一致性

提交方均为具备代谢组分析能力的实验室（NIH 核心设施、高校分析化学团队、医院研究中心）；策展由 NMDR 专职团队完成，流程含 30 天内格式核验、mwTab 规范检查与原始/处理数据对应关系审查。官方未公布统一的标注者间一致性指标（如 Kappa）；质量参照物是官方 Exemplary Studies 清单——同时满足元数据详尽、含对照与内标、原始文件与样本名一一映射等 8 项标准的研究被点名示范。

§3.7 采集周期

平台层采集周期为 2013 年至今的持续滚动收录。单项研究的采样周期由其协议决定（从单时点到数年队列随访），以各研究 mwTab 元数据中的采集描述为准；发布节奏上，策展完成后按提交者指定日期公开，Common Fund 资助数据不晚于首篇论文接收日公开。

对建模者的含义：库内"研究"是异时性的（不同年份、不同队列持续汇入），任何一次性抓取都只是时间切片。建议在数据卡中记录抓取日期与 ID 清单哈希，跨时间重复实验时以同一快照复跑；若需要纳入新发布研究，应作为独立的"数据集版本升级"处理而非静默追加。

§3.8 地域覆盖

提交来自全球 60 个国家（官网首页，截至 2026-09）。研究机构以美国为主（密歇根大学、加州大学戴维斯分校、加州大学圣地亚哥分校、北卡罗来纳大学、梅奥诊所、佛罗里达大学等 NIH 核心设施），亚洲与欧洲机构占比持续上升（库内可见浙江大学、中山大学、复旦大学附属中山医院等中国机构提交，以及多国合作研究）。样本地理属性以研究执行地为准，元数据未统一记录受试者出生地或居住地经纬度。

对地域敏感的应用（如饮食相关代谢表型），应把"研究执行地"视作混杂变量而非精确暴露坐标——本库的 spatialCoverage 只能保证提交来源可查，不能替代流行病学层面的暴露评估。

§3.9 设备与平台规格

平台 常见厂商格式 库内角色
Thermo LC-MS .raw 非靶向主力，高分辨轨道阱
Sciex LC-MS WIFF 三重四极杆靶向定量常见
Agilent GC-MS/LC-MS .d 代谢通量与挥发物研究
Bruker/Varian NMR FID/FT 文件 绝对定量与代谢物鉴定
开放交换格式 mzML、mzXML 跨软件处理的中间格式

具体仪器型号、离子源与碰撞能量记录在各分析元数据中，可经 REST analysis 输出读取；本页不逐一罗列型号清单以免过时。

建模提示：仪器型号是天然的批次协变量。跨研究合并时，即使无法做完整批次校正，至少应把"仪器厂商 + 电离源 + 色谱柱类型"三元组作为最小分层变量保留——它们在元数据中强制存在，可程序化提取，成本低而解释力高。

§3.10 深度溯源链

层级 溯源要素
资助方 NIH Common Fund / NIDDK（资助号随引用模板输出，如 U2C-DK119886、原 U01 DK097430）
运行方 UCSD 圣地亚哥超级计算中心 DRCC（PI：Shankar Subramaniam；协调人：Eoin Fahy）
提交方 原始研究实验室（研究页署名机构与作者文献）
数据对象 Project（PR + DOI）→ Study（ST）→ Analysis（AN）→ 样本 → 文件
策展记录 上传时间、发布/embargo 日期、策展处理（约 30 天内完成的通知机制）
引用闭环 官方引用模板要求同时给出 Project ID 与 Project DOI
外部注册 FAIRsharing / re3data / RRID 三套注册记录与官网互链

§4 数据结构

§4.0 本地目录树（推荐布局）

本库数据经 REST + FTP 抓取落地后，推荐按如下树形组织（布局为本页建议，非官方目录规范）：

metabolomics-workbench/
├── raw/                          # FTP 或分析页下载的原始谱图
│   ├── ST001231/                 # 以 Study ID 为目录名
│   │   ├── AN001800/             # 以 Analysis ID 分子目录
│   │   │   ├── *.raw             # Thermo 原始文件（或 WIFF/.d/mzML）
│   │   │   └── params/           # 仪器参数文件
│   │   └── AN001801/
│   └── ST002474/
├── mwtab/                        # 处理后数据与元数据
│   ├── ST001231_AN001800.json    # REST mwtab 输出（JSON）
│   ├── ST001231_AN001800.txt     # 同内容 mwTab 文本
│   └── ...
├── refmet/                       # RefMet 名称映射缓存
│   └── name_map.csv              # 原始名 → RefMet 名 → 外部 ID
└── meta/
    ├── study_summary.csv         # rest/study/study_id/ST/available 全表
    ├── factors_audit.csv         # §4.2 标签审计输出（类频数/不平衡比）
    └── download_log.json         # 抓取时间与版本快照记录

§4.1 DAIMS 字段字典

以下为 AI 建模最常触碰的字段（以 REST JSON 与 mwTab 输出为准，示例值为典型形态）：

字段 类型 说明 示例值 AI 用途 观测误差/注意 信息性缺失编码 取值范围
study_id 文本 研究唯一标识 ST001231 分组单元/防泄漏 前缀 ST 固定 6 位数字 无缺失 ST000001 起
analysis_id 文本 分析运行标识 AN001800 特征来源粒度 一研究可含多个极性/平台 无缺失 AN000001 起
project_id 文本 提交与 DOI 单元 PR000001 引用与版本锁定 非 Project 化的早期数据缺此层 官方未披露统一规则 PR000001 起
analysis_type 文本 分析平台类型 LC-MS / GC-MS / NMR 模态分层建模 拼写存在历史变体 无缺失 枚举（约数类）
species 文本 样本物种 Homo sapiens 按物种过滤 存在学名/俗名并存 无缺失 分类学名称
factor_* 文本/枚举 实验因子与分组标签 factor1: Diagnosis=Control 监督标签 列名随研究自定义 空串常见 研究内自定义
refmet_name 文本 RefMet 标准代谢物名 Cholesterol 跨研究特征对齐主键 非靶向无名特征为空 空串=未命名特征 RefMet 词表
value（datatable 列） 数值 定量值（浓度/峰面积/分箱面积） 12.4 模型输入 单位与归一化随研究不同 空单元格 ≥0 或已中心化
kegg_id / pubchem_cid 文本 外部数据库标识 C00002 / 5997 通路映射 一对多情况存在 空串 各库 ID 空间
m/z、retention time 数值 非靶向特征坐标 118.0865 / 65.3 特征身份定义 跨仪器漂移 无缺失 m/z>0、RT≥0
exactmass / formula 文本/数值 化合物描述 386.6599 / C27H46O 结构特征 等压物种共享同值 空串 化学合理域
polarity 文本 离子极性 POSITIVE / NEGATIVE 同研究分视图建模 NMR 研究无此字段 空串 枚举
sample_source 文本 样本来源组织/基质 Blood、Plasma、Liver 按基质分层 命名粒度因研究而异 空串 自由文本
doi（Project 层） 文本 数据集 DOI 10.21228/M8159B 引用与快照 无 DOI 的旧提交 无缺失 10.21228/*

§4.2 标签分布

标签即因子表（factors）。全库无统一标签体系，常见分布特征：疾病研究中 case/control 二分类最普遍；时间序列研究以"基线/干预后"两时点为主；剂量-反应与多组织研究呈多类不平衡。获取方式：rest/study/study_id/ST…/factors 逐研究读取，或 rest/study/study_id/ST/species、/disease 批量拉取跨研究疾病标注。建模前必须显式统计每个 Study 内各因子的类频数——本库不存在"全库统一标签分布"这一官方口径，任何汇总都应是分析者自己算出来的。

# 标签分布审计：输出每研究每因子的类频数与不平衡比
def audit_factors(factors: dict, study_id: str) -> list[dict]:
    rows = []
    for f in factors.get("factors", [factors]):
        name, values = f.get("factor_name"), f.get("factor_values", [])
        if name and values:
            cnt = pd.Series(values).value_counts()
            rows.append({"study_id": study_id, "factor": name,
                         "n_classes": int(cnt.shape[0]),
                         "min_class_n": int(cnt.min()),
                         "imbalance": round(cnt.max() / max(cnt.min(), 1), 1)})
    return rows
# 使用：audit_factors(mw_get(f"study/study_id/{study_id}/factors"), study_id)
# 判读：imbalance > 10 的因子需类权重或重采样；n_classes=1 无法做监督任务

注意：factors JSON 的嵌套结构随研究类型略有差异，上述解析函数应先在目标研究上打印原始 JSON 校准键名后再批量运行。

该审计的输出（factors_audit.csv）建议直接进数据卡片：它同时回答"这个研究能不能做监督任务"（n_classes≥2）与"类平衡要不要处理"（imbalance 阈值）两个最常被问的问题。

§4.3 关键统计

统计项 数值 口径日期
公开研究数 4,570 2026-09-15（官网首页）
累计处理研究数 5,106 2026-09-15（官网首页）
分析总数 6,125 2025-10-22（官方论文）
Project 总数 2,466 2025-10-22（官方论文）
化合物结构数 164,000+ 2026-09（官网数据页）
RefMet 策展名称来源 70 万+ 名称 / 3,500+ 研究 2026-09（RefMet 页）
非靶向特征总数 4,500,000+ 2026-09（检索门户页）
提交国家数 60 2026-09（官网首页）
主论文被引 635+ 2026-06-13（Europe PMC，经 Database Commons 转录）
非靶向研究数 890+ 2026-09（检索门户页）
非靶向 LC-MS 分析数 1,500+ 2026-09（检索门户页）

§4.4 数据层级

层级关系为 Project（PR，提交与 DOI 单元）→ Study（ST，实验设计单元）→ Analysis（AN，平台运行单元）→ Sample（样本，因子挂载点）→ Metabolite/Feature（代谢物或 m/z 特征）→ Measurement（数值）。对 AI 工程的含义：① 同一 Study 的多个 Analysis 共享样本设计但特征空间不同（不同极性、不同色谱），合并需在代谢物名层面对齐；② 样本 ID 只在 Study 内唯一，跨 Study 拼接时必须拼上 Study 前缀；③ Measurement 层的单位与归一化属于 Analysis 属性，不可跨层假设一致。

工程落点：把三级 ID 编进数据路径（§4.0 目录树即按此组织），主外键在数据卡中声明——study_id 是跨表 join 的唯一安全键，analysis_id 是特征空间的命名空间，sample_id 必须与 study_id 组成复合键才能全局唯一。这套约定让 §6.1 的缓存命名、§5 的分组划分、§8.3 的评测协议共享同一个键体系，避免各模块各自造键。

§4.5 缺失值与信息性缺失

缺失形态 语义 推荐处理
空单元格（靶向定量表） 低于检出限或未测 按 LOD/2 或携带 MNAR 假设的插补；禁止当 0 直接均值
空字符串（refmet_name） 非靶向未命名特征 保留为特征 ID（m/z_RT 键），不参与命名层对齐
因子列空值 该样本未记录该因子 建模时整列剔除或单列"unknown"类别并报告比例
缺内标响应 批次质量风险 结合 QC 样本变异决定是否剔除整批
QC/空白样本出现于因子表 质控通道混入 先用于漂移校正，校正后从建模集剔除（坑点 6）
同代谢物多行（多加合物） 化学同一性多次测量 以 refmet_name 聚合或按加合物分层（坑点 8）

官方未提供"信息性缺失"标准编码表；上述语义为代谢组学通行约定与本页建议的合成，使用时应在数据卡片中声明。

§5 数据划分与使用建议

官方划分：不存在。平台是存储库，发布的是完整研究，不做训练/测试切分。这把划分责任完全交给分析者，也把"划分即研究设计"的自由度交给了分析者。

社区惯例：以 Study（乃至 Analysis）为不可分割分组单元；跨 Study 的 meta 分析将"研究"视作独立试验，用随机效应模型汇总，而非把所有样本混进一个训练集。这一惯例在代谢组方法学文献中高度一致，可直接写进论文方法节。

划分策略建议：单研究建模用分层 K 折交叉验证（保证各折因子类比例一致）；多研究建模用 Leave-One-Study-Out（LOSO）评估跨队列泛化，这是最能暴露批次效应的协议。

泄漏风险（§5.3 重点）：① 同一 Study 的重复样本/技术重复分属训练与测试折，是最高频泄漏；② QC 池样本混入训练集会让模型学到批次而非疾病；③ 按样本随机切分多时点研究会把同一受试者的前后时点劈开。三条都指向同一原则：切分键必须落在受试者/研究层。一个具体例子：某研究对同一批受试者采集了血浆与尿液两种基质，若按样本随机切分，同一受试者的两种基质样本会分属训练与测试集，模型学到的其实是"个体代谢指纹"而非疾病信号。

交叉验证建议：嵌套 CV 选择超参；在 LOSO 外再保留一个时间上更晚发布的 Study 作最终外部测试，模拟真实前瞻场景。折数的选择与样本量相关：单研究几十个样本时 5 折已是方差-偏差的合理折中，少于 30 样本建议重复 5×2 交叉验证以稳定估计。

外部验证建议：优先选取平台、色谱与内标不同的另一 Study 作外部集；验证结果应报告按 RefMet 对齐后的特征覆盖率——覆盖率过低时外部验证结论无效。

以下为 LOSO 划分的最小实现（与 §5.3 泄漏原则一一对应）：

# Leave-One-Study-Out：以 Study 为折单元，杜绝同研究样本跨折泄漏
from sklearn.model_selection import LeaveOneGroupOut
from sklearn.linear_model import LogisticRegression
from sklearn.preprocessing import StandardScaler
from sklearn.pipeline import make_pipeline
import numpy as np

# X: 合并矩阵（已按 §6.3 预处理）；y: 标签；groups: 每行的 study_id
logo = LeaveOneGroupOut()
scores = []
model = make_pipeline(StandardScaler(), LogisticRegression(max_iter=2000))
for tr, te in logo.split(X, y, groups):
    model.fit(X[tr], y[tr])
    scores.append(model.score(X[te], y[te]))
print(f"LOSO 准确率：{np.mean(scores):.3f} ± {np.std(scores):.3f}"
      f"（{len(scores)} 折，每折=一整项研究）")
# 判读：折间方差大 = 批次效应强；某折显著差 = 该研究平台/协议离群

§6 AI 就绪指南

§6.0 云端快速启动

REST API 无需注册与密钥，任何带 Python 3.9+ 的云端环境（Colab、SageMaker Studio Lab、容器工作区）均可直接运行本节代码；仅需 requests、pandas、scikit-learn 等常规包，无重型依赖。原始谱图深处理（如 Thermo .raw 转 mzML）需自备 ProteoWizard 或云端转换服务，本节定量建模路线不依赖它。

最小连通性自检：浏览器或 curl 打开 https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/summary，若返回 JSON 即链路正常；若超时，多半是网络策略拦截了未鉴权的 GET 请求，检查代理白名单即可，本库不存在账号/配额问题。

§6.1 快速上手

以下代码演示"拉取一项研究的因子表与定量矩阵"的最小闭环。

# ── 目录结构预期 ────────────────────────────────────────────
#   ./mw_cache/   REST 缓存（自动创建）：study 级 JSON 落地于此
# ── data_root 拼接关系 ─────────────────────────────────────
#   data_root = "https://www.metabolomicsworkbench.org/rest"
#   具体端点 = f"{data_root}/study/study_id/{study_id}/{output}"
#   本地缓存路径 = f"./mw_cache/{study_id}_{output}.json"
# ── 最小可用子集 ───────────────────────────────────────────
#   任选一项公开靶向研究（本例 ST000009，混合餐耐受试验）
import json, pathlib, requests
import pandas as pd

DATA_ROOT = "https://www.metabolomicsworkbench.org/rest"
CACHE = pathlib.Path("./mw_cache"); CACHE.mkdir(exist_ok=True)

def mw_get(path: str) -> dict:
    """GET {DATA_ROOT}/{path}，JSON 落盘缓存后返回 dict。"""
    fname = CACHE / (path.replace("/", "_") + ".json")
    if not fname.exists():
        r = requests.get(f"{DATA_ROOT}/{path}", timeout=60)
        r.raise_for_status()
        fname.write_text(r.text, encoding="utf-8")
    return json.loads(fname.read_text(encoding="utf-8"))

study_id = "ST000009"
factors  = mw_get(f"study/study_id/{study_id}/factors")   # 因子/标签
metabs   = mw_get(f"study/study_id/{study_id}/metabolites")  # 命名代谢物
print(len(metabs), "个命名代谢物；因子结构：", json.dumps(factors)[:200])

第二条常用路径是质量数检索（moverz context）：给定 m/z、加合物与容差，直接反查库内化合物，适合在谱图处理早期做候选归属：

# moverz：在 MW 化合物库中检索 m/z=635.52（M+H，容差 0.5 Da）的候选
hits = mw_get("moverz/MB/635.52/M+H/0.5")
# 数据库可选：MB（MW 库）/ LIPIDS（脂质）/ REFMET（RefMet）
# 常用加合物：M+H、M+Na、M+K（正离子）；M-H、M-2H（负离子）
print(json.dumps(hits, ensure_ascii=False)[:300])
# 产出：候选化合物的 regno/名称/精确质量——接 refmet context 可继续取分类

§6.2 数据获取

获取方式 入口 适用 备注
网页下载 https://www.metabolomicsworkbench.org/data/browse.php 单研究 每分析附原始文件与结果表
REST API https://www.metabolomicsworkbench.org/rest/ 批量结构化 默认 JSON，可加 /txt；文档 v1.2（2025-07-22）
FTP ftp://www.metabolomicsworkbench.org/ 全库镜像 适合批量原始文件
mwtab Python 包 PyPI mwtab（v2.0.0，BSD-3-Clear） 批量解析校验 官方维护 
# 批量枚举全部公开研究，筛选人源 LC-MS 研究
avail = mw_get("study/study_id/ST/available")     # 全库公开研究清单
human_ms = [s for s in avail
            if s.get("species") == "Homo sapiens" and s.get("analysis_type") == "LC-MS"]
print(f"公开研究 {len(avail)} 项；人源 LC-MS {len(human_ms)} 项")
# 下载某分析 datatable（样本×代谢物矩阵）与 mwTab 全量元数据
an = human_ms[0]["analysis_id"]
dt = mw_get(f"study/analysis_id/{an}/datatable")
mt = mw_get(f"study/analysis_id/{an}/mwtab")
# 提示：原始谱图不走 REST——从分析页"Uploaded data"或 FTP 获取

原始谱图的批量获取走 FTP 或分析页直链，命令行示例：

# 单分析原始文件目录示例（目录名以分析页实际给出为准）
curl -O "https://www.metabolomicsworkbench.org/data/DRCCMetadata.php?Mode=Study&StudyID=ST001231"
# FTP 全库浏览（交互式）：
#   ftp ftp://www.metabolomicsworkbench.org/
#   ls / Data 目录按 Study ID 组织，原始文件位于对应 Analysis 子目录
# 大规模镜像建议：先抓 rest/study/study_id/ST/available 生成 ID 清单，
# 再按清单逐 Study 同步，并以 download_log.json 记录时间与文件哈希

无需注册即可完成上述全部下载；仅提交方需要在 Upload 入口注册登录。若为机构镜像，建议与官方联系确认批量抓取的礼貌间隔（官方支持邮箱 help@metabolomicsworkbench.org）。

§6.3 预处理全流程

流程：格式解析 → RefMet 名称对齐 → 单位/归一化核查 → 缺失值处理 → 变换稳定化。

# 第 1 步：datatable → DataFrame（首列为样本，其余列为代谢物）
df = pd.DataFrame(dt["data"]) if isinstance(dt, dict) else pd.DataFrame(dt)
df = df.set_index(df.columns[0])
# 第 2 步：列名批量映射到 RefMet 标准名（REST match 端点）
def to_refmet(names: list[str]) -> dict:
    out = {}
    for n in names:                       # 逐名查询；批量接口见 RefMet 页
        try:
            out[n] = mw_get(f"refmet/match/{n}/name").get("refmet_name", n)
        except Exception:
            out[n] = n                    # 查询失败时保留原名
    return out
colmap = to_refmet(list(df.columns))
df = df.rename(columns=colmap)
# 第 3 步：核查量纲——同列数量级差异 >1e4 提示混入峰面积与浓度
scale = df.abs().max()
print(scale[scale / (scale.min() + 1e-12) > 1e4].head())
# 第 4 步：缺失值按 LOD/2 处理（MNAR 语义），禁止当 0
df = df.fillna(df.min() / 2)
# 第 5 步：log2 变换 + 每样本中位数归一化（PQN 的简化替代）
import numpy as np
df = np.log2(df + 1)
df = df.sub(df.median(axis=0), axis=1)
print(df.shape)                            # (样本数, 代谢物数)

注意：第 2 步逐名查询仅用于演示；生产环境请改用官方批量映射表单、RefMet R 包或 refmet/all 全表缓存，避免数千次 HTTP 往返。

全表缓存路线补充：refmet/all 返回整库名称与元数据（体积在百 MB 量级），落地为本地 Parquet 后做内存内 join，映射吞吐可从"秒级/名"提升到"百万名/分钟"；代价是需要跟踪 RefMet 词表版本并在更新时重建缓存（见 §7.6 命名漂移）。

QC 过滤与批次诊断（衔接坑点 6）：

# 第 6 步：剔除 QC/空白与无标签样本，并输出批次诊断
def drop_qc(df: pd.DataFrame, labels: pd.Series) -> tuple[pd.DataFrame, pd.Series]:
    keep = ~labels.index.str.upper().str.contains("QC|BLANK|POOL")
    return df.loc[keep], labels.loc[keep]

df2, y2 = drop_qc(df, labels)
# 批次诊断：每代谢物在 QC 内的 CV>30% 视为不稳，整列剔除
qc_cv = df.loc[labels.index.str.upper().str.contains("QC")]
stable_cols = (qc_cv.std() / qc_cv.mean().abs().clip(lower=1e-9) < 0.3)
df2 = df2.loc[:, stable_cols[stable_cols].index]
print(f"建模集：{df2.shape[0]} 样本 × {df2.shape[1]} 稳定代谢物")
# 注意：QC 行是否存在及其命名以该研究元数据为准，先查再删

§6.4 PyTorch DataLoader

# Dataset：把一份分析 datatable 封装成 (特征向量, 标签) 监督样本
# 输入依赖：§6.3 产出的 df（样本×代谢物，已对齐 RefMet 并插补）
# 标签来源：factors JSON 解析出的样本级因子（此处以二因子研究为例）
import torch
from torch.utils.data import Dataset, DataLoader
from sklearn.preprocessing import LabelEncoder

class MWStudyDataset(Dataset):
    """一次分析的数据集；factor_col 为因子表中的分组列名。"""
    def __init__(self, df: pd.DataFrame, labels: pd.Series):
        self.X = torch.tensor(df.to_numpy(dtype="float32"))
        self.y = torch.tensor(LabelEncoder().fit_transform(labels))
    def __len__(self):  return len(self.X)
    def __getitem__(self, i): return self.X[i], self.y[i]

# labels 构造示意：从 factors 输出按 SAMPLE_NAME 对齐（真实键名随研究而异，
# 务必先打印 factors JSON 核对结构，切勿假设固定列名）
# labels = pd.Series(..., index=df.index)
# 因子对齐三步：① 打印 factors JSON 确认样本键与因子名；
#              ② 按样本键 intersect(df.index, 因子表索引)；
#              ③ 缺因子样本先剔除并计数，写进实验日志
ds = MWStudyDataset(df, labels)            # ← labels 由因子表对齐而来
g = torch.Generator().manual_seed(42)
train = DataLoader(ds, batch_size=64, shuffle=True, generator=g)
model = torch.nn.Sequential(
    torch.nn.Linear(ds.X.shape[1], 128), torch.nn.ReLU(),
    torch.nn.Dropout(0.3), torch.nn.Linear(128, len(torch.unique(ds.y))))
for xb, yb in train:                       # 冒烟测试一轮前向
    print(model(xb).shape); break

该 Dataset 的设计取舍：以"一分析一数据集"为边界（不跨分析拼接），特征维度即该分析的命名代谢物数（通常 100-1,000 维），样本量通常在几十到几百——这一量纲下，正则化线性模型仍是首选，深度模型仅在有跨研究大矩阵时才值得投入（且必须先过 §6.5 坑点 4）。

工程注意：labels 的构造是这套代码里唯一没有"官方固定格式"的环节——因子键名完全由提交者决定。务必保留 §4.2 的审计步骤作为 DataLoader 的前置关卡，把"键名假设错误"拦截在建模之前而不是训练报告之后。

§6.5 八大坑点

⚠️ 坑点 1：Project/Study/Analysis 三级标识混用（分类：标签理解）

问题：把 Study ID 当作最小数据单元或引用单元，实际同一 Study 下多个 Analysis（不同极性、不同色谱）特征空间完全不同；引用时只给 Study ID 则无法定位具体数据集。
症状：合并后矩阵行数翻倍、同一样本出现两套互相冲突的列；论文被审稿人要求补 Analysis ID；缓存目录里同一数据存了两份不同名字的文件。
解决：

  1. 简单方法：所有 join 与引用一律落到 analysis_id 粒度，Study 仅作分组键。
  2. 进阶方法：按官方引用模板同时输出 Project ID + Project DOI（前缀 10.21228），代码中用 {study_id}/{analysis_id} 复合键命名缓存文件。
  3. SOTA 方法：在数据卡片中登记三层谱系（PR→ST→AN），用 rest/study/study_id/ST…/analysis 自动生成层级清单供审计。
    参考：https://www.metabolomicsworkbench.org/about/howtocite.php

⚠️ 坑点 2：RefMet 名称映射不是全量覆盖（分类：预处理陷阱）

问题：官方明确说明"许多代谢组实验产生的名称目前无法映射到 RefMet"；脂质等压物种（PC 34:1、TG 54:2）按设计就不对应唯一结构，强行用 InChIKey join 会丢行或错并。
症状：映射后特征数骤减；跨研究矩阵里同一脂质在 A 研究叫 PC 34:1、B 研究叫 PC(34:1) 而没对上。
解决：

  1. 简单方法：映射前后统计覆盖率并写进报告；未映射列保留原名单独成组。
  2. 进阶方法：先用 refmet/match/{name}/name 规范化，再做大小写、空格与括号风格归一（PC(34:1) ↔ PC 34:1），对脂质采用"类 + 总碳：总双键"缩写正则归一。
  3. SOTA 方法：以四层分辨率显式建模注释层级（唯一结构 / 系统命名 / 总组成 / 类级），把层级作为特征元信息输入模型或用作分层评估。
    参考：https://www.metabolomicsworkbench.org/databases/refmet/index.php；Fahy E, Subramaniam S, 2020, Nature Methods. https://doi.org/10.1038/s41592-020-01009-y

⚠️ 坑点 3：非靶向研究没有"代谢物×样本"命名矩阵（分类：工程陷阱）

问题：对非靶向 Study 调用命名代谢物端点只会得到极少或空结果——其主数据是 m/z-RT 特征，存于另一套输出里，特征名可能为空。
症状：脚本在非靶向研究上返回空 DataFrame，或在 metabolites 端点拿到远小于预期的列数。
解决：

  1. 简单方法：先调 number_of_metabolites 判断命名特征数，接近 0 即走特征管线。
  2. 进阶方法：改用 untarg_studies + untarg_data 端点拉 m/z-RT 特征表，用 mz@RT 字符串作特征主键。
  3. SOTA 方法：把非靶向特征身份定义为"分析 ID + 容差窗内的 m/z/RT"三元组，用官方 450 万+ 特征检索门户做跨研究特征对齐，再决定是否值得注释。
    参考：https://www.metabolomicsworkbench.org/tools/mw_rest.php（REST v1.2 文档）

⚠️ 坑点 4：跨研究直接拼接定量表（分类：偏倚陷阱）

问题：各研究的 value 列语义不同——绝对浓度（μM）、原始峰面积、内标归一化面积、分箱 NMR 面积混杂；仪器、色谱柱与内标随研究而变，直接 concat 等于把"批次"当成了"生物学"。
症状：合并集上模型准确率虚高；LOSO 评估中性能崩塌；PCA 图按研究而不是按疾病分簇。
解决：

  1. 简单方法：研究内标准化（每列 z-score 或样本中位数归一）后再拼接，且只拼接语义一致的列（浓度对浓度）。
  2. 进阶方法：按 RefMet 对齐后采用比值型变换（如对每样本除以 QC 中位数），并在模型中把 Study 作为随机效应或协变量。
  3. SOTA 方法：ComBat 类批次校正或分层多任务学习（每 Study 一头、共享底座），用 LOSO 协议报告跨研究泛化。
    参考：Thompson PT & Moseley HNB, 2026, Metabolites. https://doi.org/10.3390/metabo16010076

⚠️ 坑点 5：缺失值不是随机的（MNAR/LOD 截断）（分类：预处理陷阱）

问题：代谢组缺失主要来自"信号低于检出限"，与浓度本身相关，属 MNAR；把缺失当 0 或做面向 MAR 的均值/多重插补都会系统性压低低丰度代谢物的方差。
症状：插补后出现人为双峰分布；低丰度脂质全库"消失"；ROC 表现对插补方式异常敏感。
解决：

  1. 简单方法：右删失语义用"列最小值的一半"（LOD/2 近似）填充，并记录各列缺失率。
  2. 进阶方法：缺失率超阈值（如 20%）的列整列剔除；其余用 QRILC（分位回归左删失插补）或 KNN-TN 等专为删失设计的算法。
  3. SOTA 方法：在模型中显式加入"是否缺失"指示通道，让下游学习删失模式本身；报告插补敏感性分析。
    参考：https://www.metabolomicsworkbench.org/data/faq.php（官方仅规定交最终结果，插补策略归分析者）

⚠️ 坑点 6：把 QC 池与空白样本混入训练集（分类：数据泄漏）

问题：提交规范鼓励上交质控样本（pooled QC、方法空白），其因子表中可能没有疾病标签或被标为 QC；混入训练集会让模型学到仪器漂移而非生物学信号。
症状：验证集性能极好但外部验证失效；特征重要性头部全是内标与 QC 指示峰。
解决：

  1. 简单方法：按因子表过滤，剔除无疾病标签或显式标注 QC/Blank 的样本后再划分。
  2. 进阶方法：保留 QC 用于信号校正（如 LOESS 漂移校正），校正后从建模集移除；训练/测试划分键落在生物学重复（受试者）层。
  3. SOTA 方法：在 Exemplary Studies 中优先选"样本名与原始文件一一映射、含对照"的研究，天然规避该坑；用 QC 变异系数（CV%）作为数据集准入门槛。
    参考：https://www.metabolomicsworkbench.org/data/DRCCStudySummary.php?Mode=HighlightStudies

⚠️ 坑点 7：引用了尚未解禁的 Study ID（分类：评估误用）

问题：文献或预印本里出现的 ST 编号可能仍处 embargo 期（536 项在库内未公开，截至 2026-09-15），脚本按 ID 抓取会失败或拿到空响应，误判为"库损坏"。
症状：REST 返回空/错误但 ID 在论文里"存在"；复现实验同事报告"下载不到你说的数据"。
解决：

  1. 简单方法：抓取前用 rest/study/study_id/{ST}/available 过滤，只处理公开集合。
  2. 进阶方法：批处理脚本记录"论文引用 ID vs 库内可得"差集，embargo 项进入重试队列（官方口径：资助结束后 1 年强制解禁）。
  3. SOTA 方法：为复现包内置数据可得性清单（manifest），标注每项数据的 DOI、获取日期与解禁预期，审稿与交接零歧义。
    参考：https://www.metabolomicsworkbench.org/data/faq.php（Embargo Times 节）

⚠️ 坑点 8：跨平台、跨极性合并导致特征双计（分类：评估误用）

问题：同一 Study 常同时含正/负离子两个 Analysis 与 NMR 平台；同一代谢物（如柠檬酸）在多平台重复出现，简单纵向拼接后该代谢物权重被放大数倍。
症状：通路富集被高丰度重复分子主导；不同平台的同 名代谢物相关系数异常低，暴露平台间系统偏差。
解决：

  1. 简单方法：以 refmet_name 去重，多平台取均值或按平台置信度择一。
  2. 进阶方法：按平台分组建模后 stacking 融合；或对每个 RefMet 名保留"平台数"作权重元信息。
  3. SOTA 方法：多视图学习（每平台一个视图 + 跨视图对齐损失），用结构相似性网络（官方 RDKit 工具）先量化平台间化学覆盖重叠再决定融合策略。
    参考：https://www.metabolomicsworkbench.org/databases/refmet/name_to_refmetS_form.php（结构相似性网络工具）

§6.6 数据增强（安全✅/危险❌）

  • ✅ 安全：对谱图级输入做轻微 m/z 轴漂移扰动（±0.01 Da 内）、保留时间窗抖动；对定量表做样本级 mixup（同类内插值）；按代谢物模块（同通路）做特征 dropout，模拟测量波动。
  • ✅ 安全：跨研究增强——用另一 Study 的批内方差估计对目标集加高斯噪声，间接模拟批次扰动。
  • ✅ 安全：对缺失模式做保持 MNAR 的掩码增强（只在低丰度列按原缺失率掩码）。
  • ❌ 危险：对浓度矩阵做镜像/旋转变换（化学量纲无意义）；随机缩放单列数值（破坏内标归一化关系）；对缺失模式随机重采样（破坏 MNAR 结构）；把 QC 样本当增强素材混入训练分布。
  • ❌ 危险：跨类别 mixup——不同疾病表型的样本插值会产生生物学上不存在的"中间表型"，污染决策边界。

§6.7 模型推荐表

任务 推荐起点 升级路线 备注
二分类标志物建模 弹性网逻辑回归 XGBoost + SHAP 高维小样本，线性模型方差低
疾病分型 PCA+KMeans 基线 变分自编码器 先看是否按 Study 分簇（坑点 4 自检）
跨研究泛化 LOSO + 随机效应汇总 多任务学习/ComBat 报告每折特征覆盖率
脂质组 LIPID MAPS 分类先验 图神经网络（分子图） 结构相似性网络可作先验边
NMR 绝对定量 PLS 回归 注意力机制谱图模型 分箱数即特征数，直接可训
跨研究 meta 分析 随机效应模型（研究层） 贝叶斯分层模型 效应量方向一致性优先于显著性
非靶向特征注释 m/z 精确质量匹配 + moverz MS/MS 谱图检索迁移 无名特征不得进入命名层结论

§6.8 硬件需求表

场景 CPU 内存 存储 GPU
REST 定量表建模 4 核 8 GB 50 GB 不需要
百级研究批量 meta 分析 16 核 32 GB 500 GB 可选
全库镜像 + 原始谱图 16 核 64 GB 数十 TB（保守预留，以 FTP 实测为准） 不需要
谱图深度学习（mzML 处理后） 16 核 64 GB 2 TB 1×24 GB
RefMet 全表映射服务 4 核 16 GB 20 GB 不需要

内存要点：refmet/all 全表与百级研究 datatable 缓存均在 GB 量级，32 GB 内存可覆盖绝大多数批量场景；瓶颈通常在网络往返——批量任务务必落地缓存（§6.1 的 mw_cache 模式）。

§6.9 评估指标代码

# 分类（case/control）+ 回归（浓度预测）双指标；不平衡场景看 AUPRC
from sklearn.metrics import roc_auc_score, average_precision_score
from sklearn.model_selection import StratifiedKFold, cross_val_score
import numpy as np

def eval_cls(model, X, y, seed: int = 42) -> dict:
    cv = StratifiedKFold(5, shuffle=True, random_state=seed)
    auc = cross_val_score(model, X, y, cv=cv, scoring="roc_auc")
    ap  = cross_val_score(model, X, y, cv=cv, scoring="average_precision")
    return {"AUROC": float(np.mean(auc)), "AUPRC": float(np.mean(ap)),
            "prevalence": float(np.mean(y))}   # 类平衡基线对照
# 回归任务：report RMSE 与 R²，且按 Study 分组再评一次（坑点 4 自检）
# 跨研究泛化：外层 LOSO 循环，内层用 eval_cls；每折输出特征覆盖率
def eval_loso(model, X, y, groups) -> dict:
    from sklearn.model_selection import LeaveOneGroupOut
    aucs = []
    for tr, te in LeaveOneGroupOut().split(X, y, groups):
        model.fit(X[tr], y[tr])
        if len(np.unique(y[te])) > 1:          # 折内单类时跳过该折
            aucs.append(roc_auc_score(y[te], model.predict_proba(X[te])[:, 1]))
    return {"LOSO_AUROC": float(np.mean(aucs)), "n_folds": len(aucs)}
# 回归（如浓度预测）：用 RMSE/R² + 分组留一，报告中必须写明单位语义
from sklearn.metrics import mean_squared_error, r2_score
def eval_reg(model, X, y, groups) -> dict:
    from sklearn.model_selection import LeaveOneGroupOut
    rmse, r2 = [], []
    for tr, te in LeaveOneGroupOut().split(X, y, groups):
        model.fit(X[tr], y[tr])
        pred = model.predict(X[te])
        rmse.append(mean_squared_error(y[te], pred) ** 0.5)
        r2.append(r2_score(y[te], pred))
    return {"LOSO_RMSE": float(np.mean(rmse)), "LOSO_R2": float(np.mean(r2))}

§6.10 MLOps 笔记

  • 数据版本化：以"抓取日期 + Study/Analysis ID 清单哈希"作数据集版本号；REST 是活接口，昨天与今天的 available 集合可能不同，任何实验必须冻结快照。
  • 引用即溯源：生产特征库中每张表登记 Project DOI（10.21228/*），审计与论文回溯都能闭环。
  • 监控：线上模型监控 RefMet 特征覆盖率与 QC-CV 两个哨兵指标，覆盖率下降提示上游注释漂移。
  • 复现包：交付时附 manifest（数据 ID、获取日期、mwTab 缓存哈希、环境锁文件），embargo 项单列（见坑点 7）。
  • 速率与礼貌：REST 无鉴权也无公开限流说明，批量任务按秒级间隔串行 + 本地缓存即可，避免对公共服务造成压力；镜像级需求改走 FTP。
  • ** Schema 演进**：mwTab 格式与 REST 输出偶有字段增补（如 v1.2 的 untarg 系列端点），解析层应按"缺字段降级"编写，升级时跑一轮全量回归。

§7 质量评估与局限性

§7.1 已知偏倚

偏倚类型 描述 严重程度 缓解措施
机构与地域偏倚 提交集中于美国资助核心设施，60 国中少数国家贡献多数研究 中 LOSO 按机构分组评估；结果外推时声明来源结构
平台偏倚 LC-MS（尤其 Thermo 平台）占比远高于 GC-MS 与 NMR 中 按平台分层建模；跨平台结论仅在 RefMet 对齐列上成立
注释偏倚 靶向研究注释强、非靶向研究大量特征无名 高 区分注释层级（§3.5），无名特征不进入命名层结论
发表偏倚 embargo 政策与论文驱动提交，阴性结果研究相对少 低-中 把握方向性结论时纳入预注册研究证据
存活者偏倚（批次质量） 元数据不全或 QC 失败的提交可能未入库 低 优先选用 Exemplary Studies
物种构成偏倚 非人源研究占比可观，直接混合建模会把物种差异当疾病信号 中 建模前按 species 过滤；跨物种结论单列
时间偏倚 早期研究（2013-2016）仪器与协议与近年不可比 中 按发布年代分层评估；关键结论复验于新研究
单位语义偏倚 浓度/峰面积/归一化值混在同一 value 语义下 高 跨研究只用 RefMet 对齐后的相对方向，不比绝对量

§7.2 标注质量

代谢物注释质量的分层已在 §3.5 展开。平台侧的质量保障是流程性的：策展团队核验元数据完整性与原始/处理数据对应关系，处理周期约 30 天；官方以 Exemplary Studies（8 项标准）树立标杆，但未公布全库统一的注释置信度字段——提交者侧的注释等级（Level 1/2/3）以各研究元数据自述为准。使用建议：靶向浓度 > 保留时间+谱图确认注释 > 精确质量推测注释 > 无名特征，四级分开建模、分开报告。

对"标注者一致性"的具体操作建议：在同一研究内，用技术重复样本的变异系数（CV）代理测量一致性；在同一代谢物跨研究层，比较效应方向的一致率（如各研究中病例相对对照的升降方向）。两个指标都不需要额外标注，全部可从公开数据算出，是低成本的质量仪表盘。

§7.3 泛化性

目标场景 失效风险 证据与理由
欧美临床队列内复现 低 库内主要队列来自欧美核心设施，同平台复现文献充分
跨平台（MS↔NMR）迁移 高 特征空间与量纲完全不同；仅 RefMet 命名层可对话
低资源设备/床旁检测迁移 高 库内多为高分辨实验室平台，谱图与床旁仪器差异大
跨物种外推（动物→人） 中-高 NAR 主论文即以跨物种比较为目标，但代谢物丰度物种差异显著
儿科/孕产人群 中 库内此类专项研究相对少，采样前应先统计因子分布
低丰度代谢物建模 高 LOD 截断使低丰度区间信息量低（坑点 5），需删失感知方法

§7.4 伦理

人源研究数据由提交方完成脱敏后提交，公开数据不含直接标识符；涉及人体样本的 Common Fund 数据受 NIH 数据共享政策约束，embargo 规则见 §6.5 坑点 7。平台托管 HHEAR 暴露组专项数据，引用时须按官方模板注明 NIEHS 资助（U2CES026555）。

二次使用者仍需遵守各自来源研究的伦理边界：本库许可证层面开放，不等于豁免下游的伦理审查义务——对样本级数据尝试再识别、将公开数据用于未经许可的商业诊断宣称、或绕过 embargo 期获取数据，均不属于合法使用。涉及新增人体受试者的后续研究，应重新走本机构伦理审查，本库的开放状态仅覆盖既有数据的二次分析。

§7.5 公平性

全库未强制收集受试者种族/族群字段，公平性审计只能在"逐研究元数据"粒度进行；机构与地域偏倚（§7.1）意味着模型在代表性不足人群上的表现无法从库内证据直接支撑。

建议：建模报告必须附研究来源清单与样本量分布表；涉及健康差异研究的结论，应寻找专门队列外部验证而非依赖本库。对以中国人群为目标的应用，库内已有浙江大学、中山大学、复旦大学附属中山医院等机构提交的研究可供起点，但覆盖病种与样本量有限，正式建模仍应回到国内专队数据。

§7.6 数据漂移

两类漂移需要监控：集合漂移——新研究持续入库（2024-04 至 2025-10 增长 50%），available 集合随时间扩大，训练时冻结的 ID 清单会与线上不一致；仪器漂移——同研究内 QC 池的信号漂移是谱图数据的固有噪声，提交方报告的校正方法记录在元数据中。

还有第三类更隐蔽：命名漂移——RefMet 词表本身在演进（分类层级更新、脂质缩写修订），同一原始名在不同时间点映射到的 RefMet 名可能变化。对策是把"原始名 → RefMet 名"的映射结果随数据快照一起落盘，而不是每次运行时重新在线映射；映射表版本也纳入 manifest。工程对策汇总见 §6.10：冻结快照 + 版本哈希 + RefMet 覆盖率哨兵 + 映射表落盘。

§7.7 DAIMS 24 项核查

# 检查项 状态 说明
1 宽格式 ✅ datatable 即样本×代谢物宽矩阵，可直接入模
2 唯一标识 ✅ PR/ST/AN 三级 ID + 样本名，主键体系完备
3 特殊字符 ⚠️ 代谢物名含括号/逗号/连字符，CSV 解析需转义处理
4 重复行 ✅ 策展后无重复记录问题；技术重复有独立命名
5 缺失编码 ⚠️ 空单元格语义因研究而异（未测/低于 LOD），无全库统一码
6 标签标识 ✅ 因子表（factors）显式给出分组变量与取值
7 罕见类分组 ⚠️ 小类别未做官方合并，需分析者自行处理
8 偏倚评估 ⚠️ 偏倚存在（§7.1）但官方未提供评估报告
9 数据字典 ✅ REST 文档 v1.2 + mwTab 规范 + 教程完整
10 信息性缺失解释 ❌ 官方未提供缺失语义标准说明
11 设备记录 ✅ 仪器/色谱/极性等参数在分析元数据中强制记录
12 共线性 ⚠️ 脂质物种高度相关，官方未提供共线性处理指引
13 编码映射 ✅ RefMet + KEGG/PubChem/HMDB/CHEBI 等外部 ID 映射
14 时间戳处理 ⚠️ 发布/embargo 日期清晰，但样本采集时间戳常缺
15 划分建议 ❌ 无官方训练/测试划分（存储库性质使然）
16 泄漏讨论 ⚠️ 社区有共识（Study 层切分），官方文档未专章讨论
17 标签分布 ✅ factors/MetStat 端点可程序化获取分布
18 测量偏倚 ⚠️ 批次/平台效应真实存在，需分析者自行校正
19 外部验证建议 ⚠️ 无官方模板；同行评审研究提供了可循先例
20 版本记录 ✅ Project DOI 快照 + 研究发布日期，可稳定追溯
21 预处理脚本 ✅ mwtab（Python）、RefMet（R）、Shiny App 官方提供
22 合规要求 ✅ Terms of Use、数据共享政策、引用模板齐备
23 多模态对齐 ⚠️ MS/NMR 仅在 RefMet 命名层对齐，无样本级跨模态对齐保证
24 去标识化 ✅ 公开数据经提交方脱敏 + 策展复核，无直接标识符

DAIMS 评分：17.0 / 24（12 项 ✅、10 项 ⚠️、2 项 ❌；⚠️ 计 0.5 分）

评分解读：17.0 分处在"结构化程度优秀、但统计口径需自建"的区间。标识体系、数据字典、外部 ID 映射、工具链四项达到存储库类数据集的第一梯队；失分集中在存储库与基准集的属性差异——没有官方划分、没有缺失语义标准、没有跨研究测量偏倚校正，这些本就需要分析者补齐，属于"用研究补齐"而非"数据缺陷"。

对你意味着什么：可以直接把 REST 定量路线接入生产特征管道（当天即可跑通），但必须自建三件套：① 以 Study 为键的划分器与 LOSO 评估器；② 缺失/注释分层的数据字典（继承 §4.5 与 §3.5 的框架并按你的研究集实例化）；③ 冻结快照与 DOI 登记的版本管理（§6.10）。做完这三件事，本库的 AI 就绪体验接近一个精心维护的数据仓库；不做，则会在跨研究合并的第一周踩满 §6.5 的坑点 4、5、8。

§7.8 外部验证矩阵

本库无基准式外部验证传统（它是存储库而非榜单）。下表仅收录经同行评审、与"跨研究可复用性"直接相关的证据：

外部数据集/场景 来源机构 评估任务 性能指标 相对内部变化 关键发现
全库 mwTab 合规性审计 肯塔基大学 Moseley 实验室 格式校验与 FAIR 评估 策展问题检出与修复（定性） 不适用（非预测任务） mwtab 2.0 校验全库数据集，提升策展与复用质量 [Thompson PT & Moseley HNB, 2026, Metabolites. https://doi.org/10.3390/metabo16010076]
RefMet 命名统一性 UCSD/SDSC 跨研究名称归一 四层分辨率覆盖率（官方口径 70 万+ 名称源） 不适用（命名任务） 名称统一是跨研究 meta 分析的前提条件 [Fahy E, Subramaniam S, 2020, Nature Methods. https://doi.org/10.1038/s41592-020-01009-y]
跨物种平台互操作 NIH Common Fund 核心设施 MS/NMR 跨 20+ 物种整合 结构-测量关联覆盖（定性） 不适用（基础设施验证） 主论文验证了跨物种、跨平台数据整合可行性 [Sud M et al., 2016, Nucleic Acids Research. https://doi.org/10.1093/nar/gkv1042]

§8 基准性能与生态

§8.1 排行榜（任务型代表研究）

Metabolomics Workbench 为存储库，不存在官方模型排行榜。下表列出基于本库或与本库核心组件直接相关的代表性同行评审工作；各行任务与指标不同，数值不可直接比较：

排名 模型/工作 任务与结果 年份 关键技术 完整引用 代码
1 mwtab 2.0 校验管线 全库 mwTab/JSON 数据集的质量校验与 FAIR 评估 2026 mwTab 解析、批量校验、文件状态网站 Thompson PT, Moseley HNB, 2026, Metabolites 16(1):76. https://doi.org/10.3390/metabo16010076 PyPI mwtab
2 RefMet 命名体系 70 万+ 名称 → 四层标准化命名的建立与映射 2020 分析化学中心命名、LIPID MAPS/ClassyFire 分类 Fahy E, Subramaniam S, 2020, Nature Methods 17(12):1173-1174. https://doi.org/10.1038/s41592-020-01009-y RefMet R 包
3 Workbench 初始平台 跨 20+ 物种 MS/NMR 数据的整合发布框架 2016 mwTab 元数据规范、结构库关联 Sud M, Fahy E, Cotter D, et al., 2016, Nucleic Acids Research 44(D1):D463-D470. https://doi.org/10.1093/nar/gkv1042 官网工具

数值不可直接比较的原因：三项工作分别处于数据治理、命名标准化与平台构建三个不同层面，不共享任务定义与指标。

阅读建议：把上表当作"能力坐标"而非"性能榜单"——关注每行工作为本库增加了什么能力（校验、命名、整合），而不是横向比大小。若需模型层基准，应回到 §8.3 协议在具体任务上自建。

§8.2 SOTA 总结与选型建议

本库的"SOTA"不在模型层而在数据基础设施层：对"跨研究代谢组数据能不能用"这个问题，当前最佳实践 = RefMet 名称对齐（特征层）+ mwtab 校验（格式层）+ Study 层 LOSO（评估层）。选型建议：若你的目标是单研究标志物建模，从任意 Exemplary Study 起步即可；若目标是多研究 meta 分析，先把 §6.3 预处理链与坑点 4 的批次校正做扎实；若目标是数据治理产品（如院内代谢组库），mwtab 校验管线 + RefMet 映射是最省力的骨架。

三条路线的共同前置只有一件事：把 §4.1 字段字典里的键体系（study/analysis/sample/refmet）在自家仓库里落成表结构。键体系立住，后面所有升级（加研究、换模型、接流水线）都是增量的；键体系不立，每个新研究都会变成一次返工。

§8.3 评测协议

社区可复现的评测协议要点：

  1. 数据冻结：记录抓取日期与 ID 清单哈希，manifest 随代码交付；
  2. 特征层统一：全部经 RefMet 映射，逐折报告特征覆盖率；
  3. 划分：外层 Leave-One-Study-Out、内层分层 K 折，切分键落在受试者/研究层；
  4. 缺失：声明插补方法（LOD/2、QRILC 等）并附敏感性分析；
  5. 指标：分类报 AUROC/AUPRC 与类基线，回归报 RMSE/R²，聚类报轮廓系数与 ARI；
  6. 报告：附 Project DOI 清单使第三方可核，标注每项数据的获取日期。

该协议由本页综合官方工具与文献惯例整理，供直接采用；各条与 §6.5 坑点编号一一对应，评审时可按坑点清单逐项对照。

数据集 定位 与本库关系
MetaboLights EBI 运营的欧洲代谢组存储库 地理对位的姊妹库；格式为 ISA-Tab 衍生（本库为 mwTab）；化合物库此前核实口径为 33,253 个化合物，与本库 164,000+ 结构库不可混用
GNPS 质谱分子网络平台 侧重 LC-MS/MS 谱图注释与社区分子网络，与本库研究级定量表互补
HMDB 人类代谢物参考知识库 化合物注释参考源，可用于丰度注释与背景先验
MassBank 二级质谱参考谱图库 本库 MS 检索功能的外部交叉参考源
LIPID MAPS 脂质分类与命名体系 本库脂质缩写与分类层级的直接上游之一
KEGG / PubChem / ChEBI / HMDB ID 空间 外部标识体系 经 RefMet 与 compound 端点映射，支撑通路富集
Protocols 栏目 官方协议库 代谢物类别/样本类型级的实验协议，理解数据来源的必读材料
mwFileStatusWebsite 社区工具 全库文件状态可视化（mwtab 论文配套），数据审计辅助

注：以上均为纯文字对比，规模与入口以其官方页面为准。

§8.5 关键论文 Top 5

  1. Sud M, Fahy E, Cotter D, Azam K, Vadivelu I, Burant C, Edison A, Fiehn O, Higashi R, Nair KS, Sumner S, Subramaniam S. Metabolomics Workbench: An international repository for metabolomics data and metadata, metabolite standards, protocols, tutorials and training, and analysis tools. Nucleic Acids Research, 2016, 44(D1):D463-D470. https://doi.org/10.1093/nar/gkv1042 —— 平台奠基论文，定义三级数据模型与收录范围。
  2. Fahy E, Subramaniam S. RefMet: a reference nomenclature for metabolomics. Nature Methods, 2020, 17(12):1173-1174. https://doi.org/10.1038/s41592-020-01009-y —— 提出四层分辨率代谢物命名，解决等压物种命名难题。
  3. Thompson PT, Moseley HNB. Major Update and Improved Validation Functionality in the mwTab Python Library and the Metabolomics Workbench File Status Website. Metabolites, 2026, 16(1):76. https://doi.org/10.3390/metabo16010076 —— mwtab 2.0 与全库 FAIR 校验，含规模增长统计。
  4. Djoumbou Feunang Y, Eisner R, Knox C, et al. ClassyFire: automated chemical classification with a comprehensive, computable taxonomy. Journal of Cheminformatics, 2016, 8:61. https://doi.org/10.1186/s13321-016-0174-y —— RefMet 化学分类层所依赖的可计算分类体系。
  5. Sumner LW, Amberg A, Barrett D, et al. Proposed minimum reporting standards for chemical analysis: Chemical Analysis Working Group (CAWG) Metabolomics Standards Initiative (MSI). Metabolomics, 2007, 3:211-221. —— 代谢物注释置信度分级的源头标准，理解本库注释分层的必读文献。

前两篇（Sud 2016、Fahy 2020）是理解本库数据模型与命名体系的总纲；Thompson 2026 提供了最新的规模与质量视角；后两篇分别支撑化学分类层与注释分级实践。五篇读毕，本库的全部结构设计都能找到出处。

§8.6 社区活跃度

  • 收录与排名：Database Commons 全库排名 253/6,932（截至 2026-06-13）；FAIRsharing 与 re3data 均有维护中的注册记录；PubChem 以 Data Source ID 12016 聚合其化合物内容。
  • 学术影响：主论文被引 635+（Europe PMC，截至 2026-06-13），覆盖方法学、临床生物标志物与数据治理文献。
  • 支持渠道：官方 FAQ、教程与 Exemplary Studies 清单；技术支持邮箱 help@metabolomicsworkbench.org；无官方论坛。
  • 持续运营证据：REST 文档 2025-07 更新至 v1.2；mwtab 2.0（2026-01 刊出）由库外实验室反哺维护，形成官方-社区双轨生态。
  • 社区工具层：除官方包外，社区围绕 mwTab/JSON 生态维护了文件状态网站等辅助设施；代谢组标准化活动（MSI 传统）持续通过论文与研讨会影响本库的元数据规范。
  • 提交端活跃度：60 个国家、持续增长的 Project 数（2,466 个，截至 2025-10-22）与 536 项在途 embargo，说明提交端与发布端均处于活跃循环。
  • 互操作活动：与本库相关的命名标准化讨论（MSI 传统、脂质缩写修订）持续在方法学期刊进行，RefMet 词表随之滚动演进——关注其 Nat Methods 论文与官网新闻栏是跟踪演变的最低成本方式。

§8.7 生态快照

资源 类型 链接 推荐理由
REST API 文档 v1.2 接口文档 https://www.metabolomicsworkbench.org/tools/mw_rest.php 7 类 context 全量说明 + 交互式 URL 构造器
mwtab Python 包 官方库 https://pypi.org/project/mwtab/ 解析/校验 mwTab 与 JSON，BSD-3-Clear 许可
RefMet R 包 官方库 https://github.com/metabolomicsworkbench/RefMet 批量名称映射 + 元数据获取 + 绘图
非靶向特征检索门户 在线工具 https://www.metabolomicsworkbench.org/data/search_untarg_mz_form.php 450 万+ m/z-RT 特征跨研究检索
结构相似性网络 在线工具 https://www.metabolomicsworkbench.org/databases/refmet/name_to_refmetS_form.php RDKit 指纹 + Tanimoto/Dice 网络图
Exemplary Studies 策展清单 https://www.metabolomicsworkbench.org/data/DRCCStudySummary.php?Mode=HighlightStudies 提交与建模的样板研究集
全库研究汇总 数据入口 https://www.metabolomicsworkbench.org/data/browse.php 浏览/检索/下载一切公开研究
REST API PDF 文档 离线文档 https://www.metabolomicsworkbench.org/tools/MWRestAPIv1.2.pdf 内网/离线环境查阅接口规范
甾体结构绘制工具 在线工具 https://www.metabolomicsworkbench.org/tools/structuredrawing/sterol_gen2_form.php 45 种母核生成 molfile/系统命名/m/z
胆汁酸命名表 参考资料 https://www.metabolomicsworkbench.org/tools/structuredrawing/bile_acids.php RefMet 名/系统名/缩写对照，脂质建模实用

§9 相关资源与引用

§9.1 官方资源

§9.2 BibTeX

@article{sud2016metabolomics,
  title   = {Metabolomics Workbench: An international repository for metabolomics
             data and metadata, metabolite standards, protocols, tutorials and
             training, and analysis tools},
  author  = {Sud, Manish and Fahy, Eoin and Cotter, Dawn and Azam, Kenan and
             Vadivelu, Ilango and Burant, Charles and Edison, Arthur and
             Fiehn, Oliver and Higashi, Richard and Nair, K. Sreekumaran and
             Sumner, Susan and Subramaniam, Shankar},
  journal = {Nucleic Acids Research},
  volume  = {44},
  number  = {D1},
  pages   = {D463--D470},
  year    = {2016},
  doi     = {10.1093/nar/gkv1042}
}

@article{fahy2020refmet,
  title   = {RefMet: a reference nomenclature for metabolomics},
  author  = {Fahy, Eoin and Subramaniam, Shankar},
  journal = {Nature Methods},
  volume  = {17},
  number  = {12},
  pages   = {1173--1174},
  year    = {2020},
  doi     = {10.1038/s41592-020-01009-y}
}

@article{thompson2026mwtab,
  title   = {Major Update and Improved Validation Functionality in the mwTab
             Python Library and the Metabolomics Workbench File Status Website},
  author  = {Thompson, P. Travis and Moseley, Hunter N. B.},
  journal = {Metabolites},
  volume  = {16},
  number  = {1},
  pages   = {76},
  year    = {2026},
  doi     = {10.3390/metabo16010076}
}

@article{djoumbou2016classyfire,
  title   = {ClassyFire: automated chemical classification with a
             comprehensive, computable taxonomy},
  author  = {Djoumbou Feunang, Yannick and Eisner, Roman and Knox, Craig and
             others},
  journal = {Journal of Cheminformatics},
  volume  = {8},
  pages   = {61},
  year    = {2016},
  doi     = {10.1186/s13321-016-0174-y}
}

@article{sumner2007msi,
  title   = {Proposed minimum reporting standards for chemical analysis:
             Chemical Analysis Working Group (CAWG) Metabolomics Standards
             Initiative (MSI)},
  author  = {Sumner, Lloyd W. and Amberg, Ann and Barrett, David and others},
  journal = {Metabolomics},
  volume  = {3},
  pages   = {211--221},
  year    = {2007}
}

§9.3 引用指南

  • 引数据：使用官方模板，同时给出 Project ID 与 Project DOI；模板含资助致谢（NMDR U2C-DK119886、CFDE 3OT2OD030544、M3C 1U2C-DK119889）。完整模板见 https://www.metabolomicsworkbench.org/about/howtocite.php。
  • 引平台：官方指定通用引用语为 “The Metabolomics Workbench, https://www.metabolomicsworkbench.org/”，学术场景建议再叠加主论文（Sud M et al., 2016）。
  • 引 RefMet：引用 RefMet 命名体系时使用 Fahy & Subramaniam 2020（Nature Methods 17(12):1173-1174）；在方法学段落中说明所用映射端点与映射日期。
  • 引本词条：引用千方病案医数集本页面（记录 ID 入库后自动生成），并注明检索日期；本页统计数字的口径日期见 §4.3。
  • 致谢联动：数据引用模板已含 NMDR/CFDE/M3C 资助号；若使用 HHEAR 子集，追加 NIEHS U2CES026555 致谢句。

§10 AI 使用声明卡

§10.1 AI 模型列表

模型 版本 用途
千方百科写作助手 fast-model 本词条初稿撰写、资料整合与结构化

§10.2 AI 参与范围

AI 参与范围：检索资料摘要与整合、章节结构生成、代码示例编写、表格与 JSON-LD 排版。AI 不参与：事实真伪的最终裁定、医学审核结论、审核状态判定。

边界约束在写作前即已声明：全部关键数字均要求溯源至官方页面或同行评审文献，未核实信息以"官方未披露"处理；他库对比仅作纯文字陈述；引用模板、REST 端点、资助号等硬事实逐条回查原始页面。人工审核者对每一处统计口径（截至日期、来源库）进行了二次核对，见 §10.4。

§10.3 输入来源列表

  1. Metabolomics Workbench 官方主页（规模口径 5,106/4,570/536，60 国），https://www.metabolomicsworkbench.org/ ，检索于 2026-09-15。
  2. Metabolomics Workbench 团队页面（PI 与策展团队），https://www.metabolomicsworkbench.org/about/personnel.php ，检索于 2026-09-15。
  3. Metabolomics Workbench REST API 文档 v1.2（2025-07-22），https://www.metabolomicsworkbench.org/tools/mw_rest.php ，检索于 2026-09-15。
  4. Metabolomics Workbench FAQ（embargo、上传、引用模板），https://www.metabolomicsworkbench.org/data/faq.php ，检索于 2026-09-15。
  5. Metabolomics Workbench How to Cite（Project DOI 体系与资助号），https://www.metabolomicsworkbench.org/about/howtocite.php ，检索于 2026-09-15。
  6. Metabolomics Workbench Terms of Use，https://www.metabolomicsworkbench.org/about/termsofuse.php ，检索于 2026-09-15。
  7. Metabolomics Workbench RefMet 页面（70 万+ 名称、3,500+ 研究、四层分辨率），https://www.metabolomicsworkbench.org/databases/refmet/index.php ，检索于 2026-09-15。
  8. Sud M, et al. Nucleic Acids Research, 2016, 44(D1):D463-D470. https://doi.org/10.1093/nar/gkv1042 （PubMed PMID 26467476；PMCID PMC4702780）。
  9. Fahy E, Subramaniam S. Nature Methods, 2020, 17(12):1173-1174. https://doi.org/10.1038/s41592-020-01009-y （PubMed PMID 33199890）。
  10. Thompson PT, Moseley HNB. Metabolites, 2026, 16(1):76. https://doi.org/10.3390/metabo16010076 （2025-10-22 规模口径：2,466/3,795/6,125；增速 50%）。
  11. re3data 注册记录 r3d100012314（起始年份、许可标注、FTP/REST、RRID），https://www.re3data.org/repository/r3d100012314 ，检索于 2026-09-15。
  12. Database Commons 数据库档案（635 次被引、全库排名），https://ngdc.cncb.ac.cn/databasecommons/database/id/1755 ，检索于 2026-09-15。
  13. CASRAI 数据集指南（与 MetaboLights 的关系、mwTab 格式、免费政策），https://casrai.org/guides/metabolomics-workbench-nih-national-metabolomics-repository/ ，检索于 2026-09-15。
  14. Metabolomics Workbench 非靶向检索门户（450 万+ 特征口径），https://www.metabolomicsworkbench.org/data/search_untarg_mz_form.php ，检索于 2026-09-15。
  15. PubChem 数据源页（Data Source ID 12016），https://pubchem.ncbi.nlm.nih.gov/source/Metabolomics Workbench ，检索于 2026-09-15。

§10.4 人工校验记录

内容模块 审核者 审核方式 审核状态
§0 E-E-A-T 与免责声明 千方病案医学编辑部 逐字对照金标准模板 ✅ 已通过
§1 概览与对比表 千方病案医学编辑部 核对官网与论文数字 ✅ 已通过
§2 ICD-11/SNOMED 映射 千方病案医学编辑部 术语库复核 ✅ 已通过
§3-§4 规格与字段字典 千方病案数据工程组 对照 REST 文档与 FAQ 核验 ✅ 已通过
§6 代码与 8 大坑点 千方病案数据工程组 代码走查 + 端点核验 ✅ 已通过
§7 DAIMS 24 项 千方病案医学编辑部 逐项独立复核 ✅ 已通过
§8-§9 生态与引用 千方病案医学编辑部 逐条链接与 DOI 核验 ✅ 已通过
§10 声明卡与口径日期 千方病案医学编辑部 与 §0、§4.3 交叉比对 ✅ 已通过
frontmatter 与 §C JSON-LD 千方病案数据工程组 双序列化一致性核对 ✅ 已通过
§5 划分与 §6.2 获取流程 千方病案数据工程组 端点实测与键体系核对 ✅ 已通过

§10.5 AI 生成章节标注

以下章节由 AI 生成初稿并经人工审核修订：§1.1、§1.2、§2.2、§2.5、§3.4、§4.4、§5、§6.3、§6.5、§6.10、§7.2、§7.5、§8.2、§8.3。表格类内容（INFOBOX、§3.2、§4.1、§7.7）由 AI 按核实事实汇编，逐格经人工抽查。

编写约束的事前声明：AI 不得引入未经检索来源支撑的数字；不确定的事实必须以"官方未披露"或口径限定词处理；他库仅可纯文字提及；所有代码必须基于官方文档记载的端点与参数编写。这些约束与 §10.2 的范围声明共同构成本页的 AI 治理边界。

§10.6 最后人工审核日期

2026-09-05（与 §0 审核日期一致；数据口径截至 2026-09-15 官网首页与 §4.3 所列各口径日期）。

审核覆盖说明：本次人工审核覆盖全部 11 个大节与 frontmatter/JSON-LD 的机器可读层；动态数字（研究数、引用量、特征数）均标注口径日期，后续更新应循 §4.3 的日期锚点逐项刷新，而非整体重写。

页面状态：published（全部内容已完成审核并发布）

相关数据集导航

以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：

  • metabolights — 共享标签：基因组学与多组学 / 代谢组学 / 转录组
  • tabula-sapiens — 共享标签：基因组学与多组学 / 转录组
  • single-cell-portal — 共享标签：基因组学与多组学 / 转录组
  • hcl — 共享标签：基因组学与多组学 / 转录组
  • pride — 共享标签：基因组学与多组学 / 代谢组学
  • proteomexchange — 共享标签：基因组学与多组学 / 代谢组学
  • GEO — 共享标签：基因组学与多组学 / 转录组
  • fantom5 — 共享标签：基因组学与多组学 / 转录组
  • TCGA — 共享标签：基因组学与多组学 / 转录组
  • CELLxGENE — 共享标签：基因组学与多组学 / 转录组

导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。

相关数据集

MetaboLights — 代谢组学开放研究存档 AI-Ready Wikipedia基因组学与多组学, 代谢组学, 转录组
返回 AI-Ready 数据集

数据定制

标注服务

欢迎联系咨询

客服二维码

客服二维码

客服二维码
电话咨询

直接咨询

18892062214

微信同号

微信咨询

微信咨询

18892062214

微信同号

邮箱咨询

邮箱咨询

collab@qianfanghub.cn