Bio Clinical Databases Hla Typing

Version Compatibility

Reference examples tested with: OptiType 1.3.5, HLA-LA 1.0.4, T1K 1.0.6 (Song 2023), Polysolver 4.0, HLA-HD 1.7.1, arcasHLA 0.6.0, StarPhase 1.0+ (PacBio), HIBAG 1.40+, samtools 1.19+, bwa-mem 0.7.17+. IPD-IMGT/HLA database release frequency is quarterly; tools must be re-bundled with the current release to capture new alleles (~38,000 alleles at Jan 2024; ~43,000+ by Jul 2025).

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. Tool reference-bundle vintage matters more than algorithm choice for non-European cohorts; a 2022-bundled HLA-LA will silently miss thousands of post-2022 alleles dominant in African and South Asian ancestry.

HLA Typing for Clinical Applications

'Determine HLA genotype for HSCT / neoantigen prediction / PGx screening' -> Call HLA class I (A, B, C) and class II (DRB1, DRB3/4/5, DQA1, DQB1, DPA1, DPB1) alleles at the resolution required by the downstream application.

• CLI (general-purpose all-rounder): t1k --preset hla -1 R1.fq -2 R2.fq -f hla_reference.fa
• CLI (class I gold standard from WES/WGS): OptiTypePipeline.py -i R1.fq R2.fq -d
• CLI (class I + II with PRG): HLA-LA.pl --BAM input.bam --graph PRG_MHC_GRCh38_withIMGT
• CLI (RNA-seq): arcasHLA extract sample.bam -o out && arcasHLA genotype out/sample.extracted.fq.gz
• CLI (long-read transplant-grade): PacBio HiFi StarPhase
• R (imputation from SNP arrays): HIBAG::predict() with ancestry-stratified reference panel

Resolution Levels and What Each Application Requires

HLA nomenclature: HLA-A*02:01:01:01 = family : protein-changing : synonymous : intronic/UTR. Expression suffixes: N (null; DNA present, no protein expressed); L (low expression); S (secreted); Q (questionable); A (aberrant). A serologically apparent DR4-positive donor carrying DRB4*01:03:01:02N is functionally DR53-negative; a classic HSCT donor-selection failure.

G-Groups vs P-Groups: Routinely Confused

• G-groups collapse alleles with identical DNA sequence across the antigen-recognition exons (class I exons 2-3; class II exon 2). Use for sequence-level lab QC.
• P-groups collapse alleles encoding identical mature protein across class I positions 1-90 (or class II beta1 domain positions 1-94). Use for epitope-based matching and neoantigen prediction.

DRB1 + DRB3/4/5 Linkage: The Mandatory Sanity Check

DR haplotype linkage is fixed and is the canonical sanity check on any DR typing:

Any caller reporting DRB4 with DRB1*15:01 is broken or has a chimera. Use this as a routine QC check on automated pipelines.

Algorithmic Taxonomy: Short-Read Tools

Operational benchmark consensus: in the Claeys 2023 BMC Genomics 13-tool benchmark (Matey-Hernandez 2018), HLA-HD was the top class-II caller and OptiType (WES) / arcasHLA (RNA) the class-I anchors. T1K (Song 2023, not in that benchmark) adds class I + II + KIR co-typing in one pass and is the 2024-2026 all-rounder recommendation for WGS/WES.

Long-Read and Ultra-High-Resolution

ONT R9 was historically unreliable for null-allele discrimination due to homopolymer errors; R10.4 with duplex closes the gap for class I and is competitive with PacBio HiFi for class II. PacBio HiFi remains the gold standard for DPB1 4-field typing.

SNP-Based HLA Imputation: The Ancestry Footgun

When only SNP-array genotypes are available (GWAS cohorts), use imputation:

Critical caveat: imputation panel quality is the limiting factor, NOT the imputation algorithm. EUR-trained HIBAG on East-Asian SNP-array data produces confidently wrong calls. African-ancestry imputation accuracy drops 10-20 percentage points without an ancestry-matched panel (Douillard 2024 HLA). For populations underrepresented in IPD-IMGT/HLA itself, imputation is fundamentally limited regardless of method.

Decision Tree by Scenario

