alterlab-metabolomics-wb

Metabolomics Workbench 数据库

概述

Metabolomics Workbench 是一个由 NIH Common Fund 资助、由 UCSD 托管的综合平台，也是代谢组学研究数据的主要存储库。它通过编程方式提供对数千项已处理研究的访问权限（截至 2026-09，REST API 列出了 4,587 项公开研究和 7,534 项分析），通过 RefMet 提供标准化的代谢物命名法，并支持跨多个分析平台（GC-MS、LC-MS、NMR）的强大搜索功能。

API 注意事项（已于 2026-06 验证）

解析响应前请先阅读以下内容——有几种行为与“/json 总是返回 JSON”的直觉假设相悖：

• /json 并非总是返回 JSON。 moverz 上下文以及 study 的 summary/搜索结果，即使请求 /json，也会返回制表符分隔文本。scripts/query_metabolomics_wb.py 助手脚本会将此类响应正文封装为 {"raw": "<tsv>"}，而不是报错。请解析 TSV；不要假设响应是带键的 JSON 对象。
• moverz 会发出 302 重定向到内部 .php 处理程序。urllib/requests 会自动跟随重定向；原始 curl 不会，除非传入 -L（否则会得到空响应正文）。
• 使用 /txt 而不是 /json 列出可用研究。 study/study_id/ST/available/json 会返回空响应正文；请使用 study/study_id/ST/available/txt，它会返回垂直的 key<TAB>value 列表（每项分析都会重复出现 project_id、study_id、analysis_id 行）——收集 study_id 行并去重，因为包含多项分析的研究会出现多次。
• refmet/match 返回字段 refmet_name（以及 formula、exactmass、类别和 refmet_id），而不是 name。
• 通过 refmet_name 搜索研究时使用的是已编入索引的 RefMet 名称，该名称可能与 refmet/match 的输出不同（例如，match/citrate 返回 Citric acid，但研究索引采用 Tyrosine 风格的条目）。请确认该名称能匹配到研究；结果为空通常表示名称索引不匹配，而不是“没有研究”。

脚本

scripts/query_metabolomics_wb.py — 查询 Metabolomics Workbench REST API（仅使用标准库，将 JSON 输出到 stdout）：

python scripts/query_metabolomics_wb.py refmet citrate          # standardize a name (RefMet)
python scripts/query_metabolomics_wb.py study ST000001          # study summary
python scripts/query_metabolomics_wb.py moverz 635.52 --adduct M+H   # m/z search

何时使用此技能

在通过 Metabolomics Workbench REST API 查询代谢物结构、访问研究数据、标准化命名法、执行质谱搜索，或检索基因/蛋白质与代谢物的关联时，应使用此技能。

不适用的情况

场景	改用
人类代谢物的参考生物学信息（生物流体浓度、生物标志物证据）	alterlab-hmdb
一般化合物属性、同义词、生物测定	alterlab-pubchem
通路图以及 KEGG 化合物/反应映射	alterlab-kegg
处理原始 LC-MS/MS 文件（峰提取、特征检测）	alterlab-pyopenms
对照谱库评估 MS/MS 光谱相似性	alterlab-matchms

核心功能

1. 查询代谢物结构和数据

访问全面的代谢物信息，包括结构、标识符以及与外部数据库的交叉引用。

关键操作：

• 通过各种标识符检索化合物数据（PubChem CID、InChI Key、KEGG ID、HMDB ID 等）
• 将分子结构下载为 MOL 文件或 PNG 图像
• 访问标准化的化合物分类
• 在不同代谢物数据库之间交叉引用

查询示例：

import requests

# Get compound information by PubChem CID
response = requests.get('https://www.metabolomicsworkbench.org/rest/compound/pubchem_cid/5281365/all/json')

# Download molecular structure as PNG
response = requests.get('https://www.metabolomicsworkbench.org/rest/compound/regno/11/png')

# Get compound name by registry number
response = requests.get('https://www.metabolomicsworkbench.org/rest/compound/regno/11/name/json')

2. 访问研究元数据和实验结果

根据各种条件查询代谢组学研究，并检索完整的实验数据集。

关键操作：

• 按代谢物、机构、研究人员或标题搜索研究
• 访问研究摘要、实验因素和分析详情
• 以各种格式检索完整的实验数据
• 下载 mwTab 格式文件以获取完整的研究信息
• 查询非靶向代谢组学数据

查询示例：

# List all available public studies (use /txt — the /json variant returns empty)
response = requests.get('https://www.metabolomicsworkbench.org/rest/study/study_id/ST/available/txt')

# Get study summary
response = requests.get('https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/summary/json')

# Retrieve experimental data
response = requests.get('https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/data/json')

# Find studies containing a specific metabolite
response = requests.get('https://www.metabolomicsworkbench.org/rest/study/refmet_name/Tyrosine/summary/json')

3. 使用 RefMet 标准化代谢物命名

使用 RefMet 数据库标准化代谢物名称，并访问四个结构分辨率级别的系统分类信息。

主要操作：

• 将常见代谢物名称匹配到标准化的 RefMet 名称
• 按化学式、精确质量或 InChI Key 查询
• 访问分层分类信息（超类、主类、子类）
• 检索所有 RefMet 条目，或按分类筛选

查询示例：

# Standardize a metabolite name
response = requests.get('https://www.metabolomicsworkbench.org/rest/refmet/match/citrate/name/json')

# Query by molecular formula
response = requests.get('https://www.metabolomicsworkbench.org/rest/refmet/formula/C12H24O2/all/json')

# Get all metabolites in a specific class
response = requests.get('https://www.metabolomicsworkbench.org/rest/refmet/main_class/Fatty%20Acids/all/json')

