opentargets-database

Open Targets Database Skill

概述

此技能可访问 Open Targets Platform GraphQL API。它汇总来自遗传学（GWAS/eQTL）、通路、动物模型和临床试验的多模态证据，用于对靶点与疾病关联进行排序，并识别可成药基因。

前置条件

1. uv：阅读 uv 技能，并按照其 Setup 说明确保已安装 uv 且已将其加入 PATH。
2. 用户通知：如果工作区根目录中不存在 .licenses/opentargets_database_LICENSE.txt，则 (1) 显著提醒用户查看 https://platform-docs.opentargets.org/licence 上的条款，然后 (2) 创建该文件，记录通知文本和时间戳。

核心规则

• 使用封装脚本：始终执行提供的辅助脚本来查询数据库，而不是直接访问数据库。这些脚本会自动确保公平使用并实现重试逻辑。
• 输出标志：始终需要 --output 标志，因为输出可能非常大。使用 jq 或编写自己的代码来处理此 JSON 文件。
• 通知：使用此技能时，确保在输出中提及。

快速参考

始终使用提供的 Python 脚本 scripts/query_opentargets.py 快速查询数据库。它负责 API 通信、重试、格式化，并会自动截断过大的响应。切勿编写自己的 curl 或类似请求。

用法：

uv run scripts/query_opentargets.py --output /tmp/opentargets_results.json [OPTIONS] COMMAND [ARGS]...

常用选项：

• --output PATH：必需。写入 JSON 输出文件的路径。
• --limit N：限制数组中返回的项目数（默认值为 50）。进行初步探索时，可使用 10 之类的较小数字。
• --page-size N：设置 API 分页大小（默认值为 200）。如果需要更多结果，可增大此值（例如，包含许多可信集的研究）。

可用命令：

• get-gwas-studies disease_id：获取与特定疾病 ID 关联的所有 GWAS 研究（例如，类风湿关节炎对应的 MONDO_0008383）。
• get-study-credible-sets study_id：获取指定研究 ID 的所有可信集。返回置信度、精细定位方法、变异和 p 值信息。
• get-qtl-credible-sets variant_id：获取特定变异 ID 的 QTL 可信集（例如 19_44908822_C_T）。
• get-l2g variant_id [--study-id ID]：返回位点到基因（L2G）的预测/得分，以识别最可能的因果基因。仅需提供 variant_id；使用 --study-id 可筛选特定研究。接受 chr 前缀（例如 chr1_113834946_A_G）。
• get-target-druggability ensembl_id：提供基因/靶点的可成药性数据（小分子、抗体等）和临床试验安全性信息。
• get-associated-targets disease_id：查找与特定疾病 ID（EFO 或 MONDO）关联的所有靶基因。
• get-disease-drugs disease_id [--min-stage STAGE]：查找与某种疾病关联的所有药物和临床候选药物。使用 --min-stage 进行筛选（例如，PHASE_3 表示 III 期或已获批）。
• get-associated-diseases ensembl_id：查找与特定靶点 Ensembl ID 关联的所有疾病。
• search-disease query_string：按名称搜索疾病，以查找其 ID 和其他元数据。
• get-credible-sets-near-target ensembl_id [--window N]：获取某靶点的可信集，并筛选出位于靶点周围基因组窗口范围内的可信集。可用于查找基因附近的变异。
• custom-query query [--variables '{}']：运行原始 GraphQL 查询，以获取其他 Open Targets 数据。

L2G 查询用法

get-l2g 命令有两种模式：

• 仅变异（get-l2g <variant_id>）：返回所有研究中以该变异为 lead variant 的所有可信集合的 L2G 预测。结果数量可能很多（例如数百条）。当用户希望全面了解某个位点最可能由哪个基因致因，或未提及特定研究时，请使用此模式。
• 变异 + 研究（get-l2g <variant_id> --study-id <study_id>）：仅返回该特定研究中可信集合的 L2G 预测。当用户询问某项特定 GWAS 研究，或需要缩小结果范围时，请使用此模式。

