Back to Details

tooluniverse-pharmacogenomics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

COMPUTE, DON'T DESCRIBE

计算而非描述

When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.
当分析需要计算（统计、数据处理、评分、富集分析）时，通过Bash编写并运行Python代码。不要描述你要做什么——直接执行并报告实际结果。使用ToolUniverse工具检索数据，然后用Python（pandas、scipy、statsmodels、matplotlib）进行分析。

Pharmacogenomics (PGx) Research Skill

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

Systematic PGx analysis: resolve gene-drug pairs, retrieve CPIC dosing guidelines, annotate alleles and variants with PharmGKB, check FDA PGx biomarker labeling, and generate evidence-graded clinical recommendations.
系统化PGx分析：解析基因-药物对、检索CPIC给药指南、通过PharmGKB对等位基因和变异进行注释、检查FDA PGx生物标志物标注，并生成循证分级临床建议。

When to Use

适用场景

  • "What CPIC guidelines exist for CYP2D6?"
  • "Get dosing recommendations for codeine based on CYP2D6 poor metabolizer status"
  • "Which drugs have FDA pharmacogenomic biomarkers for CYP2C19?"
  • "Find PharmGKB clinical annotations for rs1799853"
  • "Is this patient's CYP2D6 genotype relevant to tamoxifen dosing?"
  • "What is the functional status of CYP2D6*4?"
  • "List all CPIC level A gene-drug pairs for CYP2D6"
  • "CYP2D6对应的CPIC指南有哪些？"
  • "根据CYP2D6弱代谢者状态，给出可待因的给药建议"
  • "哪些药物针对CYP2C19有FDA药物基因组学生物标志物？"
  • "查找rs1799853的PharmGKB临床注释"
  • "该患者的CYP2D6基因型与他莫昔芬给药相关吗？"
  • "CYP2D6*4的功能状态是什么？"
  • "列出CYP2D6所有CPIC A级基因-药物对"

Workflow Overview

工作流概述

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)
输入（基因/药物/变异/表型）
  |
  v
阶段0：消歧（解析基因符号、药物名称、rsID）
  |
  v
阶段1：基因-药物对识别（CPIC配对+证据等级）
  |
  v
阶段2：指南与给药检索（CPIC建议+PharmGKB）
  |
  v
阶段3：等位基因与变异注释（星型等位基因、功能、活性评分）
  |
  v
阶段4：FDA生物标志物标注（监管PGx状态）
  |
  v
阶段5：跨数据库富集（EpiGraphDB、DGIdb、OpenTargets PGx）
  |
  v
阶段6：报告（循证分级临床摘要）

Phase 0: Disambiguation

阶段0：消歧

Resolve user input to canonical identifiers before querying PGx databases.
PharmGKB_search_genes: 
query
(string REQUIRED, e.g., "CYP2D6"). Returns 
{status, data: [{id, symbol, name}]}
.
  • Use to get PharmGKB gene accession ID (e.g., "PA128" for CYP2D6).
PharmGKB_search_drugs: 
query
(string REQUIRED, e.g., "codeine"). Returns 
{status, data: [{id, name, types}]}
.
  • Use to get PharmGKB chemical ID (e.g., "PA449088" for codeine).
PharmGKB_search_variants: 
query
(string REQUIRED, rsID e.g., "rs1799853"). Returns 
{status, data: [{id, symbol, changeClassification, clinicalSignificance}]}
.
  • Use to resolve rsIDs and find PharmGKB annotation IDs.
CPIC_get_drug_info: 
name
(string REQUIRED, lowercase, e.g., "codeine"). Returns drug identifiers including 
drugid
, 
rxnormid
, 
drugbankid
, 
atcid
, 
guidelineid
, and 
flowchart
URL.
  • Also resolves drug names: can be used to find the 
    guidelineid
    directly from a drug name.
