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-B57:01/B15:02/B58:01/A31: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:

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

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)

Key per-allele activity values (selected):

**\*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

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.

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.

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.

NUDT15 3 is the dominant thiopurine determinant in East Asians; TPMT-alone testing misses these patients (Yang 2015 J Clin Oncol*).

UGT1A1 (Irinotecan, Atazanavir)

• \28 (TA7 promoter repeat vs \1 = TA6, \*37 = TA8); EUR-common
• \*6 (c.211G>A, p.G71R); East Asian dominant
• Severe neutropenia in \28/\28 at irinotecan >=180 mg/m^2

CYP2C19 + Clopidogrel; The Most-Litigated Pair

• Pare 2010 NEJM: no benefit of clopidogrel in \*2 carriers in CURE/ACTIVE-A.
• TAILOR-PCI (Pereira 2020 JAMA): 5,302 patients post-PCI; primary endpoint MACE @12mo HR 0.66, p=0.06 (negative by pre-specified alpha) but positive in sensitivity analyses.
• Pereira NL et al 2021 meta-analysis (7 RCTs, 15,949 patients): ~30% MACE reduction in CYP2C19 LOF carriers (JACC Cardiovasc Interv 14:739).
• Consensus 2024 (ACC/AHA/ESC): genotype-guided therapy reasonable; strongest in post-PCI ACS.

Warfarin (CYP2C9 + VKORC1 + CYP4F2)

• EU-PACT 2013 NEJM: PGx dosing positive (European).
• COAG 2013 NEJM: PGx dosing negative; worse in African Americans because algorithm omitted CYP2C9 \5, \6, \8, \11 alleles common in African ancestry. Paradigmatic ancestry-algorithm failure (Daneshjou 2014 Blood).
• IWPC algorithm explains 47-55% of dose variance.

SLCO1B1 + Simvastatin

• rs4149056 (c.521T>C, p.V174A); OR 4.5 per C allele for myopathy on 80 mg simvastatin (SEARCH 2008 NEJM).
• 2022 CPIC update broadened to all statins with SLCO1B1 substrate behavior.

Other Actionable

• **CYP2B6 *6** (c.516G>T + c.785A>G): efavirenz dose 600 -> 400 mg in 6/6 (ENCORE1).
• **CYP3A5 *3** (rs776746): non-expressers (\3, \6, \7) are the common* state in non-AFR; expressers need 1.5-2x higher tacrolimus dose.
• G6PD (CPIC 2022 Gammal 2023): X-linked; female heterozygotes have mosaic activity that single-timepoint assay misclassifies.

Decision Tree by Scenario

PharmCAT Workflow (Recommended Multi-Gene Pipeline)

Goal: Generate CPIC-compliant pharmacogenomic report from a phased or unphased VCF covering 21 PGx genes.

Approach: Run PharmCAT on the VCF; supplement CYP2D6 with Cyrius output if SVs suspected; cross-reference HLA from separate typing.

# PharmCAT (CPIC-recommended; covers 21 genes including CYP2C19, CYP2C9, CYP2D6,
# DPYD, TPMT, NUDT15, UGT1A1, SLCO1B1, CYP3A5, CYP4F2, VKORC1, IFNL3/IFNL4, etc.)

# 1. Preprocess VCF (ensures correct ref allele alignment + chr formatting)
pharmcat_vcf_preprocessor.py \
    -vcf input.vcf.gz \
    -refFna GRCh38.fa \
    -o pharmcat_input/

# 2. Run PharmCAT
java -jar pharmcat.jar \
    -vcf pharmcat_input/input.preprocessed.vcf.bgz \
    -o pharmcat_output/

# Output: <sample>.report.html with phenotype, activity score, dosing recommendations

For CYP2D6 SV-rich samples, run Cyrius separately and pass outside calls to PharmCAT:

# Cyrius for CYP2D6 (99.3% concordance vs Aldy 82-87%, Stargazer 84%)
cyrius -m sample.bam -o cyrius_out --threads 8
# Output: cyrius_out/sample.tsv with diplotype + activity score

