tooluniverse-pharmacogenomics

计算，而非描述

需要计算（统计、数据处理、评分、信息增强）时，请通过 Bash 编写并运行 Python 代码。不要只描述打算怎么做——请实际执行并报告结果。使用 ToolUniverse 工具检索数据，然后用 Python（pandas、scipy、statsmodels、matplotlib）进行分析。

药物基因组学（PGx）研究技能

系统化 PGx 分析：确定基因-药物配对，检索 CPIC 给药指南，使用 PharmGKB 标注等位基因和变异，检查 FDA PGx 生物标志物标签，并生成按证据等级划分的临床建议。

使用场景

• “CYP2D6 有哪些 CPIC 指南？”
• “根据 CYP2D6 弱代谢者状态，获取可待因的给药建议”
• “哪些药物的 FDA 药物基因组学生物标志物涉及 CYP2C19？”
• “查找 rs1799853 的 PharmGKB 临床注释”
• “该患者的 CYP2D6 基因型是否与他莫昔芬给药有关？”
• “CYP2D6*4 的功能状态是什么？”
• “列出 CYP2D6 所有 CPIC A 级基因-药物配对”

工作流概览

Input (gene/drug/variant/phenotype)
  |
  v
Phase 0: Disambiguation (resolve gene symbols, drug names, rsIDs)
  |
  v
Phase 1: Gene-Drug Pair Identification (CPIC pairs + evidence levels)
  |
  v
Phase 2: Guideline & Dosing Retrieval (CPIC recommendations + PharmGKB)
  |
  v
Phase 3: Allele & Variant Annotation (star alleles, function, activity scores)
  |
  v
Phase 4: FDA Biomarker Labeling (regulatory PGx status)
  |
  v
Phase 5: Cross-Database Enrichment (EpiGraphDB, DGIdb, OpenTargets PGx)
  |
  v
Phase 6: Report (evidence-graded clinical summary)

---

阶段 0：消歧

在查询 PGx 数据库之前，将用户输入解析为规范标识符。

PharmGKB_search_genes：query（必填字符串，例如 “CYP2D6”）。返回 {status, data: [{id, symbol, name}]}。

• 用于获取 PharmGKB 基因登录 ID（例如 CYP2D6 的 “PA128”）。

PharmGKB_search_drugs：query（必填字符串，例如 “codeine”）。返回 {status, data: [{id, name, types}]}。

• 用于获取 PharmGKB 化学物质 ID（例如可待因的 “PA449088”）。

PharmGKB_search_variants：query（必填字符串，rsID，例如 “rs1799853”）。返回 {status, data: [{id, symbol, changeClassification, clinicalSignificance}]}。

• 用于解析 rsID 并查找 PharmGKB 注释 ID。

CPIC_get_drug_info：name（必填字符串，小写，例如 “codeine”）。返回药物标识符，包括 drugid、rxnormid、drugbankid、atcid、guidelineid 和 flowchart URL。

• 也可用于解析药物名称：可以通过药物名称直接查找 guidelineid。

CPIC_get_gene_info：symbol（必填字符串，例如 “CYP2D6”）。返回基因坐标、PharmGKB/HGNC/Ensembl ID、lookupmethod（ACTIVITY_SCORE 或 PHENOTYPE）以及等位基因频率方法。

---

阶段 1：识别基因-药物配对

CPIC_search_gene_drug_pairs：gene_symbol（字符串）、cpiclevel（"A"/"B"/"C"/"D"）、limit（整数，默认值 50）。返回 {status, data: [{genesymbol, drugid, cpiclevel, guidelineid, pgxtesting, clinpgxlevel, usedforrecommendation}]}。

• 按证据等级筛选的主要工具。CPIC 等级：A = 证据最强/可采取行动，B = 中等，C = 信息性，D = 证据不足。
• PostgREST 自动规范化：接受普通基因符号（例如 “CYP2D6”）——该工具会自动添加 eq. 前缀。
• 也接受别名：gene 和 gene_symbol 均可解析为 genesymbol。

