alterlab-metabolomics-wb

メタボロミクスワークベンチデータベース

概要

メタボロミクスワークベンチは、UCSD がホストする NIH コモンファンド支援の包括的なプラットフォームで、メタボロミクス研究データの主要なリポジトリとして機能します。数千件の処理済み研究データ（REST API に 2026-09 時点で公開研究 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 は内部の .php ハンドラーへ 302 リダイレクトします。 urllib／requests はリダイレクトを自動的にたどりますが、生の curl はたどりません（-L を渡さないと本文は空になります）。
• 利用可能な研究データの一覧取得には、/json ではなく /txt を使ってください。 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 を標準出力に出力します）。

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データベースを使用して代謝物名を標準化し、4つの構造解像度レベルにわたる体系的な分類にアクセスします。

主な操作：

• 一般的な代謝物名を標準化された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は、主に次の2つの出力形式に対応しています：

• JSON（デフォルト）：プログラムからのアクセスに適した、機械可読形式です
• TXT：人が読みやすいタブ区切りテキスト形式です

API URLの末尾に/jsonまたは/txtを追加して形式を指定します。形式を省略した場合、デフォルトでJSONが返されます。

ベストプラクティス

1. 標準化にはRefMetを使用する：名称の一貫性を確保するため、研究を検索する前に、必ずRefMetを通じて代謝物名を標準化してください。

2. 適切な付加イオンを指定する：m/z検索を行う際は、分析方法に適したイオン付加体の種類を使用してください（例：ESIのポジティブモードではM+H）。

3. 妥当な許容誤差を設定する：適切な質量許容誤差を使用してください（通常、低分解能MSでは0.5 Da、高分解能MSでは0.01 Daです）。

4. 参照データをキャッシュする：API呼び出しを最小限に抑えるため、頻繁に使用する参照データ（RefMetデータベース、化合物情報）のキャッシュを検討してください。

5. ページネーションを処理する：大規模な結果セットの場合、レスポンス内の複数のデータ構造を処理できるようにしてください。

6. 識別子を検証する：化合物を正しく特定できるよう、可能な場合は複数のデータベースで代謝物識別子を相互参照してください。

リソース

references/

詳細なAPIリファレンスドキュメントはreferences/api_reference.mdにあります。以下が含まれます。

• REST APIエンドポイントの完全な仕様
• 利用可能なすべてのコンテキスト（compound、study、refmet、metstat、gene、protein、moverz）
• 入出力パラメーターの詳細
• 質量分析用のイオン付加体の種類
• その他のクエリ例

詳細なAPI仕様が必要な場合や、あまり一般的でないエンドポイントを使用する場合は、このリファレンスファイルを読み込んでください。