# Retrieve complete RefMet database
response = requests.get('https://www.metabolomicsworkbench.org/rest/refmet/all/json')

4. 执行质谱搜索

根据指定的离子加合物和容差范围，按质荷比（m/z）搜索化合物。

主要操作：

• 在多个数据库（Metabolomics Workbench、LIPIDS、RefMet）中搜索前体离子质量
• 指定离子加合物类型（M+H、M-H、M+Na、M+NH4、M+2H 等）
• 计算已知代谢物与特定加合物对应的精确质量
• 设置质量容差，实现灵活匹配

查询示例：

# Search by m/z value with M+H adduct
response = requests.get('https://www.metabolomicsworkbench.org/rest/moverz/MB/635.52/M+H/0.5/json')

# Calculate exact mass for a metabolite with specific adduct
response = requests.get('https://www.metabolomicsworkbench.org/rest/moverz/exactmass/PC(34:1)/M+H/json')

# Search across RefMet database
response = requests.get('https://www.metabolomicsworkbench.org/rest/moverz/REFMET/200.15/M-H/0.3/json')

5. 按分析和生物学参数筛选研究

使用 MetStat 上下文查找符合特定实验条件的研究。

主要操作：

• 按分析方法筛选（LCMS、GCMS、NMR）
• 指定电离极性（POSITIVE、NEGATIVE）
• 按色谱类型筛选（HILIC、RP、GC）
• 指定物种、样本来源或疾病
• 使用分号分隔的格式组合多个筛选条件

查询示例：

# Find human blood studies on diabetes using LC-MS
response = requests.get('https://www.metabolomicsworkbench.org/rest/metstat/LCMS;POSITIVE;HILIC;Human;Blood;Diabetes/json')

# Find all human blood studies containing tyrosine
response = requests.get('https://www.metabolomicsworkbench.org/rest/metstat/;;;Human;Blood;;;Tyrosine/json')

# Filter by analytical method only
response = requests.get('https://www.metabolomicsworkbench.org/rest/metstat/GCMS;;;;;;/json')

6. 访问信息基因和蛋白质

检索与代谢通路和代谢物代谢相关的基因和蛋白质数据。

主要操作：

• 按符号、名称或 ID 查询基因
• 访问蛋白质序列和注释
• 交叉引用基因 ID、RefSeq ID 和 UniProt ID
• 检索基因与代谢物的关联

查询示例：

# Get gene information by symbol
response = requests.get('https://www.metabolomicsworkbench.org/rest/gene/gene_symbol/ACACA/all/json')

# Retrieve protein data by UniProt ID
response = requests.get('https://www.metabolomicsworkbench.org/rest/protein/uniprot_id/Q13085/all/json')

常见工作流

工作流 1：查找含有特定代谢物的研究

要查找所有包含特定代谢物测量数据的研究：

1. 首先使用 RefMet 标准化代谢物名称：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/refmet/match/glucose/name/json')
   

2. 使用标准化名称搜索研究：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/study/refmet_name/Glucose/summary/json')
   

3. 从特定研究中检索实验数据：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/data/json')
   

工作流 2：根据 MS 数据鉴定化合物

要根据质谱 m/z 值鉴定潜在化合物：

1. 使用适当的加合物和容差执行 m/z 搜索：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/moverz/MB/180.06/M+H/0.5/json')
   

2. 查看结果中的候选化合物。注意：moverz 返回的是制表符分隔的文本（名称、系统名称、分子式、离子、类别），而非 JSON，且不包含 regno 列。使用返回的名称或分子式查找化合物。

3. 使用已有的标识符（例如注册号或分子式）检索候选化合物的详细信息：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/compound/regno/{regno}/all/json')
   

4. 下载结构以进行确认：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/compound/regno/{regno}/png')
   

工作流 3：探索疾病特定的代谢组学

要查找特定疾病和分析平台的代谢组学研究：

1. 使用 MetStat 筛选研究：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/metstat/LCMS;POSITIVE;;Human;;Cancer/json')
   

2. 查看结果中的研究 ID

3. 访问研究详细信息：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/study/study_id/ST{ID}/summary/json')
   

4. 检索完整实验数据：

   response = requests.get('https://www.metabolomicsworkbench.org/rest/study/study_id/ST{ID}/data/json')
   

输出格式

API 支持两种主要输出格式：

• JSON（默认）：机器可读格式，适合程序化访问
• TXT：制表符分隔的可读文本格式

在 API URL 后添加 /json 或 /txt 以指定格式。省略格式时，默认返回 JSON。

最佳实践

1. 使用 RefMet 进行标准化：搜索研究之前，始终通过 RefMet 标准化代谢物名称，以确保命名一致

2. 指定合适的加合离子：执行 m/z 搜索时，根据分析方法使用正确的离子加合类型（例如，正离子模式 ESI 使用 M+H）

3. 设置合理的容差：使用合适的质量容差值（低分辨率通常为 0.5 Da，高分辨率 MS 通常为 0.01 Da）

4. 缓存参考数据：考虑缓存常用的参考数据（RefMet 数据库、化合物信息），以尽量减少 API 调用

5. 处理分页：对于大型结果集，请做好处理响应中多种数据结构的准备

6. 验证标识符：尽可能跨多个数据库交叉核对代谢物标识符，以确保正确识别化合物

资源

references/

详细的 API 参考文档见 references/api_reference.md，其中包括：

• 完整的 REST API 端点规范
• 所有可用上下文（compound、study、refmet、metstat、gene、protein、moverz）
• 输入/输出参数详情
• 质谱分析中的离子加合类型
• 其他查询示例

需要详细的 API 规范或使用较少见的端点时，请加载此参考文件。