chembl-database

ChEMBL データベースクエリ

前提条件

1. uv：uv スキルを読み、セットアップ手順に従って、uv がインストールされ、PATH に含まれていることを確認してください。
2. ユーザーへの通知：.licenses/chembl_database_LICENSE.txt がワークスペースのルートディレクトリにまだ存在しない場合は、（1）ユーザーに https://chembl.gitbook.io/chembl-interface-documentation/about の利用規約を確認するよう目立つ形で通知し、（2）通知文とタイムスタンプを記録したファイルを作成してください。

基本ルール

• [!IMPORTANT] ユーティリティスクリプトを使用すること：ChEMBL API とのすべてのやり取り（ステータスの確認を含む）では、必ず付属のユーティリティスクリプト scripts/chembl_api.py を使用してください。ChEMBL API へのクエリに curl や独自の Python リクエストを使用することは絶対に避けてください。これにより、レート制限が適用され、ネットワークエラー時にも再試行が行われます。

• ファイルへの出力（必須）：すべてのサブコマンドで --output フラグが必須です。すべての JSON 結果は指定したファイルに書き込まれます。コマンドの実行後、jq または独自のコードを使って出力ファイルを読み取り、データを抽出してください。リスト結果は通常、エンドポイント名（例：molecules、activities）をキーとする JSON 配列に格納されます。

• 通知：このスキルを使用した場合は、その旨を出力に記載してください。

ユーティリティスクリプト

ChEMBL API のすべてのクエリには、サブコマンドを備えた単一のスクリプトを使用します。

uv run scripts/chembl_api.py <subcommand> --output <file> [options]

---

1. API ステータスの確認

uv run scripts/chembl_api.py status --output /tmp/status.json

---

2. 分子クエリ

ChEMBL ID で取得： bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --output /tmp/mol.json

名前で検索： bash uv run scripts/chembl_api.py molecule --search "aspirin" --limit 3 --output /tmp/mol_search.json

一括取得： bash uv run scripts/chembl_api.py molecule --ids "CHEMBL25;CHEMBL1642" --limit 10 --output /tmp/mol_batch.json

プロパティで絞り込み： bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__lte=500 --limit 5 --output /tmp/mol_filter.json

範囲で絞り込み： bash uv run scripts/chembl_api.py molecule --filter molecule_properties__mw_freebase__range=150,200 --limit 5 --output /tmp/mol_range.json

SDF 構造ファイルをダウンロード： bash uv run scripts/chembl_api.py molecule --id CHEMBL25 --dl_format sdf --output /tmp/aspirin.sdf

ヒント：SDF/MOL ファイルは、PyMOL や RDKit などのツールに直接渡して、3D 可視化や解析に利用できます。

---

3. ターゲットクエリ

ターゲットを検索： bash uv run scripts/chembl_api.py target --search "EGFR" --limit 5 --output /tmp/targets.json

ID で取得： bash uv run scripts/chembl_api.py target --id CHEMBL203 --output /tmp/egfr.json

---

4. 生物活性データ

ID で活性データを取得： bash uv run scripts/chembl_api.py activity --id 31863 --output /tmp/act.json

活性データを検索： bash uv run scripts/chembl_api.py activity --search "EGFR" --limit 5 --output /tmp/act_search.json

ターゲットの活性データを絞り込み： bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 10 --output /tmp/egfr_ic50.json

生物活性の単位を nM に正規化： bash uv run scripts/chembl_api.py activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 5 --normalize --output /tmp/egfr_normalized.json

重要：生物活性値には、nM、µM、pM などさまざまな単位が使われます。一貫した比較を行うため、--normalize を使用してすべての値を nM に変換してください。各レコードには normalized_value_nM と normalization_note が含まれます。

---

5. 薬剤情報

薬剤の詳細を取得： bash uv run scripts/chembl_api.py drug --id CHEMBL25 --output /tmp/drug.json

薬剤の適応症： bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 --limit 10 --output /tmp/indications.json

フェーズで適応症を絞り込む： bash uv run scripts/chembl_api.py drug_indication --filter molecule_chembl_id=CHEMBL25 max_phase_for_ind=4.0 --limit 10 --output /tmp/approved_indications.json

薬剤の警告： bash uv run scripts/chembl_api.py drug_warning --limit 5 --output /tmp/warnings.json

作用機序： bash uv run scripts/chembl_api.py mechanism --filter molecule_chembl_id=CHEMBL25 --limit 5 --output /tmp/mech.json

---

6. 構造ベースの検索

注： 類似性検索と部分構造検索はどちらも、ChEMBL のインデックス済みデータベース上でサーバー側で実行されます。ローカルに RDKit をインストールする必要はありません。

類似性検索（SMILES ＋しきい値）： bash uv run scripts/chembl_api.py similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --similarity 85 --limit 5 --output /tmp/similar.json

部分構造検索（SMILES）： bash uv run scripts/chembl_api.py substructure --smiles "c1ccccc1" --limit 5 --output /tmp/substruct.json

---

7. 化合物の画像

2D 構造画像をダウンロードします（デフォルトは SVG で、出版物向けに拡大縮小できます）。

uv run scripts/chembl_api.py image --id CHEMBL25 --output /tmp/chembl25.svg

オプション：

• --dimensions：画像サイズ（ピクセル単位、最大 500、デフォルト 500）。
• --engine：レンダリングエンジン（デフォルト：rdkit）。
• --img_format：出力形式 — svg（デフォルト、ベクター形式）または png（ラスター形式）。

