tooluniverse-metabolomics

メタボロミクス研究

代謝物を特定し、研究を分析し、メタボロミクスのデータベースを検索する、包括的なメタボロミクス研究スキルです。注釈付きの代謝物情報、研究の詳細、データベースの統計情報を含む、構造化された研究レポートを生成します。

使用例

次のような依頼があった場合に、このスキルを使用します：

• 代謝物を特定または注釈する（HMDB ID、化学的性質、経路）
• MetaboLights または Metabolomics Workbench からメタボロミクス研究の情報を取得する
• キーワードまたは疾患でメタボロミクス研究を検索する
• 代謝物プロファイルまたはデータセットを分析する
• 包括的なメタボロミクス研究レポートを生成する

クエリの例：

• 「グルコースの HMDB ID と経路情報を教えてください」
• 「MTBLS1 の研究詳細を取得してください」
• 「糖尿病に関連するメタボロミクス研究を見つけてください」
• 「次の代謝物を分析してください：グルコース、乳酸、ピルビン酸」

対象データベース

主な代謝物データベース：

• HMDB（Human Metabolome Database）：構造、経路、生物学的役割を含む、220,000 種類以上の代謝物
• MetaboLights：数千件の研究を収録する公開メタボロミクスリポジトリ
• Metabolomics Workbench：NIH Common Fund のメタボロミクスデータリポジトリ
• FooDB：食品化学成分データベース — 食品化合物の構造と HMDB／KEGG／PubChem／ChEBI の相互参照情報を取得するには、FooDB_get_compound（パラメーター fdb_id、例："FDB000004"）を使用します。食品メタボロミクスの注釈に最適です
• PubChem：化学的性質と生物活性データ（フォールバック）

研究ワークフロー

このスキルは、4 段階の分析パイプラインを実行します：

フェーズ 1：代謝物の特定と注釈

入力リスト内の各代謝物について：

1. 代謝物名で HMDB を検索します
2. HMDB ID、化学式、分子量を取得します
3. 詳細な代謝物情報（説明、経路）を取得します
4. HMDB が利用できない場合は、PubChem から CID と化学的性質を取得します

フェーズ 2：研究詳細の取得

指定された研究 ID について：

1. データベースの種類を判定します（MTBLS = MetaboLights、ST = Metabolomics Workbench）
2. 研究のメタデータ（タイトル、説明、生物種、ステータス）を取得します
3. 実験デザインとデータの利用可能性を抽出します

フェーズ 3：研究の検索

キーワード検索の場合：

1. クエリ語で MetaboLights の研究を検索します
2. 一致する研究 ID と概要情報を返します
3. 結果の総数を報告します

フェーズ 4：データベースの概要

常にレポートに含まれます：

1. MetaboLights の最近の研究例
2. データベースの統計情報と利用可能性
3. すべてのデータベースの連携情報

使用パターン

パターン 1：代謝物の特定

入力：

• 代謝物リスト：["glucose", "lactate", "pyruvate"]

出力レポートに含まれる情報：

• 各代謝物の HMDB ID
• 化学式と分子量
• 生物学的経路
• PubChem CID
• SMILES 表記

パターン 2：研究の取得

入力：

• 研究 ID："MTBLS1" または "ST000001"

出力レポートに含まれる情報：

• 研究のタイトルと説明
• 生物種情報
• 研究のステータスと公開日
• データの利用可能性

パターン 3：研究の検索

入力：

• 検索クエリ："diabetes"
• 任意の生物種フィルター

出力レポートに含まれる情報：

• 一致する研究 ID
• 研究のタイトルと概要
• 結果の総数

パターン 4：包括的な分析

入力：

• 代謝物リスト：["glucose", "pyruvate"]
• 研究 ID："MTBLS1"
• 検索クエリ："diabetes"

出力レポートに含まれる情報：

• すべてのフェーズを統合した内容（特定、研究詳細、検索結果、概要）
• 相互参照された情報
• メタボロミクス研究の完全な要約

入力パラメーター

metabolite_list（任意）

特定および注釈する代謝物名のリストです。

• 形式：文字列のリスト
• 例：["glucose"]、["lactate", "pyruvate", "acetate"]
• 注記：一般名を使用できます。HMDB が標準識別子を検索します

study_id（任意）

MetaboLights または Metabolomics Workbench の研究識別子です。

• 形式: "MTBLS" または "ST" で始まる文字列
• 例: "MTBLS1"、"ST000001"
• 注: プレフィックスに基づいてデータベースが自動検出されます

search_query（任意）

メタボロミクス研究を検索するキーワードです。

• 形式: 文字列（疾患、化合物、生物種、手法）
• 例: "diabetes"、"glucose metabolism"、"LC-MS"

organism（任意）

研究の絞り込み対象となる生物種です。

• 形式: 文字列（学名）
• デフォルト: "Homo sapiens"
• 例: "Mus musculus"、"Saccharomyces cerevisiae"

output_file（任意）

生成される Markdown レポートのパスです。