CPIC_get_gene_info: 
symbol
(string REQUIRED, e.g., "CYP2D6"). Returns gene coordinates, PharmGKB/HGNC/Ensembl IDs, 
lookupmethod
(ACTIVITY_SCORE or PHENOTYPE), and allele frequency methodology.
在查询PGx数据库之前，先将用户输入解析为标准标识符。
PharmGKB_search_genes：
query
（字符串 必填，例如"CYP2D6"）。返回
{status, data: [{id, symbol, name}]}
。
  • 用于获取PharmGKB基因 accession 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）以及等位基因频率方法。

Phase 1: Identify Gene-Drug Pairs

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

CPIC_search_gene_drug_pairs: 
gene_symbol
(string), 
cpiclevel
("A"/"B"/"C"/"D"), 
limit
(int, default 50). Returns 
{status, data: [{genesymbol, drugid, cpiclevel, guidelineid, pgxtesting, clinpgxlevel, usedforrecommendation}]}
.
  • Primary tool for filtering by evidence level. CPIC levels: A = strongest/actionable, B = moderate, C = informational, D = insufficient.
  • PostgREST auto-normalization: Accepts plain gene symbols (e.g., "CYP2D6") -- the tool auto-prepends 
    eq.
    prefix.
  • Also accepts aliases: 
    gene
    or 
    gene_symbol
    both resolve to 
    genesymbol
    .
CPIC_get_gene_drug_pairs: 
genesymbol
(string REQUIRED). Returns ALL pairs for one gene including 
drug: {name}
, 
citations
, 
guidelineid
.
  • Returns drug names in response (unlike search which returns RxNorm IDs only).
CPIC_list_drugs: No params. Returns all drugs with guideline IDs. Use for browsing.
CPIC_list_pgx_genes: No params. Returns all PGx genes curated by CPIC with 
symbol
, 
lookupmethod
, 
ensemblid
.
EpiGraphDB_get_gene_drug_associations: 
gene_name
(string REQUIRED, e.g., "CYP2D6"). Returns 
{status, data: {gene_drug_associations: [{gene, drug, source, pharmgkb_evidence, cpic_level, pgx_on_fda_label, guideline}]}}
.
  • Aggregates CPIC + PharmGKB evidence with FDA label status in one call. Good for quick overview.
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标注状态，适合快速概览。

Finding Guideline IDs

查找指南ID

Don't memorize guideline IDs. Use 
CPIC_list_guidelines(gene="CYP2D6")
or 
CPIC_list_guidelines(drug="codeine")
to discover them. Each result includes both the numeric 
id
(for 
CPIC_get_recommendations
) and the 
clinpgxid
string (for 
PharmGKB_get_dosing_guidelines
).
无需记忆指南ID。使用
CPIC_list_guidelines(gene="CYP2D6")
或
CPIC_list_guidelines(drug="codeine")
查找。每个结果均包含数字
id
（用于
CPIC_get_recommendations
）和
clinpgxid
字符串（用于
PharmGKB_get_dosing_guidelines
）。

Phase 2: Retrieve Dosing Guidelines

阶段2：检索给药指南

CPIC_get_recommendations (CPICGetRecommendationsTool): 
guideline_id
(integer, OR 
drug
/
drug_name
string for auto-resolution), 
limit
(int, default 50), 
offset
(int). Returns 
{status, data: {guideline_id, recommendations: [{drugrecommendation, classification, phenotypes, implications, activityscore, lookupkey, population, drug: {name}}], count}}
.
  • Preferred usage: 
    CPIC_get_recommendations(drug="codeine", limit=50)
    — auto-resolves drug name to guideline_id via CPIC API, and filters within multi-drug guidelines (e.g., CYP2D6 opioid guideline covers codeine + tramadol) using RxNorm ID matching.
  • classification
    : "Strong", "Moderate", or "Optional". 
    phenotypes
    : maps gene → metabolizer phenotype. 
    activityscore
    : maps gene → activity score.
  • Fallback: 
    CPIC_get_drug_info(name="codeine")
    to extract guidelineid, then 
    CPIC_get_recommendations(guideline_id=100416, limit=50)
    .