---

8. 他のデータベースとの相互参照

ChEMBL は UniProt、Ensembl、PubChem などのデータベースと統合されています。一般的な相互参照のパターンは次のとおりです。

UniProt アクセッションから ChEMBL ターゲットを検索： bash uv run scripts/chembl_api.py target --filter target_components__accession=P00533 --limit 5 --output /tmp/uniprot_target.json

任意の ChEMBL ID をエンティティタイプに解決： bash uv run scripts/chembl_api.py chembl_id_lookup --id CHEMBL203 --output /tmp/lookup.json

相互参照ソースを検索： bash uv run scripts/chembl_api.py xref_source --limit 10 --output /tmp/xrefs.json

ヒント： target_component エンドポイントを使うと、任意の ChEMBL ターゲットについて、UniProt アクセッション、遺伝子名、タンパク質配列を検索できます。

---

9. ページネーション

すべてのリストエンドポイントは、ページネーション用の --limit と --offset に対応しています。

# First page: 2 results starting at offset 0
uv run scripts/chembl_api.py molecule --limit 2 --offset 0 --output /tmp/page1.json

# Second page: next 2 results starting at offset 2
uv run scripts/chembl_api.py molecule --limit 2 --offset 2 --output /tmp/page2.json

レスポンスには total_count、limit、offset、next、previous を含む page_meta が含まれます。--offset の値を順次指定して、大きな結果セットをページごとに取得してください。

---

10. その他のエンドポイント

残りのエンドポイントもすべて同じパターンに従います。

uv run scripts/chembl_api.py <subcommand> --output <file> [--id ID | --ids ID1;ID2 | --search QUERY] [--limit N] [--offset N] [--filter KEY=VAL ...]

主なサブコマンドの概要：

• molecule (searchable: true)：分子／化合物 — 主要なエントリーポイント
• target (searchable: true)：創薬ターゲット（タンパク質、生物など）
• activity (searchable: true)：生物活性データ（IC50、Ki、EC50など）
• drug (searchable: false)：承認済み医薬品
• mechanism (searchable: false)：作用機序
• assay (searchable: true)：アッセイの説明
• similarity (searchable: false)：類似性検索（特殊）
• substructure (searchable: false)：部分構造検索（特殊）
• image (searchable: false)：化合物画像のダウンロード（特殊）

サブコマンドの全一覧：

• activity_supp (searchable: false)：補足的な活性データ
• assay_class (searchable: false)：アッセイの分類
• atc_class (searchable: false)：ATC 医薬品分類
• binding_site (searchable: false)：結合部位の情報
• biotherapeutic (searchable: false)：バイオ医薬品分子
• cell_line (searchable: false)：細胞株の詳細
• chembl_id_lookup (searchable: true)：ChEMBL ID の解決
• chembl_release (searchable: false)：データベースのリリース情報
• compound_record (searchable: false)：化合物レコード
• compound_structural_alert (searchable: false)：構造アラート
• document (searchable: true)：文献ドキュメント
• document_similarity (searchable: false)：ドキュメントの類似性
• drug_indication (searchable: false)：医薬品の適応症
• drug_warning (searchable: false)：医薬品の安全性に関する警告
• go_slim (searchable: false)：GO slim 用語
• metabolism (searchable: false)：代謝データ
• molecule_form (searchable: false)：分子形態（塩／親化合物）
• organism (searchable: false)：生物
• protein_classification (searchable: true)：タンパク質の分類
• source (searchable: false)：データソース
• target_component (searchable: false)：ターゲットタンパク質の構成要素
• target_relation (searchable: false)：ターゲット間の関係
• tissue (searchable: false)：組織の種類
• xref_source (searchable: false)：相互参照ソース
• status (searchable: false)：API ステータスの確認（特殊）

共通オプション

• --output FILE：必須。 JSON の結果を出力するファイルパスです。
• --id ID：ID を指定して単一のレコードを取得します。
• --ids ID1;ID2;...：複数のレコードを一括取得します。
• --search QUERY：フリーテキスト検索（検索可能なエンドポイントのみ。✓ が付いています）。
• --limit N：返す結果の最大数（デフォルト：5）。
• --offset N：ページネーションのオフセット。
• --filter KEY=VAL：フィルターパラメーター（複数指定できます）。
• --normalize：（activity のみ）値を nM に正規化します。
• --dl_format sdf|mol：（molecule のみ）構造ファイルをダウンロードします。

リファレンス

• API エンドポイントのリファレンス：エンドポイントとフィルター演算子の全一覧については、 references/api_endpoints.md を参照してください。

ワークフロー

1. status --output /tmp/status.json を実行して、API が利用可能であることを確認します。
2. 該当するサブコマンドを使用して、ターゲット、分子、または医薬品を検索します。
3. 出力 JSON ファイルを読み込み、ID とデータを抽出します。
4. 検索結果の ID を使用して、詳細なレコードを取得します。
5. フィルターを指定して activity をクエリし、ターゲット／分子の生物活性データを取得します。 研究間で値を比較する場合は、--normalize を使用します。
6. similarity または substructure を使用して、サーバー側で構造ベースのクエリを実行します。
7. image で化合物画像を、または molecule --dl_format sdf で構造ファイルをダウンロードします。
8. target --filter target_components__accession=<UniProt> を使用して、UniProt と相互参照します。