mhcgnomes: Parsing MHC nomenclature in the wild

MHCgnomes is a parsing library for multi-species MHC nomenclature which aims to correctly parse every name in IEDB, IMGT/HLA, IPD/MHC, and the allele lists for both NetMHCpan and NetMHCIIpan predictors. This allows for standardization between immune databases and tools, which often use different naming conventions.

It is the allele-naming layer of the openvax stack: mhctools, mhcflurry and mhcseqs all normalize allele names through it rather than parsing strings themselves.

Install

pip install mhcgnomes

Requires Python 3.11 or later. There are no MHC data downloads: the curated species and gene ontology ships with the package.

Quick start

>>> import mhcgnomes
>>> [mhcgnomes.parse(s).to_string() for s in ["A*02:01", "HLA-A0201", "hla-a:02:01"]]
['HLA-A*02:01', 'HLA-A*02:01', 'HLA-A*02:01']
>>> mhcgnomes.parse("DQ2.5").to_string()
'HLA-DQA1*05:01/DQB1*02:01'
>>> type(mhcgnomes.parse("HLA-A2")).__name__
'Serotype'
>>> mhcgnomes.parse("H2-Kk").to_string()
'H2-K*k'

parse returns a structured object, not a string: an Allele, Gene, Pair, Serotype, Haplotype, MhcClass or Species, depending on how much the input actually specified. to_string() gives the normalized spelling and compact_string() the short one:

>>> mhcgnomes.parse("HLA-A0201")
Allele(gene=Gene(species=Species(name='Homo sapiens', mhc_prefix='HLA'), name='A', mutations=()), allele_fields=('02', '01'), annotations=(), mutations=())
>>> mhcgnomes.parse("HLA-A0201").compact_string()
'A0201'

Pass raise_on_error=False to get None instead of a ParseError, and required_result_types= to say which of those types you will accept. Both matter when the input is not a curated allele list; see parsing untrusted input.

Command line

mhcgnomes "HLA-A*02:01" "DQ2.5"

This prints one row per input with the parsed result type, the normalized and compact forms, species, gene, MHC class, and the parsed properties from to_record(). --format tsv and --format json give machine-readable output, --strict exits non-zero on the first parse error, and mhcgnomes data manages the pinned external IMGT/IPD files. The command-line guide shows the full output of each.

Documentation

Full documentation: pirl-unc.github.io/mhcgnomes.

• MHC nomenclature in the wild: why one allele has a dozen spellings, and what the other named entities are
• Parsing guide: result types, untrusted input, species inference, species= vs default_species=
• Command line
• Species and gene ontology: the species tree, prefix tiers and provenance, gene classes
• Curation guide: where new species, genes and aliases go
• Immutable data objects and the release process

Development

./develop.sh   # create .venv and install the package with dev and docs extras
./format.sh    # ruff format
./lint.sh      # ruff check and ruff format --check
./test.sh      # pytest with coverage, worker count capped by free RAM and CPUs

Every pull request bumps mhcgnomes/version.py; see the release process (source) for how a merged version reaches PyPI.

Raw IPD-IMGT/HLA and IPD-MHC snapshots are not committed or bundled in releases. See External IMGT/IPD data for checksum-pinned downloads, local/CI caches, optional mirrors, offline use, and alias regeneration.

To work on the documentation site:

./develop.sh
mkdocs serve
mkdocs build --strict

License

Apache License 2.0.