tooluniverse-hla-immunogenomics

What this skill does

# 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

| Database | Scope | Best For |
|----------|-------|----------|
| **IMGT** | International ImMunoGeneTics; HLA/MHC gene nomenclature and sequences | Authoritative HLA gene info, allele nomenclature, sequence data |
| **IEDB** | Immune Epitope Database; experimentally validated epitope-MHC data | Epitope binding, MHC restriction, T-cell assay results |
| **BVBRC** | BV-BRC (formerly PATRIC/IRD); pathogen epitopes | Pathogen-derived epitopes with host MHC context |
| **UniProt** | Protein function and structure annotations | HLA protein features, domains, variants |
| **DGIdb** | Drug-Gene Interaction Database | Druggability of HLA-pathway genes |
| **PubMed** | Biomedical literature | Clinical HLA studies, transplant outcomes |

---

## 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
  UniProt protein features, structural domains
    |
Phase 5: Clinical & Therapeutic Context
  DGIdb druggability, PubMed clinical evidence
    |
Phase 6: Report Synthesis
  Integrated immunogenomics report
```

---

## Phase Details

### Phase 0: Query Parsing & HLA Disambiguation

Parse the user's input to identify:
- **HLA allele** (e.g., HLA-A*02:01, HLA-DRB1*04: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.

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

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

**Importan