# Pass outside calls to PharmCAT
java -jar pharmcat.jar \
    -vcf pharmcat_input/input.preprocessed.vcf.bgz \
    -po cyrius_out/cyrius_for_pharmcat.tsv \
    -o pharmcat_output_with_cyrius/

CYP2D6 Activity Score Calculation

Goal: Convert CYP2D6 diplotype to activity score and phenotype with Caudle 2020 conventions.

Approach: Look up per-allele activity values; handle copy-number duplications; apply Caudle 2020 phenotype bins.

# Caudle 2020 activity values; *10 reset from 0.5 to 0.25 in 2020
CYP2D6_ACTIVITY = {
    '*1': 1.0, '*2': 1.0, '*35': 1.0,
    '*3': 0.0, '*4': 0.0, '*5': 0.0, '*6': 0.0, '*7': 0.0, '*8': 0.0,
    '*11': 0.0, '*12': 0.0, '*15': 0.0, '*19': 0.0, '*20': 0.0,
    '*36': 0.0, '*40': 0.0, '*42': 0.0, '*68': 0.0,
    '*9': 0.5, '*41': 0.5, '*17': 0.5, '*29': 0.5,
    '*10': 0.25,
    '*13': 0.0,
}


def cyp2d6_activity(diplotype):
    '''Convert CYP2D6 diplotype to activity score.

    Accepts e.g. '*1/*4' or '*2xN/*10' or '*4xN/*10'. Copy-number-aware:
    - *4xN is clinically silent (no-function * N = 0)
    - *1xN, *2xN multiply functional activity
    '''
    left, right = diplotype.split('/')
    return _allele_activity(left) + _allele_activity(right)


def _allele_activity(allele_str):
    '''Handle copy-number suffix xN. *4xN remains 0 (the most common mis-classification).'''
    if 'x' in allele_str:
        base, n = allele_str.split('x')
        copies = int(n) if n != 'N' else 2  # 'N' usually >=2; clinical assumes 2 unless quantified
        return CYP2D6_ACTIVITY.get(base, 1.0) * copies
    return CYP2D6_ACTIVITY.get(allele_str, 1.0)


def cyp2d6_phenotype(activity_score):
    '''Caudle 2020 phenotype bins.'''
    if activity_score == 0:
        return 'Poor Metabolizer'
    if activity_score < 1.25:
        return 'Intermediate Metabolizer'
    if activity_score <= 2.25:
        return 'Normal Metabolizer'
    return 'Ultrarapid Metabolizer'


# Example: *4xN/*10; the classic clinical-silence footgun
diplotype = '*4xN/*10'
score = cyp2d6_activity(diplotype)  # 0 (from *4xN) + 0.25 (from *10) = 0.25
print(f'{diplotype}: AS={score}, phenotype={cyp2d6_phenotype(score)}')  # IM, NOT UM

DPYD Activity Score (CPIC)

DPYD_2024_ACTIVITY = {
    'c.1905+1G>A': 0.0,    # *2A; splice donor
    'c.1679T>G': 0.0,      # *13; p.I560S
    'c.2846A>T': 0.5,      # p.D949V
    'HapB3': 0.5,          # c.1129-5923C>G linked with c.1236G>A
}


def dpyd_activity(variants):
    '''Compute DPYD gene activity score from observed variants.

    Sum the two lowest activities across the two alleles. CPIC dosing:
    - AS 2.0: full dose
    - AS 1.5: 50% start + TDM
    - AS 1.0: 50% start + TDM
    - AS 0.0: avoid
    '''
    activities = sorted([DPYD_2024_ACTIVITY.get(v, 1.0) for v in variants])
    return sum(activities[:2])


def dpyd_dosing(activity_score):
    if activity_score >= 1.99:
        return 'Full dose'
    if activity_score >= 1.0:
        return '50% starting dose + therapeutic drug monitoring'
    return 'Avoid fluoropyrimidines'

