bio-clinical-databases-pharmacogenomics

## Version Compatibility Reference examples tested with: PharmCAT 2.13+, Cyrius 1.1+ (Chen 2021), Aldy 4.0+, Stargazer 2.0+, StarPhase 1.0+ (PacBio HiFi), HIBAG 1.40+, requests 2.31+, pandas 2.2+. CPIC guideline versions are gene-specific; PharmVar releases are quarterly. DPYD dosing uses the CPIC gene activity-score system (Amstutz 2018 *Clin Pharmacol Ther* 103:210, the 2017-update guideline); the 2025 TPMT/NUDT15 update (Maillard 2026) refines compound-IM dosing. Before using code patterns, verify installed versions match. If versions differ: - Python: `pip show <package>` then `help(module.function)` to check signatures - CLI: `<tool> --version` then `<tool> --help` to confirm flags If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying. PharmVar is the authoritative star-allele source (`https://www.pharmvar.org`); the older Human CYP Allele Nomenclature Database was deprecated in 2017. # Pharmacogenomics; Star Alleles, Activity Scores, and CPIC/DPWG Guidance **'What is my patient's CYP2D6 metabolizer status and should I adjust their tamoxifen dose?'** -> Call star alleles (haplotype-level), translate diplotype -> activity score -> phenotype, apply CPIC + DPWG dosing. - CLI (recommended): `pharmcat -vcf input.vcf.gz -o pharmcat_out`; CPIC-recommended, single-tool reporting - CLI (CYP2D6 SV-aware): `cyrius -m sample.bam -o cyrius_out`; mandatory addition for CYP2D6 - CLI (multi-gene CN-aware): `aldy genotype -p illumina sample.bam`; alternative - CLI (long-read 8-field): PacBio HiFi `starphase`; transplant-grade including HLA - R (SNP-array): HIBAG for HLA-B*57:01/B*15:02/B*58:01/A*31:01 imputation - API: `requests.get('https://api.pharmgkb.org/v1/data/clinicalAnnotation', ...)` ## Governance: CPIC vs DPWG vs PharmGKB vs FDA These four authorities are routinely conflated. They differ in scope, scale, and recommendations: | Authority | Scope | Output | Anchors | |-----------|-------|--------|---------| | **CPIC** (US Clinical Pharmacogenetics Implementation Consortium) | Once a result is available, what to prescribe | Level A/B/C/D gene-drug pair + strength of recommendation per phenotype + evidence quality | ~26 guidelines, ~25 genes, 100+ drugs as of 2026 | | **DPWG** (Dutch Pharmacogenetics Working Group) | Whether to test AND what to prescribe | 5-pt (0-4) evidence + 7-pt (AA-F) clinical-relevance scale | G-Standaard (Dutch EHR-integrated); RCT-validated via PREPARE | | **PharmGKB clinical annotation levels** | Evidence cataloguing | 1A/1B/2A/2B/3/4 | 1A = guideline OR medical-society OR PGRN/eMERGE implementation; NOT pure evidence | | **FDA Table of Pharmacogenomic Biomarkers** | Drug label info | ~300 drugs (informational) | NOT an actionability list; many entries are dosing-suggestion-only | | **FDA Table of Pharmacogenetic Associations** | Actionable subset | Closer to CPIC | Compare head-to-head with CPIC | **Bank et al 2018** *Clin Pharmacol Ther* 103:599 (DOI 10.1002/cpt.762) is the canonical CPIC-vs-DPWG comparison. Notable disagreements: - CYP2D6 IM + multiple antidepressants: DPWG actionable; CPIC says insufficient evidence. - HLA-B*15:11 carbamazepine: DPWG actionable; CPIC silent. - CYP2C19 IM + voriconazole: dosing magnitudes differ 25-50%. **Common PGx-evidence critiques:** (1) EUR over-representation in discovery cohorts; (2) most PGx RCTs are open-label / prescriber-unblinded; (3) publication bias in antiseizure PGx may overstate effects ~2x; (4) subjective composite endpoints. ## PharmGKB Clinical Annotation Levels: What 1A Actually Means | Level | Requirement | |-------|-------------| | **1A** | Variant-drug pair appears in CPIC guideline OR medical-society guideline OR is implemented at a PGRN/eMERGE site | | **1B** | Replication in multiple cohorts; preponderance of evidence; no formal guideline yet | | **2A** | Replicated association in a VIP (Very Important Pharmacogene) | | **2B** | Replicated association in non-VIP gene | | **3** | Single significant association OR mixed-evidence variant-drug pair | | **4** | In vitro / case report / molecular evidence only | 1A does NOT require RCT evidence; mechanism + guideline status suffices. ## Star Allele Nomenclature (PharmVar) PharmVar (`https://www.pharmvar.org`) is authoritative for: CYP1A1, CYP1A2, CYP1B1, CYP2A6, CYP2A13, CYP2B6, CYP2C8, CYP2C9, CYP2C19, CYP2D6, CYP2E1, CYP2F1, CYP2J2, CYP2R1, CYP2S1, CYP2W1, CYP3A4, CYP3A5, CYP3A7, CYP3A43, CYP4A11, CYP4F2, CYP19A1, CYP26A1, DPYD, NUDT15, SLCO1B1, TPMT. **A star allele is a haplotype, not a single variant.** *Suballeles* (*1.001, *1.002, etc.) encode the exact SNV+indel pattern within a defined functional haplotype. **The *1 reference is the PharmVar consensus reference, NOT biological wild type.** Defined as the absence of all known functional variants at the locus. ### CYP2D6 Activity Scores (Caudle 2020 *Clin Transl Sci*; DOI 10.1111/cts.12692) | Phenotype | Activity score (AS) range | |-----------|--------------------------| | **PM (Poor Metabolizer)** | 0 | | **IM (Intermediate Metabolizer)** | 0 < AS < 1.25 | | **NM (Normal Metabolizer)** | 1.25 <= AS <= 2.25 | | **UM (Ultra-rapid)** | AS > 2.25 | Key per-allele activity values (selected): | Allele | Activity | Notes | |--------|----------|-------| | \*1, \*2, \*35 | 1.0 | Normal | | \*3, \*4, \*5 (gene deletion), \*6, \*7, \*8, \*11, \*12, \*15, \*19, \*20, \*36, \*40, \*42 | 0 | No function | | \*9, \*41, \*17, \*29 | 0.5 | Decreased function (substrate-specific caveats for \*17) | | **\*10** | **0.25** | **Caudle 2020 RESET from 0.5 to 0.25**; reclassified large fractions of East-Asian populations to IM | | \*68 | 0 | Hybrid; non-functional | **\*4xN is clinically silent:** a no-function allele multiplied by N is still no-function. Reporting *4xN as UM is the most-common reportable error in clinical PGx. ### CYP2D6 Structural Complexity CYP2D6 on 22q13.2 sits adjacent to the highly-similar CYP2D7 pseudogene. Four classes of structural variant that no SNV-only caller can resolve: 1. **Gene deletion (\*5):** ~13 kb deletion; activity 0; diagnostic *REP6/REP7* breakpoint. 2. **Gene duplication/multiplication (\*1xN, \*2xN, \*4xN, \*10xN, \*17xN, \*35xN, \*36xN):** Tandem copies; clinical impact depends on which allele is amplified; **\*4xN is clinically silent**. 3. **CYP2D7 -> CYP2D6 hybrids (\*13):** Pseudogene fused 5'; non-functional. 4. **CYP2D6 -> CYP2D7 hybrids (\*36, \*61, \*63, \*68, \*83):** 5' CYP2D6 with 3' pseudogene exon 9 conversion; typically embedded in duplications upstream of *10 (East Asian) or upstream of *4 (European). **GATK / DeepVariant alone cannot call any of these.** They operate on multi-mapper-filtered BAMs; 97%+ identity between CYP2D6 and CYP2D7 produces silent miscalls of every \*5, \*13, \*36, \*68, \*4xN sample. ## Algorithmic Taxonomy: Star Allele Callers | Tool | CYP2D6 SV | CYP2D6 CN | Other PGx genes | Phased | Validation | Fails when | |------|-----------|-----------|-----------------|--------|------------|-----------| | **PharmCAT** (Sangkuhl 2020 *Clin Pharmacol Ther*) | No (consumes outside SV calls) | No | 21 CPIC genes; full clinical reporting | Phased or unphased VCF | High; CPIC reference | CYP2D6 SV-rich samples need Cyrius/StellarPGx upstream | | **Cyrius** (Chen 2021 *Pharmacogenomics J*) | **Yes (99.3% concordance)** | **Yes** | CYP2D6 only | Phased haplotypes | GeT-RM 99.3% | Other genes (single-purpose tool) | | **BCyrius** (PubMed 39901590, 2025) | Yes (extended) | Yes | CYP2D6 only | Phased | Extended SV diversity | Other genes | | **Aldy v4** (Numanagic 2018 *Nat Commun*) | Yes | Yes | CYP2D6, CYP2A6, CYP2B6, etc. | Phased | GeT-RM 82-87% (CYP2D6) | Less accurate than Cyrius for CYP2D6 | | **Stargazer** (Lee 2019 *Genet Med*) | Limited | Yes | ~50 PGx genes | Statistical phasing | ~84% (CYP2D6) | Fails on rare alleles; statistical phasing is unstable | | **StellarPGx** | Yes (~99%) | Yes | CYP2D6 + others | Phased | GeT-RM ~99% | Less widely deployed than Cyrius | | **Astrolabe** (proprietary, formerly Constellation) | Yes | Yes | Multi-gene | Proprietary | Industry-validated | License required | | **StarPhase** (PacBio HiFi 2024+) | Yes | Yes | All CPIC Level A genes + HLA | Native phasing | Long-read gold standard | Requires PacBio HiFi | **Canonical clinical workflow 2024-2026:** PharmCAT for the panel + Cyrius (or StellarPGx) for CYP2D6 SVs + dedicated HLA typer (T1K, OptiType, HLA-LA) for HLA. Twesigomwe 2020 *npj Genom Med*: inter-tool discordance 10-18% on CYP2D6; nearly all in samples carrying SVs. ## HLA-Drug Associations: Mechanistically Distinct from CYP HLA associations are **idiosyncratic immune reactions**, not dose-response phenomena. Effect sizes (OR 50-1000+) far exceed any CYP polymorphism. Testing rationale is **screen-and-avoid**, not dose-adjust. | Allele | Drug | Reaction | Population | Landmark | |--------|------|----------|------------|----------| | **HLA-B\*57:01** | Abacavir | HSS | All ancestries (5-8% NFE) | Mallal 2008 *NEJM* (PREDICT-1) | | **HLA-B\*15:02** | Carbamazepine, oxcarbazepine, phenytoin, lamotrigine (weaker) | SJS/TEN | Han Chinese, Thai, Malay, Indian (>=5%) | Chung 2004 *Nature*; FDA black-box 2007 | | **HLA-A\*31:01** | Carbamazepine | DRESS, MPE, SJS/TEN | Europeans (2-5%), Japanese | McCormack 2011 *NEJM* | | **HLA-B\*58:01** | Allopurinol | SJS/TEN, DRESS | Han Chinese (10-15%), Thai, Korean | Hung 2005 *PNAS* (OR ~580) | | **HLA-B\*13:01** | Dapsone | DDS | Han Chinese, SE Asian | Zhang 2013 *NEJM* | | **HLA-B\*35:02** (NOT \*35:01) | Minocycline | DILI | All | Urban 2017 *J Hepatol* | | **HLA-B\*35:01** | TMP-SMX | DILI, DRESS-like | African American | Li 2021 *Hepatology* | | **HLA-B\*14:01** | TMP-SMX | DILI | European American (OR 9.20) | Li 2021 | | **HLA-A\*33:01/03** | Terbinafine | DILI | Multi-ancestry | Nicoletti 2017 | | **HLA-DRB1\*15:01-DQB1\*06:02 haplotype** | Amoxicillin-clavulanate | DILI | Europeans | Stephens 2013 | | **HLA-B\*15:13** | Phenytoin | SJS | Malaysian | Chang 2017 | **Critical:** HLA screening requires 4-field resolution. \*57:01 (abacavir risk) vs \*57:03 (no risk); \*35:02 (minocycline DILI) vs \*35:01 (TMP-SMX DILI). See `clinical-databases/hla-typing` for typing. ## Non-CYP Pharmacogenes: Variant-Level Detail ### DPYD (5-FU / Capecitabine / Tegafur); Activity Score Framework The CPIC DPYD guideline (Amstutz 2018 *Clin Pharmacol Ther* 103:210) uses a **gene activity score** system. Activity values: normal-function = 1.0, decreased = 0.5, no function = 0. | Variant | rsID | Allele | Activity | |---------|------|--------|----------| | c.1905+1G>A | rs3918290 | DPYD*2A | 0 (splice disruption) | | c.1679T>G | rs55886062 | DPYD*13 (p.I560S) | 0 | | c.2846A>T | rs67376798 | (p.D949V) | 0.5 | | c.1129-5923C>G / c.1236G>A (HapB3) | rs56038477 / rs75017182 | HapB3 | 0.5 | Gene AS = sum of two lowest activities. Recommended dose: AS 2 = full dose; AS 1.5 = 50% start + TDM; AS 1.0 = 50% start + TDM; AS 0 = avoid. c.85T>C (DPYD\*9A) is NOT in the CPIC actionable set despite frequent commercial reporting; evidence does not support clinical decrement. EU universal pre-treatment testing standard since Henricks 2018 *Lancet Oncol* (genotype-guided dosing lowered severe fluoropyrimidine toxicity in DPYD variant carriers, e.g. DPYD*2A grade >=3 toxicity RR 2.87 -> 1.31) and EMA 2020 endorsement. US lags; ASCO/NCCN moved 2022-2024. ### TPMT + NUDT15 (Thiopurines); 2025 Update Maillard 2026 *Clin Pharmacol Ther* update emphasizes greater dose reduction for **compound TPMT/NUDT15 IM**. | Gene | Variant | Activity | Population | |------|---------|----------|-----------|