mhcseqs

Self-contained pipeline for downloading, curating, and extracting binding grooves from MHC (Major Histocompatibility Complex) protein sequences.

Install

pip install mhcseqs

For development:

git clone https://github.com/pirl-unc/mhcseqs.git
cd mhcseqs
./develop.sh          # uv pip install -e ".[dev]"
./test.sh             # pytest
./lint.sh             # ruff

Quick start

CLI

# Build all output CSVs (writes to ~/.cache/mhcseqs/)
mhcseqs build

# Build to a specific directory instead
mhcseqs build --output-dir output/

# Look up a specific allele
mhcseqs lookup "HLA-A*02:01"

# Inspect cached downloads and built CSVs (path, size, age)
mhcseqs data list

# Re-download source FASTAs (IMGT/HLA + IPD-MHC publish from a rolling "Latest")
mhcseqs data refresh
mhcseqs build --force-download   # equivalently, rebuild with fresh sources

# Delete cached files
mhcseqs data clear               # source FASTAs
mhcseqs data clear --built       # also remove built CSVs/reports
mhcseqs data clear --built-only  # only built CSVs/reports

# Check version
mhcseqs --version

Python API

import mhcseqs

# Build the database (downloads to ~/.cache/mhcseqs/, only needed once)
paths = mhcseqs.build()  # BuildPaths dataclass

# Look up any allele → AlleleRecord with everything
r = mhcseqs.lookup("HLA-A*02:01")
r.sequence          # full protein (with signal peptide)
r.mature_sequence   # signal peptide removed (computed property)
r.mature_start      # signal peptide length (24 for HLA-A*02:01)
r.groove1           # α1 domain
r.groove2           # α2 domain
r.ig_domain         # α3 Ig-fold
r.tail              # TM + cytoplasmic
r.domains           # typed domain spans
r.domain_architecture
r.domain_spans
r.species_category  # "human"

# Apply mutations (IEDB-style, e.g. "K66A")
m = mhcseqs.lookup("HLA-A*02:01", mutations=["K66A", "D77S"])

Load as a DataFrame

import mhcseqs

# As a DataFrame (full sequence + groove decomposition + metadata)
df = mhcseqs.load_sequences_dataframe()

# Or as a list of dicts (no pandas dependency)
rows = mhcseqs.load_sequences_dict()

Current data summary

All sources (IMGT/HLA, IPD-MHC, UniProt curated references, and 15,860 diverse MHC sequences from UniProt) are merged into a single dataset:

Covering 558+ species. Groove parse success rate on IMGT/IPD-MHC entries: 99.3%.

Structural decomposition

The parser materializes an explicit domain grammar:

The exported contiguous sequence fields are:

domain_architecture and domain_spans expose the typed domain grammar directly, for example:

• class I: signal_peptide>g_alpha1>g_alpha2>c1_alpha3>tail_linker>transmembrane>cytoplasmic_tail
• class II beta: signal_peptide>g_beta1>c1_beta2>tail_linker>transmembrane>cytoplasmic_tail

How Parsing Works

The parser is alignment-free and holistic. It does not rely on one absolute Cys position to define the mature start.

For each sequence it:

1. Enumerates all plausible Cys-Cys pairs in the Ig/C-like separation range.
2. Scores each pair as a candidate G-domain or C-like anchor using fold-topology evidence, especially the Trp41-like signal around c1+14.
3. Enumerates candidate SP boundaries and whole domain parses, including partial parses when only fragment evidence is available.
4. Chooses the best full parse using factored multiplicative scoring: three structural claims (SP grammar, domain architecture, completeness) each produce a [0,1] factor. Contradictory evidence in any factor gates the score down multiplicatively, while missing evidence is a softer penalty.

The strongest evidence types are:

• SP cleavage grammar: hydrophobic h-region, short c-region, von Heijne -3/-1 compatibility, exclusion of impossible -3/-1 property pairs, and mild +1 mature-sequence penalties.
• Domain-fold grammar: canonical G-domain versus C-like disulfide topology, including the IMGT-style Cys11-Cys74 G-domain signature and the Cys23/Trp41/Cys104 C-like grammar.
• Class-specific groove boundaries:
  • class I α1/α2 junction motifs
  • class I α2 -> α3 boundary motifs
  • class II α1 -> α2 and β1 -> β2 boundary motifs
• Soft priors on groove/support-domain lengths and TM support downstream.

The parser handles:

• full-length proteins with or without signal peptides
• SP-stripped deposits (mature_start = 0)
• common fragments:
  • class I exon 2 only -> alpha1_only
  • class I exon 3 only -> alpha2_only
  • class II exon 2-like fragments -> fragment_fallback
• low-evidence salvage:
  • class I from α3 C-like support only -> inferred_from_alpha3
  • class II beta from β1 groove pair only -> beta1_only_fallback
• true groove absence / insufficient structural evidence -> missing_groove

Groove Status Values

These are the important parser-facing statuses:

Pipeline-only statuses can still appear in CSV outputs:

Literature Basis

The parser is built around conserved sequence grammar from the MHC literature:

• MHC domain organization is more conserved than short local motifs across vertebrates: Primordial Linkage of β2-Microglobulin to the MHC
• IMGT domain numbering and the G-domain versus C-like disulfide grammar: PMC3913909
• Classical class-I domain layout and landmarks: PMC2434379
• Salmonid class-II alpha/beta cysteine topology and lineage-specific extra cysteines: PMC2386828
• Teleost class-II evolutionary divergence while retaining the same modular architecture: PMC4219347

Signal-peptide logic follows the standard SPase grammar:

• von Heijne -3/-1 cleavage rule: How signal sequences maintain cleavage specificity
• flanking -2/+1 effects: Flanking signal and mature peptide residues influence signal peptide cleavage
• strong penalty for +1 Pro: PubMed 1544500
• h-region / c-region structural context: Structure of the human signal peptidase complex reveals the determinants for signal peptide cleavage

Key columns

Dependencies

• Python 3.10+
• mhcgnomes >= 3.41.0 — allele parsing, species provenance, NHP taxonomy, and species-directed gene classification

mhcseqs emits full-binomial species aliases such as HomoSapiens-A*02:01 and MusMusculus-K*b. Its input registry accepts 476 current, historical, and external-database prefix assignments—including all 137 designation tokens in the current 125-organism IPD-MHC taxonomy register—and records an evidence URL for every one. Colliding short codes require explicit species context. mhcseqs does not invent abbreviated species prefixes, and mechanically generated 2+2/4+4/5+5 aliases are rejected unless that exact spelling has external evidence. See the prefix audit. The audit includes a versioned UniProtKB/UniSave provenance snapshot for all 239 records behind the 21 historical pairs that previously lacked raw inputs.

No alignment tools, BLAST, or structure databases are required.

License

Apache 2.0