CPIC_get_gene_drug_pairs：genesymbol（必填字符串）。返回某个基因的所有配对，包括 drug: {name}、citations、guidelineid。

• 响应中会返回药物名称（搜索工具只返回 RxNorm ID）。

CPIC_list_drugs：无参数。返回所有带指南 ID 的药物。用于浏览。

CPIC_list_pgx_genes：无参数。返回 CPIC 整理的所有 PGx 基因及其 symbol、lookupmethod、ensemblid。

EpiGraphDB_get_gene_drug_associations：gene_name（必填字符串，例如 “CYP2D6”）。返回 {status, data: {gene_drug_associations: [{gene, drug, source, pharmgkb_evidence, cpic_level, pgx_on_fda_label, guideline}]}}。

• 一次调用即可汇总 CPIC 和 PharmGKB 证据及 FDA 标签状态。适合快速查看概况。

查找指南 ID

不要死记指南 ID。使用 CPIC_list_guidelines(gene="CYP2D6") 或 CPIC_list_guidelines(drug="codeine") 来查找。每条结果都包含数字 id（用于 CPIC_get_recommendations）和字符串 clinpgxid（用于 PharmGKB_get_dosing_guidelines）。

---

阶段 2：检索给药指南

CPIC_get_recommendations (CPICGetRecommendationsTool)：guideline_id（整数，或使用 drug/drug_name 字符串自动解析）、limit（整数，默认值为 50）、offset（整数）。返回 {status, data: {guideline_id, recommendations: [{drugrecommendation, classification, phenotypes, implications, activityscore, lookupkey, population, drug: {name}}], count}}。

• 推荐用法：CPIC_get_recommendations(drug="codeine", limit=50) — 通过 CPIC API 将药物名称自动解析为 guideline_id，并使用 RxNorm ID 匹配，在包含多种药物的指南中进行筛选（例如，CYP2D6 阿片类药物指南涵盖 codeine 和 tramadol）。
• classification：可为 "Strong"、"Moderate" 或 "Optional"。phenotypes：基因到代谢者表型的映射。activityscore：基因到活性评分的映射。
• 备用方法：使用 CPIC_get_drug_info(name="codeine") 提取 guidelineid，然后调用 CPIC_get_recommendations(guideline_id=100416, limit=50)。

CPIC_get_drug_info：name（字符串，必需，小写，例如 "codeine"）。返回 {status, data: [{drugid, guidelineid, flowchart, rxnormid, drugbankid}]}。

• 便捷之处：可直接返回 guidelineid。也适用于提取 DrugBank/ATC ID。

PharmGKB_get_dosing_guidelines：guideline_id（字符串，必需——使用 CPIC_list_guidelines 中的 clinpgxid，例如 "PA166251445"）。返回 {status, data: {id, name, level, literature: [{title, crossReferences}], link}}。

• 提供 CPIC 指南元数据、文献引用以及完整指南的链接。

CPIC_list_guidelines：gene（字符串，可选）、drug（字符串，可选）。返回 {status, data: [{id, name, url, genes, clinpgxid}]}。返回全部约 29 项指南；支持按基因/药物内置筛选。

• 使用此工具查找 PharmGKB_get_dosing_guidelines 所需的 clinpgxid 值。

注意：PharmGKB_get_clinical_annotations 需要 annotation_id（例如 "1447954390"）。要查找注释 ID，请先使用 PharmGKB_search_variants(query=rsID)，然后从结果中提取注释 ID。

注意事项

• Warfarin（指南 100425）：基于算法给药；CPIC_get_recommendations 返回 0 行。请引导用户访问 CPIC 网站或 PharmGKB。
• PharmGKB 指南链接：使用 clinpgxid（例如 "PA166251445"），而不是 pharmgkbid（旧格式会返回 404）。
• 多基因指南：TCA 指南（100414）涵盖 CYP2D6 和 CYP2C19；其建议包含表型组合。
• 药物名称大小写：CPIC_get_drug_info 要求使用小写。CPIC_get_recommendations 的 drug= 使用 ilike 匹配（不区分大小写）。
• CPIC_get_recommendations 返回包装后的数据：响应为 {status, data: {guideline_id, recommendations: [...], count}}——建议嵌套在 data.recommendations 下。

