alterlab-clinpgx

ClinPGx 数据库

概览

ClinPGx（临床药物基因组学数据库）是临床药物基因组学领域的综合资源，也是 PharmGKB 的继任者。它整合了 PharmGKB、CPIC 和 PharmCAT 的数据，提供经过整理的基因变异如何影响药物反应的信息。获取用于精准医疗的基因-药物配对、临床指南、等位基因功能和药品标签。

何时使用此技能

适用于：

• 基因-药物相互作用 — 变异如何影响药物代谢、疗效或毒性
• CPIC 指南 — 基于证据的药物基因组学临床实践指南
• 等位基因信息 — 等位基因功能、频率和表型数据
• 药品标签 — FDA 及其他监管机构的药物基因组学标签
• 药物基因组学注释 — 关于基因-药物-疾病关系的整理后文献
• 临床决策支持 — 用于表型转换和自定义基因型解读的 PharmDOG
• 精准医疗 / 个性化给药 — 基于基因型的给药建议
• 药物代谢 — CYP450 和其他药物基因的功能
• 药物不良反应 — 药物毒性的遗传风险因素

不适用的情况

场景	改用
生殖系/体细胞变异致病性或 ClinVar 审查状态	alterlab-clinvar
某个变异在人群中的等位基因频率（gnomAD v4）	alterlab-gnomad
不涉及遗传因素的药物-药物相互作用或一般药理学	alterlab-drugbank
FDA 不良事件报告、召回或全文标签搜索	alterlab-fda

设置和访问要点

只需使用 requests。通过临时依赖运行辅助脚本（或任何代码片段），无需管理 venv：

uv run --with requests python scripts/query_clinpgx.py
# or, inside an existing project venv: uv pip install requests

基础 URL：https://api.clinpgx.org/v1/data/ — 旧版 api.pharmgkb.org 主机已于 2026-07-20 停用，因此较旧的 PharmGKB 脚本必须切换主机名（路径不变）。

• 资源寻址：ClinPGx 资源通过路径中的 ClinPGx 登录 ID 寻址（例如，基因 CYP2D6 = PA128，CYP2C9 = PA126），而不是通过基因符号或 rsID 寻址。要解析符号或 rsID，请使用参数查询集合端点（例如 GET /v1/data/gene?symbol=CYP2D6、GET /v1/data/variant?symbol=rs4244285），并从响应中读取登录 ID。
• 响应封装（已验证）：每个响应都是 JSON 对象 {"status": "success"|"fail", "data": [...]} — 载荷绝不会是裸列表。请从 response.json()["data"] 读取结果；当 status == "fail" 时，data 为 {"errors": [...]}（例如，“No results matching criteria”）。
• 查询参数约定**（已验证）**：基因按 relatedGenes.symbol 过滤（.name 形式会失败），而化学物质/药物按 relatedChemicals.name 过滤 — relatedChemicals.symbol 会静默返回 status: "fail" 且结果数为零。gene 集合使用 ?symbol=，chemical 集合使用 ?name=，variant 接受 ?symbol=/?name=。
• 速率限制：每秒最多 2 次请求；请求过多会返回 HTTP 429。请在请求之间加入约 500ms 的延迟。
• 身份验证：基本访问无需身份验证。
• 数据许可：Creative Commons Attribution-ShareAlike 4.0 International。
• 如需大量使用 API，请通知 ClinPGx 团队：[email protected]。

核心工作流

1. 解析标识符 — 使用带有 symbol= 参数的集合端点，将基因符号 / rsID 转换为 ClinPGx 登录 ID。
2. 查询相关资源 — gene、chemical、guidelineAnnotation、 summaryAnnotation、variantAnnotation、variant、label 或 pathway。 不存在 /allele 资源 — 星号等位基因定义和人群频率请使用 PharmVar (https://www.pharmvar.org/)。
3. 推导基因-药物关系 — 从指南注释中获取（基因对应 relatedGenes.symbol，药物对应 relatedChemicals.name），或使用 /report/pair/{firstObjId}/{secondObjId}/{resultType} 端点。
4. 按证据等级筛选 — 临床使用优先选择 1A/1B/2A 级；请对照实时 OpenAPI 规范确认字段名称。
5. 遵守速率限制 — 控制请求速率，遇到 429 时采用退避策略重试，并缓存结果。

如需使用包含速率限制和错误处理的现成函数，请参阅 scripts/query_clinpgx.py。

路由指南

• 需要某项资源（基因、化学物质、基因-药物对、CPIC 指南、等位基因 / PharmVar、变异、临床注释、标签、通路）的确切代码？ 请阅读 references/endpoints-and-capabilities.md。
• 正在执行端到端任务（临床决策支持、基因面板分析、药物安全评估、人群药物基因组学、文献综述）或处理常见用例？ 请阅读 references/query-workflows.md。
• 需要可靠的 API 接入机制（速率限制、重试、缓存）？ 请阅读 references/rate-limiting-and-error-handling.md。
• 需要完整的端点 / 参数 / 架构详情？ 请阅读 references/api_reference.md。

参考资料

• references/api_reference.md — 完整的端点列表、请求 / 响应格式、筛选运算符、数据架构、速率限制详情和故障排除。
• references/endpoints-and-capabilities.md — 涵盖全部九个能力领域（基因、药物 / 化学物质、基因-药物对、CPIC 指南、等位基因 / PharmVar、变异、临床注释、药品标签、通路）的代码示例，包括关键药物基因和证据等级定义。
• references/query-workflows.md — 五个端到端工作流（决策支持、基因面板、药物安全、人群药物基因组学、文献综述）以及常见用例（预先检测、药物治疗管理、试验资格判定）。
• references/rate-limiting-and-error-handling.md — 可复用的辅助函数，用于速率限制、指数退避重试和结果缓存。

PharmDOG 工具

PharmDOG（前身为 DDRx）是 ClinPGx 的临床决策支持工具，用于解读药物基因组检测结果。其功能包括：表型转换计算器（针对影响 CYP2D6 的药物相互作用调整表型）、自定义基因型输入、二维码报告分享、可选的指导来源（CPIC、DPWG、FDA）以及多药物分析。访问： https://www.clinpgx.org/pharmacogenomic-decision-support

重要说明

数据来源 — ClinPGx 汇总了 PharmGKB（现已纳入 ClinPGx）、CPIC、 PharmCAT、DPWG 以及 FDA/EMA 标签的数据。截至 2025 年 7 月，所有 PharmGKB URL 均会重定向至对应的 ClinPGx 页面。

临床注意事项 — 临床应用前务必核实证据强度；等位基因频率在不同人群间可能存在显著差异；需考虑表型转换（药物相互作用）和多基因效应；非遗传因素（年龄、器官功能）也会影响药物反应；并非所有检测方法都能检测到所有具有临床意义的等位基因。

数据更新 / API 稳定性 — ClinPGx 会持续更新；请查看发布日期和 ClinPGx 博客 (https://blog.clinpgx.org/)。API 端点相对稳定，但在开发过程中仍可能发生变更 — 请固定版本，并在生产环境使用前于开发环境中进行测试。

附加资源

• ClinPGx 网站：https://www.clinpgx.org/
• ClinPGx 博客：https://blog.clinpgx.org/
• API 文档：https://api.clinpgx.org/
• CPIC 网站：https://cpicpgx.org/
• PharmCAT：https://pharmcat.clinpgx.org/
• PharmVar（星号等位基因）：https://www.pharmvar.org/
• ClinGen：https://clinicalgenome.org/
• 联系邮箱：[email protected]（用于大量 API 调用）