HLA and Pharmacogenomics

Operational rule: Pharmacogenomic HLA screening requires 4-field resolution; 2-field (e.g., "B*15") misses the specific allele.

Standard Workflow: T1K on WGS/WES

Goal: Type HLA class I, class II, KIR from short-read sequencing with KIR3DL1 Bw4/Bw6 ligand prediction.

Approach: Extract MHC-region reads, run T1K with IPD-IMGT/HLA reference; T1K outputs allele-pair calls + class II haplotype + KIR.

# Extract chr6:28-34 Mb plus alt contigs (alt-aware alignment is critical)
samtools view -b -h input.bam chr6:28000000-34000000 chr6_GL000250v2_alt chr6_GL000251v2_alt \
                              chr6_GL000252v2_alt chr6_GL000253v2_alt chr6_GL000254v2_alt \
                              chr6_GL000255v2_alt chr6_GL000256v2_alt > hla_region.bam

samtools sort -n hla_region.bam -o hla_sorted.bam
samtools fastq -1 hla_R1.fq -2 hla_R2.fq -s singletons.fq -0 /dev/null hla_sorted.bam

# Run T1K (preset hla; includes class I + II).
# Some releases ship the entry point as `run-t1k` (a wrapper script) rather than `t1k`;
# verify with `which run-t1k` / `which t1k` before scripting.
t1k --preset hla \
    -1 hla_R1.fq -2 hla_R2.fq \
    -f hla_idx/hlaidx_rna_seq.fa \
    -o sample_hla \
    --threads 8

# Output: sample_hla_genotype.tsv with HLA-A, B, C, DRB1, DRB3/4/5, DQA1, DQB1, DPA1, DPB1

OptiType for Class I (TCGA-Compatible)

Goal: Type HLA-A, B, C at 4-field from WES with high accuracy.

Approach: Razers3-based alignment to IMGT class-I reference; ILP optimization to assign reads to allele pairs.

samtools view -h input.bam chr6:28000000-34000000 | samtools fastq -1 R1.fq -2 R2.fq -
OptiTypePipeline.py -i R1.fq R2.fq -d -o optitype_out -c config.ini

# config.ini
[mapping]
razers3=/usr/bin/razers3
threads=8
[ilp]
solver=glpk
threads=8
[behavior]
deletebam=true
unpaired_weight=0
use_discordant=false

HLA-LA for Class II (PRG-Based)

Goal: Type both class I and class II at 4-field with the highest class-II accuracy of any WES tool.

Approach: Population reference graph (PRG) covering the MHC; HLA-LA maps reads to the PRG and infers the most likely paths.

HLA-LA.pl \
    --BAM input.bam \
    --graph PRG_MHC_GRCh38_withIMGT \
    --workingDir hla_la_out \
    --sampleID sample_name \
    --maxThreads 8

# Output: hla_la_out/sample_name/hla/R1_bestguess_G.txt
# Format: Locus, Allele1, Allele2, AverageCoverage

arcasHLA for RNA-seq

Goal: Type HLA class I + II directly from RNA-seq for ICI neoantigen prediction.

Approach: Extract HLA-mapped reads from STAR BAM, EM-based genotype call against IMGT.

# Update reference to current IPD-IMGT/HLA release
arcasHLA reference --update

# Extract and genotype
arcasHLA extract sample.bam -o arcas_out --threads 8
arcasHLA genotype arcas_out/sample.extracted.fq.gz -o arcas_out --threads 8 --population prior

# Output: arcas_out/sample.genotype.json

SNP-Array Imputation (HIBAG): For GWAS Cohorts

Goal: Impute HLA from SNP array genotypes when sequencing is unavailable.

Approach: HIBAG random-forest classifier with population-matched reference panel.

library(HIBAG)

# Population-matched panel is critical; mismatch causes systematic errors
# Available panels: EUR, ASN, AFR, HIS (download from HIBAG release page)
load('European-HLA4-hg19.RData')

# Load PLINK genotype (.bed/.bim/.fam)
gen <- hlaBED2Geno(bed.fn='cohort.bed', fam.fn='cohort.fam', bim.fn='cohort.bim')