CPIC_get_drug_info: 
name
(string REQUIRED, lowercase, e.g., "codeine"). Returns 
{status, data: [{drugid, guidelineid, flowchart, rxnormid, drugbankid}]}
.
  • Key shortcut: returns 
    guidelineid
    directly. Still useful for extracting DrugBank/ATC IDs.
PharmGKB_get_dosing_guidelines: 
guideline_id
(string REQUIRED -- use 
clinpgxid
from CPIC_list_guidelines, e.g., "PA166251445"). Returns 
{status, data: {id, name, level, literature: [{title, crossReferences}], link}}
.
  • Provides CPIC guideline metadata, literature citations, and link to full guideline.
CPIC_list_guidelines: 
gene
(string, optional), 
drug
(string, optional). Returns 
{status, data: [{id, name, url, genes, clinpgxid}]}
. Returns all ~29 guidelines; supports built-in filtering by gene/drug.
  • Use this to discover 
    clinpgxid
    values for PharmGKB_get_dosing_guidelines.
Note: 
PharmGKB_get_clinical_annotations
requires an 
annotation_id
(e.g., "1447954390"). To discover annotation IDs, use 
PharmGKB_search_variants(query=rsID)
first, then extract annotation IDs from the results.
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阿片类指南涵盖可待因+曲马多）。
  • 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。

Gotchas

注意事项

  • Warfarin (guideline 100425): Algorithm-based dosing; 
    CPIC_get_recommendations
    returns 0 rows. Direct users to CPIC website or PharmGKB.
  • PharmGKB guideline linking: Use 
    clinpgxid
    (e.g., "PA166251445"), NOT 
    pharmgkbid
    (old format returns 404).
  • Multi-gene guidelines: TCA guideline (100414) covers both CYP2D6 and CYP2C19; recommendations have phenotype combinations.
  • Drug name case: 
    CPIC_get_drug_info
    requires lowercase. 
    CPIC_get_recommendations
    with 
    drug=
    uses ilike matching (case-insensitive).
  • CPIC_get_recommendations returns wrapped data: Response is 
    {status, data: {guideline_id, recommendations: [...], count}}
    -- recommendations are nested under 
    data.recommendations
    .
  • 华法林（指南100425）：基于算法的给药；
    CPIC_get_recommendations
    返回0行数据。引导用户访问CPIC官网或PharmGKB。
  • PharmGKB指南链接：使用
    clinpgxid
    （例如"PA166251445"），而非
    pharmgkbid
    （旧格式会返回404错误）。
  • 多基因指南：TCA指南（100414）涵盖CYP2D6和CYP2C19；建议包含表型组合。
  • 药物名称大小写：
    CPIC_get_drug_info
    要求小写。
    CPIC_get_recommendations
    的
    drug=
    参数使用模糊匹配（不区分大小写）。
  • CPIC_get_recommendations返回嵌套数据：响应格式为
    {status, data: {guideline_id, recommendations: [...], count}}
    ——建议内容嵌套在
    data.recommendations
    下。

Phase 3: Allele & Variant Annotation

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

CPIC_get_alleles: 
genesymbol
(string REQUIRED), 
limit
(int, default 50). Returns 
{status, data: [{name, clinicalfunctionalstatus, activityvalue, functionalstatus}]}
.
  • Use 
    clinicalfunctionalstatus
    (not 
    functionalstatus
    which may be null). Values: "Normal function", "Decreased function", "No function", "Increased function", "Uncertain function", "Unknown function".
  • activityvalue
    : numeric string (e.g., "1.0", "0.5", "0.0") or "n/a".
