查询 Open Targets 靶点-疾病关联…

通过 Open Targets Platform GraphQL API 查询靶点-疾病关联、药物靶点发现、可成药性/安全性与遗传学/组学证据，用于治疗靶点识别。

适用场景

解决思路

1. 使用前先安装并确保 uv 在 PATH 中：阅读 uv skill 并按其 Setup 操作。
2. 如果工作区根目录不存在 .licenses/opentargets_database_LICENSE.txt，先显著通知用户查看 https://platform-docs.opentargets.org/licence 的条款，然后创建该文件，记录通知文本和时间戳。
3. 始终通过提供的 helper scripts 查询数据库，不要直接访问数据库；脚本会自动执行公平使用并实现重试逻辑。
4. 始终使用 scripts/query_opentargets.py 查询，处理 API 通信、重试、格式化，并自动截断过大响应；绝不要自己写 curl 或类似请求。
5. 执行命令格式：uv run scripts/query_opentargets.py --output /tmp/opentargets_results.json [OPTIONS] COMMAND [ARGS]...
6. 始终提供 --output PATH（必需），将 JSON 输出写入文件；输出可能很大。
7. 用 jq 或自己的代码处理 --output 生成的 JSON 文件。
8. 使用 --limit N 限制数组返回项数（默认 50）；初步探索时用较小值如 10。
9. 使用 --page-size N 设置 API 分页大小（默认 200）；需要更多结果时增加（例如一项研究有很多 credible sets）。
10. 如果本次使用了该 skill，确保在输出中提及。
11. get-gwas-studies disease_id：获取与特定疾病 ID 关联的所有 GWAS 研究（如 MONDO_0008383 对应 Rheumatoid Arthritis）。
12. get-study-credible-sets study_id：获取给定 study ID 的所有 credible sets（如 FINNGEN_R12_RX_CROHN_2NDLINE），返回 confidence、finemapping method、variant、p-value 信息。
13. get-qtl-credible-sets variant_id：获取特定 variant ID 的 QTL credible sets（如 19_44908822_C_T）。
14. get-l2g variant_id [--study-id ID]：返回 locus-to-gene (L2G) 预测/评分，识别最可能 causal gene；仅 variant_id 必需；用 --study-id 过滤到特定研究；接受 chr 前缀（如 chr1_113834946_A_G）。
15. get-target-druggability ensembl_id：提供 gene/target 的 tractability 数据（small molecule、antibody 等）和临床试验安全信息。
16. get-associated-targets disease_id：查找与特定疾病 ID（EFO 或 MONDO）关联的所有 target genes。
17. get-disease-drugs disease_id [--min-stage STAGE]：查找与疾病关联的所有 drugs 和 clinical candidates；用 --min-stage 过滤（如 PHASE_3 表示 Phase III 或 Approved）。
18. get-associated-diseases ensembl_id：查找与特定 target Ensembl ID 关联的所有疾病。
19. search-disease query_string：按名称搜索疾病，以找到其 ID 和其他 metadata。
20. get-credible-sets-near-target ensembl_id [--window N]：获取 target 的 credible sets，并过滤到 target 周围 genomic window 内的那些；用于查找 gene “nearby” 的 variants。
21. custom-query query [--variables '{}']：运行原始 GraphQL 查询以获取任何其他 Open Targets 数据。
22. get-l2g 仅 variant 模式（get-l2g <variant_id>）：返回该 variant 作为 lead variant 的所有研究的所有 credible sets 的 L2G 预测；结果可能很多（如数百）；当用户想要 locus 最可能 causal gene 的广泛视图或未指定 study 时使用。
23. get-l2g variant + study 模式（get-l2g <variant_id> --study-id <study_id>）：仅返回该特定 study 的 credible sets 的 L2G 预测；当用户询问特定 GWAS study 或需要缩小结果时使用。
24. 对仅 variant 模式检查不完整结果：可能返回数百 credible sets；默认 --page-size 200；如果 API 报告的 count 高于返回的 rows 数量，说明结果不完整；比较 count 和实际 rows 数；如不同，增加 --page-size 或告知用户只检索到子集。
25. 要查找 gene “nearby” 的 variants 的 studies，使用 get-credible-sets-near-target，它基于 genomic position 做灵活搜索：uv run scripts/query_opentargets.py --output /tmp/results.json get-credible-sets-near-target ENSG00000156515 --window 500000
26. 注意 Open Targets GraphQL schema 的 credibleSets 有 regions 参数，但它对预计算 region 字符串（如 chr10:68769984-69903496）做精确匹配且有一些缺失数据；应使用 get-credible-sets-near-target，因为它允许 genomic range overlap 搜索。
27. get-credible-sets-near-target 会获取与 target 关联的 credible sets，并在 Python 中基于 variant 的 genomic position 过滤。
28. 若需要查询内置子命令未暴露的 endpoints 或 fields，使用 custom-query 子命令。
29. 写 custom query 前先阅读 references/OpenTargets_GraphQL_Guide.md，了解 API schema、types 和示例查询。
30. 示例 custom query 查找疾病药物：`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'`
31. 当用户询问 N-star confidence 时，匹配 API 响应 confidence 字段中的对应字符串：4 stars = SuSiE fine-mapped credible set with in-sample LD；3 stars = SuSiE fine-mapped credible set with out-of-sample LD；2 stars = PICS fine-mapped credible set extracted from summary statistics；1 star = PICS fine-mapped credible set based on reported top hit；None = Unknown confidence。
32. ID 格式：Disease IDs 通常是 MONDO IDs（如 MONDO_0008383）或 EFO IDs（如 EFO_0009460）；用 search-disease 找正确 ID。
33. Target IDs 必须是 Ensembl IDs（如 ENSG00000169083），不是 HGNC symbols；若只有 gene symbol，可能需要先用 custom GraphQL search 查询映射。
34. Variant IDs 格式为 chromosome_position_ref_alt（如 1_154426264_C_T）；chr 前缀（如 chr1_154426264_C_T）会被工具自动去除。
35. Study IDs 可以是 GWAS Catalog IDs（如 GCST90204201）或 project-specific IDs（如 FINNGEN_R12_RX_CROHN_2NDLINE）。
36. Truncation：工具会截断超过 --limit 的数组以保护 context window；如果看到 "_truncated"，可在确实需要更多数据时用更高 limit 重新查询，但对大 limit 要谨慎；始终使用 --output 保存结果到文件，避免终端输出截断。
37. Pagination and incomplete results：--page-size（默认 200）控制从 API 获取多少项；始终检查响应中的 count 字段并与实际返回的 rows 数量比较；如果 count > rows 数，数据不完整——要么增加 --page-size 获取更多，要么告知用户只返回了部分结果；这对不带 --study-id 的 get-l2g 尤其重要。

适用边界 · 注意事项

• 不适用于查询 Open Targets Platform 未覆盖的数据或非 Open Targets 数据源。
• 无法安装/运行 uv、无法访问 Open Targets GraphQL API、或不能按许可证要求创建通知文件时。
• 不应在需要直接写 curl、直接访问数据库或绕过公平使用/重试逻辑的场景中使用。