bio-clinical-databases-hla-typing

What this skill does

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

| Application | Min resolution | Why |
|-------------|---------------|-----|
| **HSCT (unrelated donor)** | 6-field (12/12 match) | Null alleles + permissive DPB1 + Bw4/Bw6 + TCE3 core/non-core |
| **Solid organ transplant** | 4-field (2-digit:2-digit) | Eplet-level epitope match (HLAMatchmaker, PIRCHE-II) |
| **ICI neoantigen prediction** | 4-field class I + II | NetMHCpan-4.1 minimum |
| **HLA-disease association** | 4-field | Standard for GWAS HLA fine-mapping |
| **HLA-B\*57:01 abacavir screen** | 4-field, specific | Other \*57 alleles (\*57:03) do NOT cause HSS |
| **HLA-B\*15:02 carbamazepine** | 4-field, specific | \*15:02 only; \*15:01 (NFE-common) is not the risk allele |

## 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:

| DRB1 allele family | Linked DRB3/4/5 |
|---------------------|-----------------|
| DR1 (\*01), DR8 (\*08), DR10 (\*10) | None |
| DR3 (\*03), DR11 (\*11), DR12 (\*12), DR13 (\*13), DR14 (\*14) | DRB3 |
| DR4 (\*04), DR7 (\*07), DR9 (\*09) | DRB4 |
| DR15 (\*15), DR16 (\*16) | DRB5 |

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

| Tool | Class I | Class II | KIR | Resolution | Approach | Fails when |
|------|---------|----------|-----|-----------|----------|-----------|
| **OptiType** (Szolek 2014 *Bioinformatics* 30:3310) | Yes (~98% 4-digit) | No | No | 4-field | ILP on exons 2-3 | Class II needed; very deep contamination |
| **Polysolver** (Shukla 2015 *Nat Biotechnol* 33:1152) | Yes (~95% 4-digit) | No | No | 4-field | Allele-specific ref alignment | Class II; non-European ancestry under-typing |
| **HLA-LA** (Dilthey 2019 *Bioinformatics* 35:4054) | Yes (~94% class I) | Yes (best class II of WES tools) | No | 4-field | Graph-based PRG | High RAM/disk (~30-100 GB scratch) |
| **T1K** (Song 2023 *Genome Res*) | Yes (~99% 4-digit) | Yes (~99%) | Yes (KIR + KIR3DL2 ligand) | 4-field | EM on consensus reference | Newer; less benchmarking on edge cases |
| **HLA-HD** (Kawaguchi 2017 *Hum Mutat* 38:788) | Yes (~98%) | Yes (~95%) | No | 4-field | Bowtie2 against IPD-IMGT | License required for commercial use |
| **arcasHLA** (Orenbuch 2020 *Bioinformatics* 36:33) | Yes (~100% 2-field) | Yes (>99% 2-field) | No | 4-field from RNA-seq | EM on STAR alignment | DNA-seq; population prior bias in non-EUR |
| **PHLAT, HLAforest, HLAminer, seq2HLA, HLAreporter** | Yes | Some | No | Mostly 2-4 field | Various | Older; superseded |

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

| Tool | Platform | Resolution | Use case |
|------|----------|-----------|----------|
| **StarPhase** (PacBio official 2024+) | PacBio HiFi | 8-field (full-field) | Transplant-grade typing |
| **HLA*ASM** | PacBio HiFi | 8-field | Assembly-based |
| **FuFiHLA** (2025 bioRxiv) | PacBio HiFi + ONT R10 | 8-field | Platform-agnostic |
| **HLAminer streaming** (Warren 2025) | ONT long-read | 4-field | Streaming nanopore |
| **pbaa + StarPhase** | PacBio amplicon | 8-field | Cost-effective targeted typing |
| **IGenotyper** (Roe 2021) | PacBio long-read | 8-field | Immunogenetics-focused |

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:

| Tool | Approach | Reference panel | Best for |
|------|----------|----------------|----------|
| **HIBAG** (Zheng 2014 *Pharmacogenomics J* 14:192) | Random forest from SNP-array | Pre-fit per-ancestry classifiers (EUR, AS, AFR, HIS) | Population-stratified GWAS |
| **HLA-TAPAS** (Luo 2021 *Nat Genet* 53:1504) | Multi-ancestry imputation | 21,546 multi-ancestry reference | Cross-ancestry GWAS |
| **HLA*IMP:02** (Dilthey 2013) | Hidden Markov | EUR-only | Legacy; EUR-only |
| **SNP2HLA** (Jia 2013) | Beagle-based | Type 1 Diabetes / EUR | Older; EUR-only |
| **CookHLA** (Cook 2021) | Hybrid SNP2HLA + supplementary | Multi-ancestry refs | Modern alternative to SNP2HLA |
| **Multi-Ethnic Reference Panel** (Degenhardt 2019) | Multi-ancestry imputation | Cross-population samples | Cross-ancestry GWAS |

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

| Scenario | Recommended path | Why |
|----------|------------------|-----|
| WGS/WES, class I only, max speed | OptiType | Best class-I accuracy, ILP-based,