PharmGKB_search_variants: 
query
(string REQUIRED, rsID). Returns variant classification and clinical significance.
PharmGKB_get_clinical_annotations: 
annotation_id
(string REQUIRED, e.g., "1447954390"). Returns 
{status, data: {accessionId, allelePhenotypes: [{allele, phenotype, limitedEvidence}], levelOfEvidence: {term}}}
.
  • REQUIRES annotation_id -- cannot query by gene/drug directly. Discover IDs via 
    PharmGKB_search_variants(query=rsID)
    or from the PharmGKB website.
  • levelOfEvidence.term
    : "1A", "1B", "2A", "2B", "3", "4" (PharmGKB evidence levels).
PharmGKB_get_gene_details: 
gene_id
(string REQUIRED, PharmGKB accession e.g., "PA128"). Returns detailed gene info including allele definition files, VIP citations.
PharmGKB_get_drug_details: 
drug_id
(string REQUIRED, PharmGKB chemical ID e.g., "PA449088"). Returns drug metadata including SMILES, InChI, type (Drug/Prodrug).
OpenTargets_drug_pharmacogenomics_data: 
chemblId
(string REQUIRED, e.g., "CHEMBL1201560"), 
size
(int). Returns PGx variant data from OpenTargets including variant consequences and drug associations.
  • Queries by drug (ChEMBL ID), not by gene. Use when you have a ChEMBL ID and want PGx variant annotations from OpenTargets.
CPIC_get_alleles：
genesymbol
（字符串 必填）、
limit
（整数，默认50）。返回
{status, data: [{name, clinicalfunctionalstatus, activityvalue, functionalstatus}]}
。
  • 使用
    clinicalfunctionalstatus
    （而非可能为空的
    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 accession 例如"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变异注释时使用。

Metabolizer Status Reasoning

代谢者状态推理

