bio-applied-hla-typing

name	bio-applied-hla-typing
description	Type HLA-A/B/C/DRB1 with OptiType/arcasHLA and predict peptide-MHC binding (NetMHCpan %Rank_EL/IC50) to rank neoantigens. Use for HLA typing, MHC binding, pVACseq, HLA LOH, or HLA-B*57:01 screening.
tool_type	bash
primary_tool	NetMHCpan

HLA Typing and Antigen Presentation

When to Use

• Typing HLA class I (-A/-B/-C) or class II (-DRB1/-DQ/-DP) alleles from WGS, WES, or RNA-seq reads
• Predicting peptide-MHC binding affinity for a peptide list or tumor somatic mutations (neoantigen prioritization, pVACseq-style pipelines)
• Detecting tumor HLA loss of heterozygosity (LOH) as an immune-escape mechanism
• Screening a patient's HLA genotype for known drug-hypersensitivity or disease associations (e.g. HLA-B57:01/abacavir, HLA-B15:02/carbamazepine)
• Summarizing HLA allele frequencies / homozygosity across a cohort

Version Compatibility

OptiType 1.3.5, arcasHLA 0.6.0, HLA-LA 1.0.3, NetMHCpan 4.1 / NetMHCIIpan 4.3, pVACtools ≥4.0, Python ≥3.10, pandas ≥2.0, numpy ≥1.26, matplotlib ≥3.8.

Prerequisites

pip install pandas numpy matplotlib. OptiType, arcasHLA, HLA-LA, and NetMHCpan are separate CLI tools (install via conda/bioconda or Docker/Singularity; NetMHCpan requires a license from DTU Health Tech). Prior concepts: bio-variant-calling-vcf-basics (somatic VCF for neoantigen input), bio-read-alignment-bwa-alignment (BAM inputs for typing).

HLA Typing from NGS Reads

Goal: Call 4-digit HLA-A/B/C (and optionally class II) genotypes from a BAM or FASTQ. Approach: Use a read-based typer against the IMGT/HLA reference; RNA-seq samples use arcasHLA, DNA (WGS/WES) samples use OptiType or HLA-LA.

# OptiType: DNA or RNA reads -> 4-digit class I genotype (ILP over HLA-mapped reads)
OptiTypePipeline.py -i tumor_R1.fastq tumor_R2.fastq \
    --dna -v -o optitype_out/
# Output: optitype_out/<timestamp>/<sample>_result.tsv
#   A*02:01,A*03:01,B*07:02,B*44:02,C*05:01,C*07:02

# arcasHLA: RNA-seq BAM -> class I + II genotype, good when only RNA-seq exists
arcasHLA extract --unmapped -o hla_reads/ tumor_rna.bam
arcasHLA genotype hla_reads/sample.extracted.1.fq.gz \
                   hla_reads/sample.extracted.2.fq.gz \
                   -g A,B,C,DPB1,DQB1,DQA1,DRB1 \
                   -o hla_typing/
# Output: hla_typing/sample.genotype.json

Tumor HLA LOH is called by comparing tumor vs matched-normal genotypes (or allele-specific copy number with a tool like LOHHLA), not by typing the tumor alone — apparent homozygosity in tumor-only RNA-seq can also come from allele-specific expression, not true LOH.

Cohort HLA Summary and Neoantigen Ranking

Goal: Summarize HLA allele frequencies/homozygosity across a cohort, and rank candidate neoantigens by predicted binding affinity. Approach: Parse per-sample typing calls into a DataFrame for cohort-level stats; parse NetMHCpan -BA output into a ranked table filtered by %Rank_EL/IC50 thresholds.

import numpy as np
import pandas as pd


def simulate_hla_cohort(n_patients=20, seed=42):
    """Build a toy HLA-A/B/C genotype table for n_patients (stand-in for
    parsing real OptiType/arcasHLA result.tsv files into one DataFrame).
    Allele pools/frequencies are approximate European population values.
    """
    rng = np.random.default_rng(seed)
    hla_a_pool = ['A*02:01', 'A*01:01', 'A*03:01', 'A*24:02', 'A*11:01',
                  'A*29:02', 'A*23:01', 'A*26:01', 'A*31:01', 'A*32:01']
    hla_b_pool = ['B*07:02', 'B*08:01', 'B*44:02', 'B*44:03', 'B*35:01',
                  'B*51:01', 'B*40:01', 'B*15:01', 'B*18:01', 'B*57:01']
    hla_c_pool = ['C*07:01', 'C*07:02', 'C*03:04', 'C*05:01', 'C*04:01',
                  'C*06:02', 'C*01:02', 'C*02:02', 'C*08:02', 'C*16:01']
    a_probs = np.array([0.283, 0.161, 0.143, 0.098, 0.072,
                         0.054, 0.041, 0.038, , ])
    a_probs /= a_probs.()
    b_probs = np.array([, , , , ,
                         , , , , ])
    b_probs /= b_probs.()

    rows = []
     i  (n_patients):
        rows.append({
            : ,
            : rng.choice(hla_a_pool, p=a_probs),
            : rng.choice(hla_a_pool, p=a_probs),
            : rng.choice(hla_b_pool, p=b_probs),
            : rng.choice(hla_b_pool, p=b_probs),
            : rng.choice(hla_c_pool),
            : rng.choice(hla_c_pool),
        })
    df = pd.DataFrame(rows)
    df[] = df[] == df[]
    df[] = df[] == df[]
     df


 ():
    
    df = pd.DataFrame({: mutations, : ic50_nM})
    df[] = pd.cut(
        df[], bins=[, strong_cutoff, weak_cutoff, np.inf],
        labels=[, , ],
    )
     df.sort_values().reset_index(drop=)


