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 `DRB401: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 (Claeys 2023 BMC Genomics; Matey-Hernandez 2018):* T1K is currently the best general-purpose all-rounder; HLA-LA is the class-II reference; OptiType is the class-I anchor for WES. For full coverage of class I + II + KIR on WGS/WES, T1K is the 2024-2026 recommendation.

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-B57 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.

Reconciliation: When Tools Disagree

Quantitative Thresholds and Conventions

CIWD v3.0.0 Ambiguity Catalogue

Hurley 2020 HLA 95:516; compiled from >8M unrelated HSCT donors across 7 geographic/ancestral groups. Categories: Common (18%, n=545), Intermediate (17%, n=513), Well-Documented (65%, n=1,997) at 2-field. Replaces legacy CWD 2.0 (Mack 2013); many older pipelines still hardcode CWD 2.0; a quiet quality failure.

TCE3 Core vs Non-Core (Meurer 2024 Blood)

DPB1 mismatch GvHD/relapse risk depends on TCE3 group:

• *Core (DPB1\02:01, \04:01, \04:02, \23:01):* GvHD reduction with permissive mismatch in the GvH direction.
• Non-core: Relapse-protection effects predominate.

Now operational in NMDP donor selection algorithms; legacy TCE3 frameworks (Crocchiolo 2009) lack this stratification.

Common Errors

Anticipated Reviewer Pushback

References

• Robinson J et al. 2024. IPD-IMGT/HLA database: 25 years of evolution. HLA.
• Robinson J et al. 2026. IPD-IMGT/HLA recent developments. Nucleic Acids Res 54:D1152.
• Szolek A et al. 2014. OptiType: precision HLA typing from NGS data. Bioinformatics 30:3310.
• Dilthey AT et al. 2019. HLALA; HLA typing from linearly projected graph alignments. Bioinformatics* 35:4054.
• Song B et al. 2023. T1K: efficient and accurate KIR and HLA genotyping. Genome Res.
• Shukla SA et al. 2015. Comprehensive analysis of cancer-associated somatic mutations in class I HLA genes. Nat Biotechnol 33:1152.
• Kawaguchi S et al. 2017. HLA-HD: An accurate HLA typing algorithm for next-generation sequencing data. Hum Mutat 38:788.
• Orenbuch R et al. 2020. arcasHLA: high-resolution HLA typing from RNAseq. Bioinformatics 36:33.
• Claeys A et al. 2023. Benchmark of tools for in silico prediction of MHC class I and class II genotypes from NGS data. BMC Genomics 24:9351.
• Matey-Hernandez ML et al. 2018. Benchmarking the HLA typing performance of Polysolver and Optitype in 50 Danish parental trios. BMC Bioinformatics 19:239.
• Zheng X et al. 2014. HIBAG; HLA genotype imputation with attribute bagging. Pharmacogenomics J 14:192.
• Luo Y et al. 2021. A high-resolution HLA reference panel capturing global population diversity. Nat Genet 53:1504.
• Hurley CK et al. 2020. Common, intermediate and well-documented HLA alleles in world populations: CIWD version 3.0.0. HLA 95:516.
• Meurer T et al. 2024. New HLA-DPB1 T-cell epitope model for mismatched URD transplant. Blood 144:1659.
• Douillard V et al. 2024. Population-specific HLA imputation reference panels. HLA.

Related Skills

• clinical-databases/pharmacogenomics - HLA-drug interactions, abacavir/carbamazepine screening
• immunoinformatics/mhc-binding-prediction - Downstream HLA-peptide binding for neoantigen
• workflows/neoantigen-pipeline - HLA typing as upstream step
• clinical-databases/clinvar-lookup - HLA disease associations
• population-genetics/population-structure - Ancestry-aware imputation context