• 形式: 文字列（拡張子が .md のファイル名）
• デフォルト: タイムスタンプに基づいて自動生成されるファイル名
• 例: "my_analysis.md"、"metabolomics_report.md"

出力形式

すべての分析で、以下の構成の Markdown レポートが生成されます。

ヘッダーセクション:

• レポートのタイトルと生成タイムスタンプ
• 入力パラメーターの概要（代謝物、研究 ID、検索クエリ、生物種）

フェーズセクション:

• 明確なセクション見出し（## 1. 代謝物の同定、## 2. 研究の詳細など）
• 各代謝物または結果のサブセクション
• 一貫した書式（太字のラベル、結果を示す表）

データベースの概要:

• 利用可能なデータベースと統計情報
• 最近の研究のサンプル
• 統合に関する情報

エラー処理:

• データを利用できない場合の適切なエラーメッセージ
• フォールバック戦略を出力に記載
• 欠損フィールドには空欄ではなく「N/A」を使用

実装上の注意

SOAP ツールの処理

HMDB ツールは SOAP ベースのため、特別なパラメーター処理が必要です。

• HMDB_search: operation="search" パラメーターが必要です
• HMDB_get_metabolite: operation="get_metabolite" パラメーターが必要です
• endpoint または method パラメーターは使用しないでください（SOAP には適用されません）

レスポンス形式の違い

ツールによってレスポンス形式が異なるため、以下の 3 種類すべてに対応してください。

1. 標準形式: {status: "success", data: [...], metadata: {...}}
2. 直接リスト: [...]（例: metabolights_list_studies）
3. 直接辞書: {field1: ..., field2: ...}（例: 一部の詳細エンドポイント）

フィールドにアクセスする前に、必ず isinstance() でレスポンスの型を確認してください。

フォールバック戦略

堅牢性を確保するため、次の優先順位に従ってください。

1. 主要ソース: まずメインデータベースを試す（代謝物には HMDB、研究には MetaboLights）
2. フォールバックソース: 主要ソースが失敗した場合は代替データベースを使用する（化学的特性には PubChem）
3. デフォルトの動作: コンテキストを含むエラーメッセージを表示し、残りのフェーズを続行する

レポートの段階的な書き込み

メモリの問題を避けるため、レポートは段階的に書き込みます。

1. パイプラインの早い段階で出力ファイルを作成する
2. 各フェーズが完了したらセクションを追加する
3. 分析に時間がかかる場合は、定期的にディスクへフラッシュする
4. ユーザーがアクセスできるよう、ファイルパスを返す

ツールの検出

スキルは ToolUniverse から以下のツールを自動的に検出して使用します。

HMDB ツール:

• HMDB_search: 名前で代謝物を検索
• HMDB_get_metabolite: 代謝物の詳細情報を取得

MetaboLights ツール:

• metabolights_list_studies: 利用可能な研究を一覧表示
• metabolights_search_studies: キーワードで研究を検索
• metabolights_get_study: ID で研究の詳細を取得

Metabolomics Workbench ツール:

• MetabolomicsWorkbench_get_study: 研究情報を取得
• MetabolomicsWorkbench_search_compound_by_name: 化合物を検索

PubChem ツール:

• PubChem_get_CID_by_compound_name: PubChem CID を取得
• PubChem_get_compound_properties_by_CID: 化学的特性を取得

手動でツールを設定する必要はありません。すべてのツールが自動的に読み込まれます。

よくある問題

問題: HMDB が「Error querying HMDB: 0」を返す

原因: HMDB 検索で結果が空だったか、最初の結果へのアクセス時にインデックスエラーが発生しました 解決方法: 一般的でない代謝物では想定される動作です。PubChem へのフォールバックが試行されます

問題：Study の詳細がすべてのフィールドで「N/A」と表示される

原因：Study ID が見つからないか、API を利用できません 解決策：Study ID の形式（MTBLS* または ST*）を確認し、Study が公開されているか確認してください

問題：ツールが見つからないというエラー

原因：一部のデータベースの API キーが不足しています 解決策：.env.template を確認し、必要な API キーを .env ファイルに追加してください（ほとんどのメタボロミクスツールはキーなしで動作します）

問題：代謝物リストが大きいと実行が遅くなる

原因：パイプラインが代謝物を個別にクエリします 解決策：レポートには最初の 10 個の代謝物のみが含まれます。代謝物が 20 個を超える場合は、バッチ処理を検討してください

概要

Metabolomics Research スキルは、以下を行う 4 フェーズのパイプラインを通じて、包括的なメタボロミクス解析を提供します。

1. HMDB（主）および PubChem（フォールバック）データベースを使用して代謝物を特定
2. MetaboLights および Metabolomics Workbench リポジトリからStudy の詳細を取得
3. メタボロミクスデータベース全体でキーワードを使ってStudy を検索
4. すべての調査結果を読みやすい Markdown 形式で構造化レポートを生成

主な機能：