---

第 3 阶段：等位基因与变异注释

CPIC_get_alleles：genesymbol（字符串，必填）、limit（整数，默认值为 50）。返回 {status, data: [{name, clinicalfunctionalstatus, activityvalue, functionalstatus}]}。

• 使用 clinicalfunctionalstatus（不要使用可能为 null 的 functionalstatus）。取值为："Normal function"（功能正常）、"Decreased function"（功能降低）、"No function"（无功能）、"Increased function"（功能增强）、"Uncertain function"（功能不确定）、"Unknown function"（功能未知）。
• activityvalue：数字字符串（例如 "1.0"、"0.5"、"0.0"）或 "n/a"。

PharmGKB_search_variants：query（字符串，必填，rsID）。返回变异分类和临床意义。

PharmGKB_get_clinical_annotations：annotation_id（字符串，必填，例如 "1447954390"）。返回 {status, data: {accessionId, allelePhenotypes: [{allele, phenotype, limitedEvidence}], levelOfEvidence: {term}}}。

• 必须提供 annotation_id——不能直接按基因或药物查询。可通过 PharmGKB_search_variants(query=rsID) 或 PharmGKB 网站查找 ID。
• levelOfEvidence.term： "1A"、"1B"、"2A"、"2B"、"3"、"4"（PharmGKB 证据等级）。

PharmGKB_get_gene_details：gene_id（字符串，必填，PharmGKB 登录号，例如 "PA128"）。返回详细基因信息，包括等位基因定义文件和 VIP 引文。

PharmGKB_get_drug_details：drug_id（字符串，必填，PharmGKB 化学品 ID，例如 "PA449088"）。返回药物元数据，包括 SMILES、InChI 和类型（Drug/Prodrug）。

OpenTargets_drug_pharmacogenomics_data：chemblId（字符串，必填，例如 "CHEMBL1201560"）、size（整数）。返回来自 OpenTargets 的 PGx 变异数据，包括变异后果和药物关联。

• 按药物（ChEMBL ID）查询，而非按基因查询。若已知 ChEMBL ID，且需要 OpenTargets 的 PGx 变异注释，请使用此工具。

代谢者状态推理

弱代谢者的酶活性降低或缺失。其临床意义完全取决于药物是活性药物还是前药：

• 活性药物 + 弱代谢者：药物蓄积 → 毒性风险（例如，可待因是前药——不适用于此情况；但去甲替林是活性药物——PM → 血药浓度升高 → 副作用）。
• 前药 + 弱代谢者：转化为活性形式的量减少 → 疗效降低（例如，可待因 → 吗啡；氯吡格雷 → 活性噻吩并吡啶）。
• 前药 + 超快代谢者：活化过量 → 毒性（典型案例：CYP2D6 UM 患者服用可待因 → 吗啡蓄积 → 呼吸抑制）。

活性药物与前药的区别决定了临床关注的方向。在解读任何代谢者表型之前，务必先判断正确。

星号等位基因推理：不要死记等位基因表。推理逻辑始终是：等位基因功能状态（正常 / 降低 / 无功能）→ 双倍型 → 预测酶活性 → 表型（UM/NM/IM/PM）→ 临床建议。使用 CPIC_get_alleles(genesymbol=...) 查询任何特定等位基因的功能状态。