A poor metabolizer has reduced or absent enzyme activity. What that means clinically depends entirely on whether the drug is active or a prodrug:
  • Active drug + poor metabolizer: drug accumulates → toxicity risk (e.g., codeine is a prodrug — this case doesn't apply; but nortriptyline is active — PM → high plasma levels → side effects).
  • Prodrug + poor metabolizer: less conversion to active form → reduced efficacy (e.g., codeine → morphine; clopidogrel → active thienopyridine).
  • Prodrug + ultrarapid metabolizer: excess activation → toxicity (classic case: codeine in CYP2D6 UM → morphine accumulation → respiratory depression).
This active-vs-prodrug distinction determines the direction of clinical concern. Get it right before interpreting any metabolizer phenotype.
Star allele reasoning: Don't memorize allele tables. The logic is always: allele function status (normal / decreased / no function) → diplotype → predicted enzyme activity → phenotype (UM/NM/IM/PM) → clinical recommendation. Use 
CPIC_get_alleles(genesymbol=...)
to look up function status for any specific allele.
弱代谢者的酶活性降低或缺失。其临床意义完全取决于药物是活性药物还是前体药物：
  • 活性药物 + 弱代谢者：药物蓄积→毒性风险（例如可待因是前体药物——此情况不适用；但去甲替林是活性药物——弱代谢者→血浆浓度高→副作用）。
  • 前体药物 + 弱代谢者：转化为活性形式的量减少→疗效降低（例如可待因→吗啡；氯吡格雷→活性噻吩吡啶）。
  • 前体药物 + 超快代谢者：过度活化→毒性（典型案例：CYP2D6超快代谢者服用可待因→吗啡蓄积→呼吸抑制）。
这种活性药物与前体药物的区分决定了临床关注的方向。在解读任何代谢者表型之前，务必明确这一点。
星型等位基因推理：无需记忆等位基因表。逻辑始终是：等位基因功能状态（正常/降低/无功能）→双倍型→预测酶活性→表型（UM/NM/IM/PM）→临床建议。使用
CPIC_get_alleles(genesymbol=...)
查找任何特定等位基因的功能状态。

Phase 4: FDA Biomarker Labeling

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

fda_pharmacogenomic_biomarkers: 
drug_name
(string, optional), 
biomarker
(string, optional, e.g., "CYP2D6"), 
limit
(integer, default 10). Returns 
{status, count, shown, results: [{Drug, TherapeuticArea, Biomarker, LabelingSection}]}
.
  • ALWAYS pass 
    limit=1000
    for complete results (default is 10).
  • LabelingSection
    values: "Dosage and Administration", "Clinical Pharmacology", "Precautions", "Use in Specific Populations", "Boxed Warning", "Contraindications".
  • Can query by drug, biomarker, or both.
  • Not all drugs have entries (e.g., simvastatin absent for SLCO1B1; use rosuvastatin for SLCO1B1 PGx testing).
FDA_get_pharmacogenomics_info_by_drug_name: 
drug_name
(string REQUIRED). Returns FDA label PGx sections with brand/generic names. Good for finding PGx labeling text in actual FDA labels.
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 PGx检测）。
FDA_get_pharmacogenomics_info_by_drug_name：
drug_name
（字符串 必填）。返回FDA标签中的PGx章节，包含品牌名/通用名。适合查找实际FDA标签中的PGx标注文本。

FDA PGx Label Reasoning

FDA PGx标签推理

The 
LabelingSection
field tells you how actionable the PGx information is. "Boxed Warning" or "Contraindications" means testing may be required or the drug contraindicated in certain genotypes — highest urgency. "Dosage and Administration" means genotype directly drives dose selection. "Clinical Pharmacology" is usually informational (PK/PD data), not a prescribing directive. When in doubt, retrieve the full label text with 
FDA_get_pharmacogenomics_info_by_drug_name
.
LabelingSection
字段表明PGx信息的可执行程度。"黑框警告"或"禁忌症"意味着某些基因型可能需要检测或禁用该药物——优先级最高。"给药剂量与方法"意味着基因型直接决定剂量选择。"临床药理学"通常为信息性内容（PK/PD数据），而非处方指导。如有疑问，使用
FDA_get_pharmacogenomics_info_by_drug_name
获取完整标签文本。

Phase 5: Cross-Database Enrichment

阶段5：跨数据库富集

DGIdb_get_drug_gene_interactions: 
genes
(array of strings REQUIRED, e.g., 
["CYP2D6"]
), 
interaction_types
(array, optional), 
interaction_sources
(array, optional). Returns drug-gene interactions with sources.
  • Broader coverage than CPIC; includes non-PGx interactions.
  • Client-side filtering applied for 
    interaction_types
    and 
    sources
    parameters.
DGIdb_get_gene_druggability: 
genes
(array of strings REQUIRED). Returns 
{status, data: {data: {genes: {nodes: [{name, geneCategories}]}}}}
.
  • Returns gene categories (e.g., "CLINICALLY ACTIONABLE", "DRUGGABLE GENOME").
PharmGKB_get_dosing_guidelines: (also in Phase 2) Provides DPWG (Dutch Pharmacogenetics Working Group) guidelines alongside CPIC.
OpenTargets_drug_pharmacogenomics_data: 
chemblId
(string REQUIRED), 
size
(int). Returns PGx variant annotations from the OpenTargets platform.
  • Complements CPIC data with additional variant-level PGx evidence.
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）提供CPIC之外的DPWG（荷兰药物遗传学工作组）指南。
OpenTargets_drug_pharmacogenomics_data：
chemblId
（字符串 必填）、
size
（整数）。返回OpenTargets平台的PGx变异注释。
  • 补充CPIC数据，提供额外的变异级PGx证据。

Adverse Event Signal Detection for PGx-Relevant Drugs

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

FAERS_filter_serious_events: 
drug_name
(string REQUIRED), 
seriousness_type
("all"/"death"/"hospitalization"/"disability"/"life_threatening"), 
adverse_event
(string, optional). Use to detect serious adverse event signals for PGx-relevant drugs — e.g., respiratory depression reports for codeine in the context of CYP2D6 UM status. The 
adverse_event
parameter filters to reports containing that specific reaction term.
Optional: 
DisGeNET_get_vda
for variant-disease associations (requires DISGENET_API_KEY).
FAERS_filter_serious_events：
drug_name
（字符串 必填）、
seriousness_type
（"all"/"death"/"hospitalization"/"disability"/"life_threatening"）、
adverse_event
（字符串，可选）。用于检测PGx相关药物的严重不良事件信号——例如CYP2D6超快代谢者服用可待因后的呼吸抑制报告。
adverse_event
参数用于过滤包含特定反应术语的报告。
可选：使用
DisGeNET_get_vda
获取变异-疾病关联（需要DISGENET_API_KEY）。

When PGx Testing Changes Clinical Decisions

PGx检测改变临床决策的场景

PGx testing changes clinical decisions ONLY for drugs with narrow therapeutic indices metabolized by polymorphic enzymes where genotype reliably predicts outcome. If the drug has a wide therapeutic index or is cleared by multiple redundant pathways, PGx status rarely alters the prescribing decision even when a variant is present.
Evidence grading — reasoning approach: CPIC levels A/B represent actionable evidence; C/D are informational. PharmGKB level 1A means the annotation is already embedded in a CPIC or DPWG guideline — the highest confidence tier. Levels 3/4 are hypothesis-generating, not prescribing-grade. CPIC recommendation strength (Strong/Moderate/Optional) within a guideline reflects how certain the genotype-to-outcome link is for that specific phenotype.
The key question is not "what level is this?" but "does this level justify changing the prescription?" For Level A CPIC with Strong classification, yes. For PharmGKB level 3, no — report it but don't act on it alone.
仅当药物治疗指数窄、由多态性酶代谢且基因型可可靠预测结局时，PGx检测才会改变临床决策。如果药物治疗指数宽或通过多种冗余途径清除，即使存在变异，PGx状态也很少改变处方决策。
证据分级——推理方法：CPIC A/B级代表可执行证据；C/D级为信息性内容。PharmGKB 1A级意味着注释已纳入CPIC或DPWG指南——置信度最高。3/4级为假设生成级，而非处方级。指南内的CPIC推荐强度（强/中等/可选）反映了该特定表型的基因型-结局关联的确定性。
关键问题不是“这是什么等级？”而是“该等级是否足以改变处方？”对于CPIC A级且强推荐的情况，答案是肯定的。对于PharmGKB 3级，答案是否定的——可报告但不能单独据此采取行动。

Key Parameter Notes

关键参数说明

Critical parameter behaviors to remember — these are the ones that actually cause failures:
  • CPIC_get_recommendations
    : accepts 
    guideline_id
    (integer) OR 
    drug
    /
    drug_name
    (string). Never pass guideline_id as a string.
  • PharmGKB_get_dosing_guidelines
    : requires 
    clinpgxid
    (e.g., "PA166251445"), not the numeric 
    pharmgkbid
    . Get clinpgxid from 
    CPIC_list_guidelines
    .
  • PharmGKB_get_clinical_annotations
    : requires 
    annotation_id
    . Cannot query by gene or drug. Discover IDs via 
    PharmGKB_search_variants(query=rsID)
    .
  • fda_pharmacogenomic_biomarkers
    : default 
    limit=10
    is almost always too small. Pass 
    limit=1000
    .
  • CPIC_get_drug_info
    : drug name must be lowercase.
  • DGIdb_get_drug_gene_interactions
    and 
    DGIdb_get_gene_druggability
    : 
    genes
    is an array, not a string (e.g., 
    ["CYP2D6"]
    ).
  • CPIC_search_gene_drug_pairs
    : returns RxNorm IDs, not drug names. Use 
    CPIC_get_gene_drug_pairs
    when you need drug names.
需要记住的关键参数行为——这些是实际导致失败的原因：
  • 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 Guideline Application Reasoning

CPIC指南应用推理

CPIC guidelines give genotype → phenotype → recommendation mappings. The skill is knowing when to apply them, not memorizing the mappings themselves. Use tools to retrieve the specific recommendation for the specific phenotype. The reasoning chain is:
  1. Does a CPIC guideline exist for this gene-drug pair? (Level A or B = actionable)
  2. What is the patient's phenotype? (from diplotype + allele function statuses)
  3. What does the guideline recommend for that phenotype? (retrieve with 
    CPIC_get_recommendations
    )
  4. Is there FDA label reinforcement? (check 
    fda_pharmacogenomic_biomarkers
    )
If step 1 is no, fall back to PharmGKB variant annotations for evidence-graded but non-guideline information.
CPIC指南提供基因型→表型→建议的映射。核心技能是知道何时应用指南，而非记忆映射关系。使用工具检索特定表型的具体建议。推理链如下：
  1. 该基因-药物对是否存在CPIC指南？（A/B级=可执行）
  2. 患者的表型是什么？（来自双倍型+等位基因功能状态）
  3. 指南针对该表型给出了什么建议？（使用
    CPIC_get_recommendations
    检索）
  4. 是否有FDA标签支持？（检查
    fda_pharmacogenomic_biomarkers
    ）
如果步骤1为否，则退而求其次，使用PharmGKB变异注释获取循证分级但非指南级别的信息。

Fallback Strategies

备选策略

  • No CPIC guideline -> Use 
    PharmGKB_search_variants(query=rsID)
    for variant-level annotations; check EpiGraphDB for gene-drug evidence
  • CPIC_get_recommendations returns 0 rows -> Check if algorithm-based (warfarin); use PharmGKB_get_dosing_guidelines
  • CPIC_get_recommendations drug auto-resolve fails -> Fall back to CPIC_get_drug_info(name=drug) + manual guideline_id extraction
  • No FDA biomarker entry -> Check DGIdb for known interactions; check EpiGraphDB 
    pgx_on_fda_label
    field
  • Unknown variant -> PharmGKB_search_variants by rsID; note as uncharacterized if absent
  • Need drug name from RxNorm ID -> Use CPIC_get_gene_drug_pairs (returns 
    drug: {name}
    ) instead of CPIC_search_gene_drug_pairs (returns only RxNorm IDs)
  • PharmGKB annotation_id unknown -> Get annotation IDs from PharmGKB website or via 
    PharmGKB_search_variants(query=rsID)
  • Need additional PGx variant data -> Use 
    OpenTargets_drug_pharmacogenomics_data(chemblId=...)
    with ChEMBL ID
  • 无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注释ID未知 -> 从PharmGKB官网或通过
    PharmGKB_search_variants(query=rsID)
    获取注释ID
  • 需要额外PGx变异数据 -> 使用
    OpenTargets_drug_pharmacogenomics_data(chemblId=...)
    并传入ChEMBL ID

Example Workflows

示例工作流

Drug-first (codeine + CYP2D6 PM): 
CPIC_get_recommendations(drug="codeine", limit=50)
→ filter 
phenotypes.CYP2D6="Poor Metabolizer"
→ Strong recommendation: avoid codeine. Then 
CPIC_get_alleles(genesymbol="CYP2D6", limit=100)
to confirm star allele function (e.g., *4/*4 → no function, AS 0.0). Then 
fda_pharmacogenomic_biomarkers(drug_name="codeine", limit=1000)
to confirm FDA label status. Gene-first alternative: 
CPIC_get_gene_drug_pairs(genesymbol="CYP2D6")
to list all associated drugs.
Gene-first (all CYP2C19 drugs): 
CPIC_search_gene_drug_pairs(gene_symbol="CYP2C19", cpiclevel="A")
for Level A pairs. 
EpiGraphDB_get_gene_drug_associations(gene_name="CYP2C19")
for CPIC + PharmGKB + FDA label overview in one call. 
fda_pharmacogenomic_biomarkers(biomarker="CYP2C19", limit=1000)
for complete FDA coverage.
Variant-first (rs1799853): 
PharmGKB_search_variants(query="rs1799853")
→ CYP2C9 variant, drug-response significance. 
CPIC_get_alleles(genesymbol="CYP2C9", limit=100)
→ maps to *2, "Decreased function". 
CPIC_get_gene_drug_pairs(genesymbol="CYP2C9")
→ warfarin, phenytoin, NSAIDs. For each drug with a guideline: 
CPIC_get_recommendations(drug="phenytoin", limit=50)
.
以药物为起点（可待因 + CYP2D6弱代谢者）：
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，"Decreased function"。
CPIC_get_gene_drug_pairs(genesymbol="CYP2C9")
→ 华法林、苯妥英、NSAIDs。对每个有指南的药物：
CPIC_get_recommendations(drug="phenytoin", limit=50)
。

Drug Class Context (RxClass)

药物类别背景（RxClass）

When PGx analysis involves understanding which drug class a substrate belongs to, or finding all drugs in a class that share the same metabolizing enzyme: use 
RxClass_get_drug_classes(drug_name=...)
to get all class memberships for a drug, 
RxClass_find_classes(query=..., class_type=...)
to find class IDs from a keyword, and 
RxClass_get_class_members(class_id=..., rela_source=..., ttys="IN")
to list all drugs in a class. Example: find all SSRIs to advise which require CYP2D6 testing as a class note.
当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 Substance Identification (FDAGSRS)

FDA物质识别（FDAGSRS）

For canonical FDA substance identification (UNII codes, cross-references to ATC/DrugBank/CAS): use 
FDAGSRS_search_substances(query=...)
to find the UNII code, 
FDAGSRS_get_substance(unii=...)
for the full record with all names and cross-references, and 
FDAGSRS_get_structure(unii=...)
for SMILES/InChIKey. Useful to confirm that two drug name variants (e.g., "warfarin sodium" and "warfarin") share the same UNII before cross-referencing in CPIC or PharmGKB.
如需标准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中进行交叉引用。

Limitations

局限性

  • CPIC covers ~29 guidelines (~130 genes); many drug-gene pairs lack formal guidelines.
  • PharmGKB clinical annotation IDs must be discovered (not derivable from gene/drug names alone -- use PharmGKB website or PharmGKB_search_variants for rsID-based lookup).
  • Warfarin dosing requires algorithmic calculation (CPIC website), not simple table lookup.
  • FDA biomarker table may lag behind current labeling changes.
  • DisGeNET requires API key (DISGENET_API_KEY).
  • CPIC_search_gene_drug_pairs returns RxNorm drug IDs, not drug names; use CPIC_get_gene_drug_pairs for names.
  • Activity score interpretation varies by gene (CYP2D6 uses numeric scores; others may use phenotype-based lookup).
  • CPIC_get_recommendations drug auto-resolution uses ilike matching -- ambiguous drug names may match multiple entries.
  • CPIC涵盖约29项指南（约130个基因）；许多药物-基因对缺乏正式指南。
  • PharmGKB临床注释ID必须主动查找（无法从基因/药物名称直接推导——使用PharmGKB官网或基于rsID的PharmGKB_search_variants查找）。
  • 华法林给药需要算法计算（CPIC官网），而非简单的表格查询。
  • FDA生物标志物表可能滞后于当前标签变更。
  • DisGeNET需要API密钥（DISGENET_API_KEY）。
  • CPIC_search_gene_drug_pairs返回RxNorm药物ID，而非药物名称；需要名称时使用CPIC_get_gene_drug_pairs。
  • 活性评分解读因基因而异（CYP2D6使用数字评分；其他基因可能使用基于表型的查找）。
  • CPIC_get_recommendations的药物自动解析使用模糊匹配——模糊的药物名称可能匹配多个条目。