tooluniverse-hla-immunogenomics

HLA & Immunogenomics Analysis

Pipeline for exploring HLA gene families, MHC-peptide binding, epitope associations, and their clinical implications in transplantation, vaccine development, and cancer immunotherapy. Bridges immunogenetic databases (IMGT, IEDB) with functional annotation (UniProt) and druggability data (DGIdb).

Reasoning Strategy

HLA analysis is fundamentally about peptide presentation: the polymorphism of HLA molecules determines which peptides are displayed to T cells, which in turn governs disease susceptibility, transplant rejection, drug hypersensitivity, and vaccine immunogenicity. HLA type affects disease susceptibility for autoimmune conditions (HLA-B27 and ankylosing spondylitis), transplant rejection (HLA mismatch drives alloresponse), drug hypersensitivity (abacavir causes severe hypersensitivity reactions only in HLA-B*57:01 carriers), and vaccine design (epitopes must be presented by the recipient's HLA alleles to elicit a T-cell response). Class I and Class II HLA molecules have fundamentally different binding grooves, peptide lengths, and T-cell partners — never conflate them. The absence of an epitope from IEDB means it has not been tested, not that it cannot bind.

LOOK UP DON'T GUESS: Never assume an allele's binding properties or population frequency — query IEDB for experimental binding data and IMGT for allele annotation. Do not guess which HLA alleles are common in a population; look up published frequency data via PubMed.

Guiding principles:

1. HLA nomenclature precision -- HLA allele names follow strict conventions (e.g., HLA-A*02:01); get the resolution level right
2. MHC class awareness -- Class I (A, B, C) and Class II (DR, DQ, DP) have different binding properties and clinical roles
3. Species context -- most queries target human HLA, but MHC exists across vertebrates; confirm species early
4. Evidence layering -- combine binding data (IEDB) with gene annotation (IMGT) and structural context (UniProt)
5. Clinical translation -- connect molecular findings to transplant matching, vaccine targets, or immunotherapy response
6. English-first queries -- use English terms in all tool calls; respond in the user's language

COMPUTE, DON'T DESCRIBE

When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

When to Use

Typical triggers:

• "Look up HLA-A*02:01 binding peptides"
• "What epitopes are presented by MHC class I for [pathogen]?"
• "Find HLA gene information for [allele]"
• "What MHC molecules bind [peptide/antigen]?"
• "Assess HLA associations for [disease]"
• "Find immunogenic epitopes for [virus/protein]"
• "What drugs target HLA-related pathways?"

Not this skill: For full neoantigen prediction pipelines, use tooluniverse-immunotherapy-response-prediction. For general gene function lookup, use tooluniverse-drug-target-validation.

Core Databases

Workflow Overview

Phase 0: Query Parsing & HLA Disambiguation
  Resolve allele names, identify MHC class, confirm species
    |
Phase 1: HLA Gene Lookup
  IMGT gene info, allele details, sequence data
    |
Phase 2: MHC Binding & Restriction
  IEDB MHC binding data, allele-specific peptide repertoire
    |
Phase 3: Epitope-MHC Associations
  IEDB/BVBRC epitope search, pathogen-specific epitopes
    |
Phase 4: Functional Annotation

Phase Details

Phase 0: Query Parsing & HLA Disambiguation

Parse the user's input to identify:

• HLA allele (e.g., HLA-A02:01, HLA-DRB104:01) -- note resolution level (2-digit vs 4-digit)
• MHC class (I or II) -- determines binding groove structure and peptide length
• Pathogen or antigen (e.g., SARS-CoV-2 spike, influenza HA)
• Clinical context (transplant, vaccine, autoimmunity, cancer)

HLA nomenclature quick reference:

• HLA-A*02:01 = gene A, allele group 02, specific protein 01
• Class I: HLA-A, HLA-B, HLA-C (present to CD8+ T cells, peptides 8-11 aa)
• Class II: HLA-DR, HLA-DQ, HLA-DP (present to CD4+ T cells, peptides 13-25 aa)

Phase 1: HLA Gene Lookup

Objective: Get authoritative gene and allele information from IMGT.

Tools:

• IMGT_search_genes -- search for HLA/MHC genes
  • Input: query (gene name or keyword), optional species, locus
  • Output: gene list with nomenclature, locus, species
• IMGT_get_gene_info -- get detailed gene/allele information
  • Input: gene_name (IMGT gene name)
  • Output: allele sequences, functional status, reference sequences

Workflow:

1. Search IMGT for the target HLA gene or allele
2. Retrieve full gene details including functional status and sequence
3. Note the number of known alleles (HLA-A has >7,000; HLA-B has >8,000)
4. Identify whether the allele is commonly studied or rare

If allele not found: Check nomenclature -- older names may have been reassigned. Try searching by the gene name alone (e.g., "HLA-A") and filtering results.

Allele-level detail via IPD-IMGT/HLA: For the authoritative allele-nomenclature record itself (not just gene-level info), use the IPD-IMGT/HLA tools:

• IPD_search_hla_alleles -- search by allele name prefix/substring
  • Input: name (e.g. "A*02:01" -- NOT query, a common mistake)
  • Output: list of {accession, name} pairs; a 4-field allele name like A*02:01 typically matches several full-resolution accessions (e.g. A*02:01:01:01, A*02:01:01:02)
• IPD_get_hla_allele -- fetch the full record for one accession (e.g. HLA00005)
  • Output: allele_history across IPD-IMGT/HLA release versions -- useful for confirming a name hasn't been reassigned since an older paper was published
• IPD_search_cells -- search HLA-typed reference cell lines by field value (e.g. donor lab, cell ID) -- useful for finding a well-characterized homozygous cell line for a given allele

Verified live example: IPD_search_hla_alleles({"name": "A*02:01"}) returns accessions HLA00005/HLA00006/... for the A*02:01:01:01/A*02:01:01:02/... sub-lineages; IPD_get_hla_allele({"accession": "HLA00005"}) returns the full allele-history record.

Phase 2: MHC Binding & Restriction

Objective: Find what peptides bind to a specific MHC molecule, or what MHC molecules present a given peptide.

Tools:

• iedb_search_mhc -- search for MHC molecules in IEDB
  • Input: mhc_restriction (allele name), optional mhc_class
  • Output: MHC molecules with binding data counts
• iedb_get_epitope_mhc -- get MHC binding details for an epitope
  • Input: epitope_id (IEDB epitope ID)
  • Output: MHC restriction data, binding assay results, IC50 values

Workflow:

1. Search IEDB for the target MHC allele to see available binding data
2. For specific epitope-MHC pairs, retrieve binding assay details
3. Note binding affinity (IC50 < 500 nM is typically considered a binder for class I)
4. Distinguish between binding assays (in vitro) and T-cell assays (functional)

Binding affinity interpretation (Class I):

• Strong binder: IC50 < 50 nM
• Moderate binder: IC50 50-500 nM
• Weak binder: IC50 500-5000 nM
• Non-binder: IC50 > 5000 nM

Naturally-presented ligands (immunopeptidomics): IEDB's binding assays test whether a peptide can bind; the HLA Ligand Atlas and MHC Motif Atlas instead report peptides actually eluted from HLA molecules by mass spectrometry -- direct evidence of presentation, not just affinity.

• MHCMotifAtlas_get_allele_ligands -- curated naturally-presented ligands for one allele
  • Input: allele in compact form, e.g. "A0201" (Class I) or "DRB1_01_01" (Class II) -- no asterisks/colons
  • Output: {allele, mhc_class, peptides: [{peptide}, ...]}
• HLALigandAtlas_get_benign_peptides -- benign-tissue immunopeptidome from the HLA Ligand Atlas (hla-ligand-atlas.org)
  • Input: hla_class must be the literal string "HLA-I" or "HLA-II" (not "I"/"II"), optional limit
  • Output: peptides with donor_alleles (the donor's full typed HLA set, prefixed s/ for the allele the peptide was specifically assigned to vs. n/ for the donor's other alleles) and source tissues
• HLALigandAtlas_get_donors -- donor-to-HLA-allele mapping table
  • Input: optional donor / allele substring filters
  • Always filter this call. The unfiltered (all-donors) query processes the full mapping table and can take 60+ seconds or time out; a scoped query (e.g. {"donor": "AUT01-DN13"}) returns in under a second. Never call it with no arguments in an interactive workflow.

Verified live example: MHCMotifAtlas_get_allele_ligands({"allele": "A0201"}) returns real eluted peptides (e.g. ALFTKVLENV); HLALigandAtlas_get_benign_peptides({"hla_class": "HLA-I", "limit": 3}) returns real thymus-tissue peptides with full donor-allele context.

Phase 3: Epitope-MHC Associations

Objective: Find epitopes from specific pathogens or antigens and their MHC restriction.

Tools:

• iedb_search_epitopes -- search for experimentally validated epitopes
  • Input: organism_name (source organism), source_antigen_name (protein name)
  • Output: epitope list with sequence, MHC restriction, assay results
• BVBRC_search_epitopes -- search pathogen-derived epitopes
  • Input: query (pathogen or antigen keyword), optional host, limit
  • Output: epitopes with host MHC context, assay type

Workflow:

1. Search IEDB for epitopes from the target pathogen/antigen
2. Supplement with BVBRC for additional pathogen-specific epitopes
3. Filter by the MHC allele of interest if specified
4. Categorize by assay type: binding assay, T-cell assay (IFN-gamma, cytotoxicity), MHC multimer

Important: IEDB epitopes are experimentally validated, not predicted. The absence of an epitope does not mean it won't bind -- it may simply be untested.

Population coverage for vaccine design: When selecting epitopes for a vaccine, check how common the restricting HLA allele is in the target population. An epitope restricted to HLA-A*02:01 covers ~50% of Europeans but <15% of some African populations. For broad population coverage, select epitopes across multiple HLA supertypes (A2, A3, B7, B44 cover >95% of most populations).

Phase 4: Functional Annotation

Objective: Get protein-level features for HLA molecules and related proteins.

Tools:

• UniProt_search -- search for HLA protein entries
  • Input: query (protein/gene name), optional organism, limit
  • Output: protein entries with accession, function, features

Workflow:

1. Search UniProt for the HLA protein (e.g., "HLA-A human")
2. Extract functional domains: signal peptide, alpha chains, transmembrane region
3. Note polymorphic positions that define allele specificity
4. Check for structural data (PDB cross-references)

Phase 5: Clinical & Therapeutic Context

Objective: Connect HLA findings to drug interactions and clinical evidence.

Tools:

• DGIdb_get_drug_gene_interactions -- find drugs targeting HLA-pathway genes
  • Input: genes (list of gene names, e.g., ["HLA-A", "B2M"])
  • Output: drug-gene interactions, interaction types, sources
• PubMed_search_articles -- find clinical HLA studies
  • Input: query (search term), optional limit
  • Output: articles with title, abstract, PMID

Workflow:

1. Query DGIdb for drug interactions with relevant HLA genes
2. Search PubMed for clinical studies (transplant outcomes, pharmacogenomics, disease associations)
3. For transplant queries, look for HLA matching guidelines and outcomes data
4. For pharmacogenomics, note HLA alleles linked to drug hypersensitivity (e.g., HLA-B*57:01 and abacavir)

Well-known HLA-drug associations (for context, always verify with current data):

• HLA-B*57:01: abacavir hypersensitivity
• HLA-B*15:02: carbamazepine SJS/TEN (Southeast Asian populations)
• HLA-B*58:01: allopurinol hypersensitivity
• HLA-A*31:01: carbamazepine drug reaction (European populations)

Phase 6: Report Synthesis

Structure the report as:

1. HLA Context -- gene/allele identification, MHC class, population frequency if available
2. Binding Profile -- peptide repertoire, binding affinity distribution
3. Epitope Landscape -- pathogen-specific epitopes, assay evidence
4. Protein Features -- structural domains, polymorphic sites
5. Clinical Relevance -- transplant implications, drug associations, disease links
6. Evidence Summary -- graded by source (IEDB experimental > computational prediction > literature mention)

Edge Cases & Fallbacks

• Ambiguous allele name: Ask user for resolution level. "HLA-A2" could mean HLA-A02:01 or the broader A02 group
• No IEDB data for allele: Common for rare alleles. Note the gap; suggest computational prediction tools
• Cross-species MHC: IMGT covers multiple species. Confirm species context for non-human queries (e.g., H-2 for mouse)
• BVBRC empty results: Try broader organism name or use IEDB as primary source

Limitations

• No binding prediction: This skill queries experimental databases, not prediction algorithms (NetMHCpan, MHCflurry). It tells you what has been measured, not what might bind
• Population frequency gaps: HLA allele frequencies vary dramatically by ethnicity; databases may not cover all populations equally
• Class II complexity: Class II molecules are heterodimers (alpha + beta chains); binding prediction and data are less mature than for Class I
• Epitope completeness: IEDB coverage is biased toward well-studied pathogens (HIV, influenza, SARS-CoV-2) and common HLA alleles