PharmVar——星号等位基因命名的权威机构：CPIC_get_alleles 提供 CPIC 自己重新整理的临床功能信息，而 PharmVar（药物基因变异联盟）才是真正定义星号等位基因的机构——包括其组成变异、单倍型结构和活性评分，涉及 CYP2D6、CYP2C9、CYP2C19、CYP2B6、DPYD 等。PharmVar_list_genes()（无参数）会列出所有经过整理的药物基因及其等位基因数量；PharmVar_get_alleles(gene=...) 会返回某个基因的完整等位基因定义集。当你需要查询某个等位基因权威的变异级定义（例如，确认 CYP2D6*17 究竟由哪些 SNP 构成），而不只是查看 CPIC 指定的功能标签，或者当 CPIC 自己整理的信息似乎与等位基因命名实际规定的内容不一致时，请使用 PharmVar。这与 tooluniverse-clinical-terminology-lookup 中的 StarAlleles_search 不同，后者是快速自动补全 / 输入提示查询，而非等位基因定义的数据源。需要 PHARMVAR_API_KEY（在 https://www.pharmvar.org/ 注册）——两个工具都正确声明了 required_api_keys，因此没有 API 密钥时会从 tu list 中正常排除，而不会在调用时失败；由于当前环境没有可用的 API 密钥，上述参数文档是根据 schema 整理的。

---

第 4 阶段：FDA 生物标志物标注

fda_pharmacogenomic_biomarkers：drug_name（字符串，可选）、biomarker（字符串，可选，例如 "CYP2D6"）、limit（整数，默认值为 10）。返回 {status, count, shown, results: [{Drug, TherapeuticArea, Biomarker, LabelingSection}]}。

• 要获取完整结果，始终传入 limit=1000（默认值为 10）。
• LabelingSection 的取值："Dosage and Administration"、"Clinical Pharmacology"、"Precautions"、"Use in Specific Populations"、"Boxed Warning"、"Contraindications"。
• 可以按药物、生物标志物或两者查询。
• 并非所有药物都有相关条目（例如，SLCO1B1 没有辛伐他汀条目；对于 SLCO1B1 药物基因组学检测，请使用瑞舒伐他汀）。

FDA_get_pharmacogenomics_info_by_drug_name：drug_name（字符串，必填）。返回 FDA 标签中的药物基因组学章节，包含品牌名 / 通用名。适合查找 FDA 实际标签中的药物基因组学标注文本。

FDA 药物基因组学标签推理

LabelingSection 字段指明了药物基因组学信息的可操作性。"Boxed Warning" 或 "Contraindications" 表示某些基因型可能需要进行检测，或药物对某些基因型患者禁用——紧急程度最高。"Dosage and Administration" 表示基因型会直接决定剂量选择。"Clinical Pharmacology" 通常仅提供信息（药代动力学 / 药效学数据），而非处方指示。如有疑问，请使用 FDA_get_pharmacogenomics_info_by_drug_name 获取完整标签文本。

---

阶段 5：跨数据库补充信息

DGIdb_get_drug_gene_interactions：genes（必需的字符串数组，例如 ["CYP2D6"]）、interaction_types（数组，可选）、interaction_sources（数组，可选）。返回药物-基因相互作用及其来源。

• 覆盖范围比 CPIC 更广；包含非 PGx 相互作用。
• 客户端会对 interaction_types 和 sources 参数应用筛选。

DGIdb_get_gene_druggability：genes（必需的字符串数组）。返回 {status, data: {data: {genes: {nodes: [{name, geneCategories}]}}}}。

• 返回基因类别（例如 “CLINICALLY ACTIONABLE”、“DRUGGABLE GENOME”）。

PharmGKB_get_dosing_guidelines：（也见阶段 2）提供 DPWG（荷兰药物遗传学工作组）指南，以及 CPIC 指南。

OpenTargets_drug_pharmacogenomics_data：chemblId（必需的字符串）、size（整数）。返回来自 OpenTargets 平台的 PGx 变异注释。

• 以额外的变异级 PGx 证据补充 CPIC 数据。

PGx 相关药物的不良事件信号检测

FAERS_filter_serious_events：drug_name（必需的字符串）、seriousness_type（“all”/“death”/“hospitalization”/“disability”/“life_threatening”）、adverse_event（字符串，可选）。用于检测 PGx 相关药物的严重不良事件信号——例如，在 CYP2D6 UM 状态的背景下，检测可待因相关的呼吸抑制报告。adverse_event 参数会筛选出包含该特定反应术语的报告。

可选：使用 DisGeNET_get_vda 查询变异-疾病关联（需要 DISGENET_API_KEY）。