# Predict each locus
hla_A <- predict(model.list[['A']], gen, type='response+prob')
hla_B <- predict(model.list[['B']], gen, type='response+prob')
hla_DRB1 <- predict(model.list[['DRB1']], gen, type='response+prob')

# Filter on probability >= 0.5 for downstream use; lower for exploratory

Per-Operation Failure Modes

1. Alt-aware alignment missing

• Trigger: BAM was aligned with bwa-mem against GRCh38 without --alt-aware; HLA reads are coerced to chr6 primary contigs.
• Mechanism: GRCh38 has ~8 alternate HLA contigs (chr6_GL000250v2_alt, etc.); without alt-aware alignment, reads from these regions get assigned to suboptimal positions on the primary chr6.
• Symptom: HLA typing accuracy drops 5-10 percentage points; high read-coverage variants get miscalled.
• Fix: Re-align the HLA region with bwa-mem-alt or use the original cDNA reference for HLA typing (extract reads to FASTQ first).

2. Stale IPD-IMGT/HLA bundle

• Trigger: Tool was installed in 2022 with the corresponding IPD-IMGT/HLA release; never updated.
• Mechanism: ~5000+ new alleles added between 2022 and 2025; new alleles dominant in under-represented ancestries.
• Symptom: Non-European samples get common alleles reported as ambiguous or as the closest legacy match.
• Fix: Update the tool's reference bundle (HLA-LA: rebuild PRG; T1K: re-run t1k-build; OptiType: update data/hla_reference_dna.fasta).

3. EUR-trained imputation on non-EUR samples

• Trigger: Use HIBAG European panel on East-Asian or African ancestry samples.
• Mechanism: Random forest was trained on EUR allele frequencies; non-EUR alleles missing from training set.
• Symptom: Confidently wrong calls; high probability assigned to incorrect alleles.
• Fix: Use ancestry-matched HIBAG panel; or switch to HLA-TAPAS multi-ancestry; or fall back to sequencing.

4. Cross-mapping DRB-related loci

• Trigger: Naive bwa-mem alignment without read-grouping at DRB1/DRB3/DRB4/DRB5.
• Mechanism: DRB1, DRB3, DRB4, DRB5 share extensive sequence identity; reads map ambiguously.
• Symptom: DR3/DR4/DR5 paralog reads contaminate DRB1 calls; haplotype linkage rule (e.g., DRB1*15:01 + DRB5) violated.
• Fix: Use HLA-LA or T1K which model paralogous loci jointly; verify DRB1+DRB3/4/5 haplotype rule.

5. DPB1 under-coverage in pre-2021 WES kits

• Trigger: Used SureSelect v5 or Nextera Rapid Capture WES; DPB1 reports homozygous typing.
• Mechanism: Pre-2021 capture kits under-covered DPB1 exon 2.
• Symptom: Heterozygous DPB1 reported as homozygous; affects HSCT matching.
• Fix: Confirm capture coverage at DPB1; if insufficient, supplement with targeted amplicon or use WGS/long-read.

6. Class II expression-allele confusion

• Trigger: Report DRB4*01:03:01:02N as functional DR53.
• Mechanism: N-suffix = null allele (DNA present but no protein expressed).
• Symptom: Functionally DR53-negative donor reported as DR53-positive; transplant matching failure.
• Fix: Parse 4-field suffix (N, L, S, Q, A); treat N as null in functional analysis; preserve full nomenclature for typing report.

7. Specific allele vs allele family confusion

• Trigger: PGx screen reports "B*57" carrier as abacavir-risk-positive.
• Mechanism: HLA-B*57 family includes *57:01 (abacavir HSS risk), *57:02, *57:03 (no HSS risk).
• Symptom: False-positive abacavir contraindication; patient denied effective therapy.
• Fix: Report at 4-field minimum; B*57:01 specifically, not B*57.

8. KIR co-typing mistaken for HLA

• Trigger: Report KIR allele as HLA.
• Mechanism: KIR (chromosome 19) and HLA (chromosome 6) are functionally paired (KIR3DL1 binds HLA-Bw4) but are distinct loci.
• Symptom: Wrong locus annotation; downstream tools fail.
• Fix: Use T1K which co-types HLA + KIR + KIR3DL2 ligand and labels output correctly.