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-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', [])