---

PGx 检测何时会改变临床决策

只有当药物治疗指数较窄、由多态性酶代谢，且基因型能够可靠预测结果时，PGx 检测才会改变临床决策。如果药物治疗指数较宽，或通过多条冗余途径清除，那么即使存在变异，PGx 状态也很少会改变处方决策。

证据分级——推理方法：CPIC 的 A/B 级代表可采取行动的证据；C/D 级仅供参考。PharmGKB 的 1A 级表示该注释已纳入 CPIC 或 DPWG 指南——这是置信度最高的级别。3/4 级用于生成假设，并非处方级证据。指南中的 CPIC 推荐强度（强/中等/可选）反映了针对特定表型，基因型与结果之间关联的确定程度。

关键问题不是“这是几级？”，而是“这个级别是否足以支持更改处方？”对于强推荐的 CPIC A 级证据，答案是肯定的。对于 PharmGKB 3 级证据，答案是否定的——可以报告，但不要仅凭这一证据采取行动。

---

关键参数说明

需要牢记的关键参数行为——这些问题确实会导致失败：

• CPIC_get_recommendations：接受 guideline_id（整数）或 drug/drug_name（字符串）。绝不要将 guideline_id 作为字符串传入。
• PharmGKB_get_dosing_guidelines：需要 clinpgxid（例如 “PA166251445”），而不是数字形式的 pharmgkbid。从 CPIC_list_guidelines 获取 clinpgxid。
• PharmGKB_get_clinical_annotations：需要 annotation_id。不能按基因或药物查询。通过 PharmGKB_search_variants(query=rsID) 查找 ID。
• fda_pharmacogenomic_biomarkers：默认的 limit=10 几乎总是太小。请传入 limit=1000。
• CPIC_get_drug_info：药物名称必须使用小写。
• DGIdb_get_drug_gene_interactions 和 DGIdb_get_gene_druggability：genes 是数组，而不是字符串（例如 ["CYP2D6"]）。
• CPIC_search_gene_drug_pairs：返回 RxNorm ID，而不是药物名称。需要药物名称时，请使用 CPIC_get_gene_drug_pairs。

---

CPIC 指南应用推理

CPIC 指南提供基因型 → 表型 → 建议的映射。关键在于知道何时应用这些映射，而不是记住映射本身。使用工具检索针对特定表型的具体建议。推理链如下：

1. 是否存在针对该基因-药物组合的 CPIC 指南？（A级或B级 = 可采取行动）
2. 患者的表型是什么？（根据双倍型 + 等位基因功能状态确定）
3. 指南对该表型有什么建议？（使用 CPIC_get_recommendations 检索）
4. FDA 标签是否提供了进一步支持？（检查 fda_pharmacogenomic_biomarkers）

如果第 1 步的答案是否定的，则回退到 PharmGKB 变异注释，获取按证据评级但非指南性质的信息。

---

回退策略

• 没有 CPIC 指南 -> 使用 PharmGKB_search_variants(query=rsID) 获取变异级注释；检查 EpiGraphDB 中的基因-药物证据
• CPIC_get_recommendations 返回 0 行 -> 检查是否基于算法（华法林）；使用 PharmGKB_get_dosing_guidelines
• CPIC_get_recommendations 自动解析药物失败 -> 回退到 CPIC_get_drug_info(name=drug) + 手动提取 guideline_id
• 没有 FDA 生物标志物条目 -> 检查 DGIdb 中已知的相互作用；检查 EpiGraphDB 的 pgx_on_fda_label 字段
• 未知变异 -> 按 rsID 使用 PharmGKB_search_variants 查询；若无结果，则注明该变异尚未表征
• 需要从 RxNorm ID 获取药物名称 -> 使用 CPIC_get_gene_drug_pairs（返回 drug: {name}），而不是 CPIC_search_gene_drug_pairs（仅返回 RxNorm ID）
• 未知 PharmGKB annotation_id -> 从 PharmGKB 网站或通过 PharmGKB_search_variants(query=rsID) 获取注释 ID
• 需要额外的 PGx 变异数据 -> 使用 OpenTargets_drug_pharmacogenomics_data(chemblId=...) 并提供 ChEMBL ID

