mhcseqs

Self-contained pipeline for downloading, curating, and extracting binding grooves from MHC protein sequences.

Installation

pip install mhcseqs

For development:

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

Requirements: Python 3.10+, mhcgnomes (installed automatically).

CLI Reference

mhcseqs build

Downloads FASTA sources (IMGT/HLA + IPD-MHC), parses alleles, selects two-field representatives, extracts binding grooves, and runs validation.

mhcseqs build [--output-dir DIR] [--data-dir DIR]

Produces four files:

mhcseqs lookup

Query built CSVs by allele name.

mhcseqs lookup "HLA-A*02:01"
mhcseqs lookup "Mamu-A1*001:01"

mhcseqs --version

Print the installed version.

Python API

Allele lookup

import mhcseqs

# Build the database (downloads FASTA sources, only needed once)
paths = mhcseqs.build()

# Look up any allele → AlleleRecord with everything
r = mhcseqs.lookup("HLA-A*02:01")
r.allele             # "HLA-A*02:01" (two-field)
r.full_allele        # "HLA-A*02:01:01:100" (full resolution)
r.sequence           # full protein (with signal peptide)
r.mature_sequence    # signal peptide removed (computed property)
r.mature_start       # signal peptide length (24)
r.groove1            # α1 domain (90 aa)
r.groove2            # α2 domain (93 aa)
r.ig_domain          # α3 Ig-fold (95 aa)
r.tail               # TM + cytoplasmic
r.species_category   # "human"

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

Load all sequences

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()

Species utilities

mhcseqs.normalize_species("Macaca mulatta")  # "macaque"
mhcseqs.normalize_mhc_species("macaque")      # "nhp"
mhcseqs.get_latin_name("macaque")             # "Macaca mulatta"
mhcseqs.get_canonical_prefix("macaque")       # "Mamu"

Allele utilities

mhcseqs.normalize_allele_name("A0201")  # "HLA-A*02:01"
mhcseqs.infer_gene("HLA-A*02:01")       # "A"
mhcseqs.infer_mhc_class("HLA-A*02:01")  # "I"

Output columns

mhc-seqs-raw.csv

mhc-full-seqs.csv

Shares columns with the raw CSV: two_field_allele, gene, mhc_class, chain, species, species_category, species_prefix, source, seq_len, sequence, is_null, is_questionable, is_pseudogene. Additional columns:

Groove extraction algorithm

The parser is alignment-free and holistic. It scores signal peptide, groove, support-domain, and TM evidence together instead of anchoring the parse on one fixed mature-position constant.

Domain architecture

Class I alpha:   signal_peptide? -> g_alpha1 -> g_alpha2 -> c1_alpha3 -> TM? -> tail?
Class II alpha: signal_peptide? -> g_alpha1 -> c1_alpha2 -> TM? -> tail?
Class II beta:  signal_peptide? -> g_beta1  -> c1_beta2  -> TM? -> tail?

How it works

1. Enumerate all plausible Cys-Cys pairs in the Ig/C-like separation range.
2. Score each pair as G-domain or C-like using Trp41-like fold topology, Cys-flank composition, and pair separation.
3. Enumerate candidate SP boundaries and complete domain parses, including partial-fragment parses when needed.
4. Choose the best whole parse from combined evidence: SP grammar, groove anchor, groove boundary motifs, support-domain evidence, and TM support.

The main evidence sources are:

• SP grammar: hydrophobic h-region, short c-region, von Heijne -3/-1 compatibility, and impossible-pair exclusions.
• Domain grammar: G-domain versus C-like disulfide topology, especially the Trp41-like signal around c1+14.
• Class-specific groove boundaries: class-I α1/α2 junctions and groove -> C-like boundary motifs for class I and class II.
• Soft priors on groove/support-domain lengths and downstream TM support.

Groove status codes

Literature basis

• PMC3805034: vertebrate MHC class I / class II modular domain organization.
• PMC3913909: IMGT numbering and G-domain versus C-like landmarks.
• PMC2434379: classical class-I domain layout and landmarks.
• PMC2386828: salmonid class-II cysteine topology and lineage-specific extra cysteines.
• PMC4219347: teleost class-II evolution with retained domain grammar.
• PubMed 6423828: von Heijne signal-peptide cleavage rule.
• PMC2638155: flanking -2/+1 cleavage effects.
• PubMed 1544500: strong disfavoring of +1 Pro.
• Structure of the human signal peptidase complex: h-region / c-region determinants beyond the local cleavage tetrapeptide.

Species taxonomy

Every entry is assigned a species_category from a 10-class taxonomy:

Module reference

mhcseqs.domain_parsing

Core groove extraction. Key functions:

• extract_groove(seq, mhc_class, ...) — main dispatcher
• parse_class_i(seq, ...) — class I alpha chain parser
• parse_class_ii_alpha(seq, ...) — class II alpha chain parser
• parse_class_ii_beta(seq, ...) — class II beta chain parser
• find_cys_pairs(seq) — locate Ig-fold Cys-Cys pairs
• AlleleRecord — dataclass with all parsed fields

mhcseqs.alleles

Allele name parsing via mhcgnomes:

• parse_allele_name(name) — parse with mhcgnomes
• normalize_allele_name(name) — canonical two-field form
• infer_gene(allele) — extract gene (e.g. "A", "DRB1")
• infer_mhc_class(allele) — "I" or "II"

mhcseqs.species

Species normalization:

• normalize_species(raw) — 29-class fine-grained
• normalize_mhc_species(raw) — 7-class category
• get_latin_name(raw) — canonical Latin name
• get_canonical_prefix(raw) — MHC naming prefix
• LATIN_NAMES, CANONICAL_MHC_PREFIXES — lookup dicts

mhcseqs.pipeline

Two-step build pipeline:

• build_raw_index(fasta_paths, out_csv) — Step 1: parse FASTA → raw CSV
• build_full_seqs(raw_csv, out_csv) — Step 2: select representatives + extract grooves

mhcseqs.validate

Post-build sanity checks:

• validate_build(raw_csv, full_csv) — run all checks
• format_validation_report(warnings, stats) — human-readable report

mhcseqs.download

FASTA source downloading:

• download_all(dest_dir) — download IMGT/HLA + IPD-MHC
• SOURCES — dict of source URLs and metadata

Generated by mhcseqs. Apache License 2.0.