PharmGKB API for Drug-Gene Pair Lookup

import requests

PHARMGKB = 'https://api.pharmgkb.org/v1'


def clinical_annotation(gene_symbol):
    '''Query PharmGKB clinical annotations by gene.'''
    r = requests.get(f'{PHARMGKB}/data/clinicalAnnotation',
                     params={'view': 'base', 'location.genes.symbol': gene_symbol},
                     timeout=30)
    return r.json().get('data', [])


def cpic_guideline(gene_symbol):
    '''Query CPIC guidelines via PharmGKB.'''
    r = requests.get(f'{PHARMGKB}/data/guideline',
                     params={'view': 'base', 'relatedGenes.symbol': gene_symbol, 'source': 'CPIC'},
                     timeout=30)
    return r.json().get('data', [])

Per-Operation Failure Modes

**1. *4xN -> "Ultrarapid Metabolizer"**

• Trigger: Pipeline reports CYP2D6 \*4xN as UM.
• Mechanism: \4 has activity 0; \4 x N = still 0. Only functional alleles (\1, \2, \*35) become UM when amplified.
• Symptom: Patient labeled as needing dose reduction when they should be PM/IM.
• Fix: Look up per-allele activity BEFORE multiplying by N; \*4xN = 0; AS depends entirely on the other allele.

2. Calling CYP2D6 from short-read without SV-aware tool

• Trigger: Use GATK + PharmCAT only on CYP2D6.
• Mechanism: 97%+ CYP2D6/CYP2D7 identity; SVs (deletion, duplications, hybrids) silently miscalled.
• Symptom: ~10-18% of samples miscalled (Twesigomwe 2020); concentrated in samples with SVs.
• Fix: Add Cyrius (or StellarPGx) for CYP2D6; pass outside calls to PharmCAT.

**3. Pre-2020 \*10 activity value**

• Trigger: Use activity = 0.5 for CYP2D6 \*10.
• Mechanism: Caudle 2020 reset \*10 from 0.5 to 0.25 based on metabolic-ratio evidence.
• Symptom: East-Asian samples mis-classified as NM (when should be IM).
• Fix: Use Caudle 2020 activity table; \*10 = 0.25.

4. EUR-only DPYD panel

• Trigger: Pre-treat fluoropyrimidine using CPIC-core 4-variant panel only.
• Mechanism: 4-variant panel captures EUR DPD-deficient carriers but misses additional DPYD variants enriched in non-European populations (Offer 2014 identified ~30 such deleterious variants).
• Symptom: African-ancestry patients suffer severe toxicity despite "negative" PGx.
• Fix: Use extended panel for AFR cohorts; supplement with phenotype testing (uracil/dihydrouracil plasma ratio).

5. TPMT testing without NUDT15

• Trigger: Pre-treat thiopurines using TPMT-only PGx in East Asian patient.
• Mechanism: NUDT15 *3 (9.8% EAS, <1% EUR) is the dominant determinant in EAS.
• Symptom: EAS patients TPMT-wildtype suffer severe myelosuppression.
• Fix: Always test NUDT15 alongside TPMT; apply Maillard 2026 compound-IM rules.

**6. HLA-B\*57 -> "abacavir risk" (4-field underspecified)**

• Trigger: Screen reports "B*57 present" as contraindication.
• Mechanism: B57:01 (HSS risk), B57:02, B*57:03 (no HSS risk).
• Symptom: False contraindication; patient denied effective therapy.
• Fix: Report 4-field; B*57:01 specifically.

**7. CYP3A5 *3 / non-expresser confusion**

• Trigger: Apply "CYP3A5 normal metabolizer" to 3/3 in tacrolimus dosing.
• Mechanism: 3/3 are NON-EXPRESSERS (most common state in non-AFR); expressers (any *1) need 1.5-2x higher dose.
• Symptom: Tacrolimus over-dosing in expressers; under-dosing in non-expressers.
• Fix: Apply CPIC 2015 (Birdwell) tacrolimus dosing; flag expresser status.