hla_df = simulate_hla_cohort()
candidate_neoantigens = rank_neoantigens(
    mutations=[, , , ,
               , , , ],
    ic50_nM=[, , , , , , , ],
)

(hla_df[[, , , , ]].head().to_string(index=))
()
()

Visualizing HLA and Neoantigen Results

Goal: Produce one figure combining a neoantigen binding waterfall, cohort allele distribution, and a pharmacogenomic frequency check. Approach: Three matplotlib panels driven by the DataFrames above.

import matplotlib.pyplot as plt
import matplotlib.patches as mpatches


def plot_hla_neoantigen_summary(hla_df, candidate_neoantigens, out_png=None):
    """Three-panel HLA/neoantigen summary figure.

    Panel 1: neoantigens ranked by predicted binding (lower IC50 = tighter).
    Panel 2: HLA-A allele distribution across the cohort.
    Panel 3: HLA-B*57:01 population frequency (abacavir screen relevance).
    """
    colors = {'Strong Binder': 'firebrick', 'Weak Binder': 'orange', 'Non-binder': 'lightgray'}
    fig, axes = plt.subplots(1, 3, figsize=(16, 5))

    sorted_df = candidate_neoantigens.sort_values('IC50_nM')
    bar_colors = [colors[b] for b in sorted_df['Binding_Level']]
    axes[0].barh(sorted_df['mutation'], -np.log10(sorted_df['IC50_nM'] + 1),
                 color=bar_colors, edgecolor='black', linewidth=0.5)
    axes[0].axvline(-np.log10(51), color='red', linestyle='--')
    axes[0].axvline(-np.log10(501), color='orange', linestyle='--')
    axes[0].set_xlabel('-log10(IC50 nM)')
    axes[0].set_title('Neoantigen MHC-I Binding')
    axes[0].legend(handles=[mpatches.Patch(color=v, label=k) for k, v  colors.items()],
                   fontsize=, loc=)

    all_a = pd.concat([hla_df[], hla_df[]]).value_counts()
    axes[].bar(all_a.index, all_a.values, color=, edgecolor=, linewidth=)
    axes[].set_xticklabels(all_a.index, rotation=, ha=, fontsize=)
    axes[].set_title()

    populations = [, , , , ]
    b5701_freq = [, , , , ]  
    axes[].bar(populations, b5701_freq, color=, edgecolor=, linewidth=)
    axes[].axhline(, color=, linestyle=, label=)
    axes[].set_xticklabels(populations, rotation=, ha=, fontsize=)
    axes[].set_ylabel()
    axes[].set_title()
    axes[].legend(fontsize=)

    plt.tight_layout()
     out_png:
        plt.savefig(out_png, dpi=, bbox_inches=)
     fig

HLA Biology Reference

• Class I (HLA-A/-B/-C): all nucleated cells; presents 8–11 aa intracellular peptides (proteasome → TAP → ER loading) to CD8+ T cells.
• Class II (HLA-DR/-DQ/-DP): professional APCs only; presents 13–25 aa extracellular/endosomal peptides to CD4+ T cells.
• Nomenclature: A*02:01 = gene A, field 1 (02) = allele group/serotype, field 2 (01) = protein sequence; 6/8-digit fields add synonymous/non-coding variants. HLA-A*02:01 is the most common HLA-A allele in Europeans (~28%).
• Disease/PGx associations: HLA-B57:01 → abacavir hypersensitivity (OR >1000, mandatory pre-screen); HLA-B15:02 → carbamazepine SJS/TEN (~OR 80); HLA-DQ2/DQ8 → celiac disease; HLA-A*02:01 → improved melanoma immunotherapy response via neoantigen presentation.
• Tumor HLA LOH: ~40% of NSCLC tumors show HLA LOH as an immune-escape route (McGranahan et al. 2017, TRACERx).

Pitfalls

• Reference bias in typing: standard linear reference genomes collapse HLA diversity in the hyper-polymorphic exons 2–3; always type against an HLA-specific reference (IMGT/HLA), not the primary GRCh38 HLA region.
• Coverage at the HLA locus: <30x at HLA-A/B/C in WES/WGS causes false homozygosity calls; check locus-level depth before trusting a typing result.
• RNA-seq apparent LOH: allele-specific expression can make a tumor look HLA-homozygous in RNA-seq even when both alleles are present in DNA — confirm LOH with matched-normal DNA typing or a copy-number-aware tool (e.g. LOHHLA), not RNA-seq alone.
• %Rank_EL vs %Rank_BA: NetMHCpan reports both an eluted-ligand rank and a binding-affinity rank; they use different score distributions — don't apply a %Rank_EL < 0.5% cutoff to a %Rank_BA column or vice versa.
• Class II is less reliable: NetMHCIIpan has fewer training epitopes and an open-ended binding groove, so predictions are noisier than class I — treat class II neoantigen calls as lower confidence.
• Nomenclature mismatches: typing tools, NetMHCpan (HLA-A02:01, no *), and IMGT/HLA (A*02:01) each expect slightly different allele string formats — normalize before joining tables.

See Also

• bio-clinical-databases-hla-typing
• bio-immunoinformatics-mhc-binding-prediction
• bio-immunoinformatics-neoantigen-prediction
• bio-workflows-neoantigen-pipeline