---

示例工作流

从药物开始（可待因 + CYP2D6 PM）：CPIC_get_recommendations(drug="codeine", limit=50) → 筛选 phenotypes.CYP2D6="Poor Metabolizer" → 强烈建议：避免使用可待因。然后使用 CPIC_get_alleles(genesymbol="CYP2D6", limit=100) 确认星号等位基因功能（例如，*4/*4 → 无功能，AS 0.0）。接着使用 fda_pharmacogenomic_biomarkers(drug_name="codeine", limit=1000) 确认 FDA 标签状态。也可从基因开始：使用 CPIC_get_gene_drug_pairs(genesymbol="CYP2D6") 列出所有相关药物。

从基因开始（所有 CYP2C19 药物）：使用 CPIC_search_gene_drug_pairs(gene_symbol="CYP2C19", cpiclevel="A") 获取 A 级配对。使用 EpiGraphDB_get_gene_drug_associations(gene_name="CYP2C19") 一次性查看 CPIC + PharmGKB + FDA 标签概览。使用 fda_pharmacogenomic_biomarkers(biomarker="CYP2C19", limit=1000) 查看完整的 FDA 覆盖情况。

从变异开始（rs1799853）：PharmGKB_search_variants(query="rs1799853") → CYP2C9 变异及其药物反应相关性。CPIC_get_alleles(genesymbol="CYP2C9", limit=100) → 映射到 *2，即“功能降低”。CPIC_get_gene_drug_pairs(genesymbol="CYP2C9") → 华法林、苯妥英、NSAIDs。对于每种有指南的药物：CPIC_get_recommendations(drug="phenytoin", limit=50)。

---

药物类别背景（RxClass）

当 PGx 分析需要了解某种底物所属的药物类别，或查找同属一个类别且具有相同代谢酶的所有药物时：使用 RxClass_get_drug_classes(drug_name=...) 获取某种药物所属的所有类别，使用 RxClass_find_classes(query=..., class_type=...) 根据关键词查找类别 ID，并使用 RxClass_get_class_members(class_id=..., rela_source=..., ttys="IN") 列出某个类别中的所有药物。例如：查找所有 SSRI，以便在类别说明中指出哪些药物需要进行 CYP2D6 检测。

FDA 物质标识（FDAGSRS）

如需查询 FDA 标准物质标识（UNII 代码，以及与 ATC、DrugBank、CAS 的交叉引用）：使用 FDAGSRS_search_substances(query=...) 查找 UNII 代码，使用 FDAGSRS_get_substance(unii=...) 获取包含所有名称和交叉引用的完整记录，使用 FDAGSRS_get_structure(unii=...) 获取 SMILES/InChIKey。可用于确认两种药物名称变体（例如，“warfarin sodium”和“warfarin”）是否对应同一 UNII，然后再在 CPIC 或 PharmGKB 中进行交叉引用。

---

限制

• CPIC 涵盖约 29 项指南（约 130 个基因）；许多药物-基因组合没有正式指南。
• 必须查找 PharmGKB 临床注释 ID（无法仅根据基因或药物名称推导出来——可使用 PharmGKB 网站，或使用 PharmGKB_search_variants 按 rsID 查找）。
• 华法林剂量需要通过算法计算（CPIC 网站），无法简单查表得出。
• FDA 生物标志物表可能未能及时反映当前标签变更。
• DisGeNET 需要 API 密钥（DISGENET_API_KEY）。
• CPIC_search_gene_drug_pairs 返回的是 RxNorm 药物 ID，而非药物名称；如需名称，请使用 CPIC_get_gene_drug_pairs。
• 活性评分的解释因基因而异（CYP2D6 使用数值评分；其他基因可能需要根据表型查询）。
• CPIC_get_recommendations 的药物自动解析使用 ilike 匹配——有歧义的药物名称可能匹配到多个条目。