8. Activity-based vs allele-based confusion

• Trigger: Sum activities across substrate-non-specific assumption for *17.
• Mechanism: CYP2D6 *17 shows substrate-dependent activity (reduced for some substrates, near-normal for others).
• Symptom: Substrate-specific dose recommendations applied generically.
• Fix: Use substrate-specific guidance where available; flag *17 in AFR cohorts.

Reconciliation: When Tools Disagree

Quantitative Thresholds and Conventions

Common Errors

Anticipated Reviewer Pushback

References

• Sangkuhl K et al. 2020. Pharmacogenomics Clinical Annotation Tool (PharmCAT). Clin Pharmacol Ther 107:203.
• Chen X et al. 2021. Cyrius: accurate CYP2D6 genotyping using whole-genome sequencing data. Pharmacogenomics J 21:251.
• Numanagic I et al. 2018. Allelic decomposition and exact genotyping of highly polymorphic and structurally variant genes. Nat Commun 9:828. (Aldy)
• Lee SB et al. 2019. Stargazer: a tool for calling star alleles. Genet Med 21:361.
• Twesigomwe D et al. 2020. A systematic comparison of pharmacogene star allele calling bioinformatics algorithms. npj Genom Med 5:30.
• Caudle KE et al. 2020. Standardizing CYP2D6 genotype to phenotype translation. Clin Transl Sci 13:116. (Activity-score reset for *10)
• Bank PCD et al. 2018. Comparison of the guidelines of the CPIC and the Dutch Pharmacogenetics Working Group. Clin Pharmacol Ther 103:599.
• Amstutz U et al. 2018. CPIC guideline for dihydropyrimidine dehydrogenase genotype and fluoropyrimidine dosing: 2017 update. Clin Pharmacol Ther 103:210. (DPYD activity score)
• Swen JJ et al. 2023. PREPARE: A pre-emptive pharmacogenetic testing strategy. Lancet 401:347.
• Henricks LM et al. 2018. DPYD-guided dose individualization to fluoropyrimidines. Lancet Oncol 19:1459.
• Pereira NL et al. 2020. Effect of genotype-guided oral P2Y12 inhibitor selection vs conventional clopidogrel therapy on ischemic outcomes after PCI. JAMA 324:761. (TAILOR-PCI)
• Pereira NL et al. 2021. Effect of CYP2C19 genotype on ischemic outcomes during oral P2Y12 inhibitor therapy: a meta-analysis. JACC Cardiovasc Interv 14:739.
• Mallal S et al. 2008. HLA-B5701 screening for hypersensitivity to abacavir. NEJM* 358:568. (PREDICT-1)
• Chung WH et al. 2004. Medical genetics: a marker for Stevens-Johnson syndrome. Nature 428:486.
• McCormack M et al. 2011. HLA-A3101 and carbamazepine-induced hypersensitivity reactions in Europeans. NEJM* 364:1134.
• Hung SI et al. 2005. HLA-B5801 allele as a genetic marker for severe cutaneous adverse reactions caused by allopurinol. PNAS* 102:4134.
• Yang JJ et al. 2015. Inherited NUDT15 variant is a genetic determinant of mercaptopurine intolerance. J Clin Oncol 33:1235.
• Relling MV et al. 2019. CPIC guideline for thiopurine dosing based on TPMT and NUDT15 genotypes: 2018 update. Clin Pharmacol Ther 105:1095.
• PharmCAT documentation: https://pharmcat.org
• PharmVar: https://www.pharmvar.org
• CPIC: https://cpicpgx.org
• DPWG: https://www.knmp.nl/dpwg

Related Skills

• clinical-databases/hla-typing - HLA-B57:01, B15:02, B58:01, A31:01 typing
• clinical-databases/clinvar-lookup - Variant pathogenicity for non-PGx context
• clinical-databases/variant-prioritization - Rare-disease pipeline
• clinical-databases/myvariant-queries - Aggregated PGx variant annotation
• chemoinformatics/admet-prediction - Drug metabolism prediction