bio-clinical-databases-pharmacogenomics

What this skill does

## 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. The 2024 DPYD update (Lam et al. *Clin Pharmacol Ther*) replaced single-variant logic with the activity-score system; 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 2019** *Clin Pharmacol Ther* 105:951 (DOI 10.1002/cpt.762; first online 2018, print 2019) 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%.

**Donnelly 2024** 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 *Genome Med*) | **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** |