• ✅ 動作するパイプラインによる 100% のテストカバレッジ
• ✅ SOAP ツールを正しく処理（HMDB では operation パラメーターが必要）
• ✅ フォールバック戦略を実装（HMDB → PubChem）
• ✅ エラーを適切に処理（いずれかのフェーズが失敗しても処理を継続）
• ✅ レポートを段階的に作成（メモリ効率に優れています）
• ✅ 実装に依存しないドキュメント（Python SDK と MCP の両方で動作）

次の用途に最適です：

• 代謝物のアノテーションと経路解析
• Study の発見とデータ取得
• 包括的なメタボロミクス研究レポート
• 複数のデータベースにまたがるメタボロミクスのクエリ

推論フレームワーク

出発点：質量スペクトル解析

代謝物の同定は質量スペクトルから始まります。推測せず、必ず計算した中性質量で HMDB／PubChem を検索してください。m/z だけから正体を推測してはいけません。

• ステップ 1 — 中性質量を計算：イオン化モードを判定します。正イオンモード：付加イオンの質量を差し引きます（[M+H]+ = -1.0073、[M+Na]+ = -22.9892、[M+NH4]+ = -18.0344）。負イオンモード：質量を加算して戻します（[M-H]- = +1.0073、[M+Cl]- = +34.9694、[M+HCOO]- = +44.9977）。
• ステップ 2 — データベースを検索：HMDB を質量でクエリします（Orbitrap／Q-TOF では ±5 ppm、単位分解能では ±0.5 Da）。複数の付加イオンの仮説から異なる中性質量が導かれます。結論を出す前に、妥当な付加イオンをすべて確認してください。
• ステップ 3 — 曖昧さを解消：精密質量だけでは、5～20 件の候補が一致することがよくあります。同位体パターン（M+1／M+2 の比率から元素組成がわかります。例：M+2 が高い場合は S または Cl が示唆されます）、保持時間、MS/MS フラグメンテーションを使って候補を絞り込みます。単一の質量一致は信頼度 L3 です。L2／L1 には、参照スペクトルとの MS/MS 一致が必要です。

証拠の評価（代謝物同定の信頼度）

• L1 - 確定：HMDB ID + 保持時間 + 参照標準物質との MS/MS 一致
• L2 - 可能性が高い：精密質量による HMDB との一致 + MS/MS 類似度（cosine > 0.7）、標準物質なし
• L3 - 暫定：精密質量と分子式のみで一致。構造異性体は未解決
• L4 - 未知：データベースとの一致がない検出 m/z。PubChem のフォールバックで候補が得られる場合があります

解釈のガイダンス

代謝物の同定：HMDB IDは、実験的検証と組み合わせた場合に最も信頼性の高いアノテーションを提供します。PubChemのみでの一致（フォールバック）は、その代謝物が化学的に特徴付けられているものの、生物学的な文脈（経路、疾患との関連）が不足している可能性を示します。同定の信頼度は必ず報告してください。

経路エンリッチメントの戦略：複数の代謝物が同じKEGGまたはHMDB経路にマッピングされる場合、入力リストがその経路向けに事前選択されていなければ、エンリッチメントには意味があります。経路の総数に対するヒット数を報告してください（3/500より3/5の検出のほうが情報量が多くなります）。推測せずに調べてください — 名前だけから経路への所属を推定するのではなく、各代謝物についてHMDB_get_metaboliteを使用して経路アノテーションを取得してください。

バイオマーカー発見の考え方：候補バイオマーカーには、次の条件が必要です：（1）サンプル間で変化の方向が一貫している（フォールドチェンジ > 1.5）、（2）統計的有意性がある（FDR調整済みp < 0.05）、（3）生物学的妥当性がある — HMDBで代謝物の既知の疾患との関連を調べてください、（4）独立コホートで再現性がある。単一研究におけるHMDBの関連性は仮説の生成に役立ちますが、確証にはなりません。独立した検証用データセットについて、MetaboLights/Metabolomics Workbenchを確認してください。

統合に関する質問

完全なメタボロミクスレポートでは、次の質問に答える必要があります。

1. 各代謝物の同定信頼度（L1-L4）はどの程度ですか？
2. 同定された代謝物では、どの生物学的経路がエンリッチされていますか？
3. バイオマーカーの基準（フォールドチェンジ、有意性、妥当性）を満たす代謝物はありますか？
4. 対象の疾患または状態に関連するメタボロミクス研究（MTBLS/ST）はありますか？
5. 主な発見の生物学的関連性を裏付けるデータベース横断的なエビデンス（HMDB経路、PubChem生物活性）には何がありますか？

制限事項：

• HMDBにすべての代謝物が登録されているとは限りません（PubChemにフォールバックします）
• 認証が必要な研究や、公開されていない研究もあります
• 多数の代謝物リスト（>10）はレポートで自動的に制限されます
• APIのレート制限が大規模なクエリに影響する場合があります

Python SDKの使用例、MCP統合、手順ごとのチュートリアルについては、QUICK_START.mdを参照してください。