结果不完整警告： 仅变异模式可能返回数百个可信集合。默认的 --page-size 为 200，因此，如果 API 报告的 count 高于返回的 rows 数量，说明你看到的结果不完整。请务必比较 count 与实际的行数。如果两者不一致，请增大 --page-size，或告知用户仅检索到了部分结果。

按区域查询

若要查找变异“靠近”某个基因的研究，请使用 get-credible-sets-near-target。该命令基于基因组位置进行灵活搜索，改进了基础 API：uv run scripts/query_opentargets.py --output /tmp/results.json get-credible-sets-near-target ENSG00000156515 --window 500000

请注意，Open Targets GraphQL 架构在 credibleSets 中包含 regions 参数，但它会与预先计算的区域字符串（例如 chr10:68769984-69903496）进行精确匹配，而且数据也不完整。请使用 get-credible-sets-near-target，因为它支持搜索重叠的基因组范围。

此命令会获取与目标相关的可信集合，并根据变异的基因组位置在 Python 中对其进行筛选。

高级 GraphQL 查询

如果需要查询内置子命令未提供的端点或字段，请使用 custom-query 子命令。

编写自定义查询前： 请阅读参考文档，了解 API 架构、类型并查看示例查询。完整的架构详情、端点和示例请参阅 references/OpenTargets_GraphQL_Guide.md。

示例：查找某种疾病的药物

uv run scripts/query_opentargets.py custom-query \
  query drugsForDisease($id: String!) {
    disease(efoId: $id) {
      name
      drugAndClinicalCandidates {
        count
        rows {
          maxClinicalStage
          drug {
            id
            name
          }
        }
      }
    }
  }' \
--variables '{"id": "EFO_1001006"}'
--output '/tmp/opentargets_result.json'

置信度星级

Open Targets Platform 会根据精细定位方法和质量检查，为每个可信集合分配一个置信度等级。这些等级对应于平台 UI 中显示的星级：

星级	置信度字符串（API 值）
★★★★（4 星）	SuSiE fine-mapped credible set with in-sample LD
★★★（3 星）	SuSiE fine-mapped credible set with out-of-sample LD
★★（2 星）	`PICS fine-mapped credible set extracted from summary
: : statistics` :
★（1 星）	PICS fine-mapped credible set based on reported top hit
无	Unknown confidence

当用户询问“N 星置信度”时，请将其需求与 API 响应中 confidence 字段的相应字符串匹配。

提示和常见错误

• ID 格式：
  • 疾病 ID 通常是 MONDO ID（例如，类风湿关节炎对应 MONDO_0008383）或 EFO ID（例如，EFO_0009460）。使用 search-disease 命令查找正确的 ID。
  • 靶标 ID 必须是 Ensembl ID（例如，ENSG00000169083），不能是 HGNC 符号。如果只有基因符号，可能需要先使用自定义 GraphQL search 查询进行映射。
  • 变异 ID 的格式为 chromosome_position_ref_alt（例如，1_154426264_C_T）。工具会自动去除 chr 前缀（例如，chr1_154426264_C_T）。
  • 研究 ID 可以是 GWAS Catalog ID（例如，GCST90204201），也可以是项目专属 ID（例如，FINNGEN_R12_RX_CROHN_2NDLINE）。
• 截断：为保护上下文窗口，工具会截断超过 --limit 的数组。如果看到 "_truncated"，且确实需要更多数据，可以使用更高的限制值重新运行查询，但要谨慎设置较大的限制值。始终使用 --output 标志将结果保存到文件，以避免终端输出被截断。
• 分页和结果不完整：--page-size 选项（默认值：200）控制从 API 获取的条目数。**始终检查响应中的 count 字段，并与实际返回的 rows 数量进行比较。**如果 count 大于行数，则数据不完整——可以增大 --page-size 以获取更多数据，或告知用户返回的只是部分结果集。这一点对于不带 --study-id 的 get-l2g 尤其重要，因为它可能返回数百个可信集。