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。绝不可使用 curl 或自定义 Python 请求直接查询 ChEMBL API。这可以确保执行速率限制，并在网络错误时重试。

• 输出到文件（必需）：每个子命令都必须使用 --output 标志。所有 JSON 结果都会写入指定文件。运行命令后，使用 jq 或自编代码读取输出文件并提取数据。列表结果通常封装在以端点名称为键的 JSON 数组中（例如，molecules、activities）。

• 通知：如果使用了此技能，请确保在输出中提及。

实用工具脚本

所有 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 进行交叉引用。