mhcseqs
Self-contained pipeline for downloading, curating, and extracting binding grooves from MHC (Major Histocompatibility Complex) protein sequences. Given an allele name it returns the full protein sequence together with an explicit structural decomposition: signal peptide, groove domains, Ig-fold support domain, and tail.
In the openvax stack it is the sequence layer beside mhcgnomes, which it uses for allele parsing, species provenance and gene classification. No alignment tools, BLAST, or structure databases are required.
Install
pip install mhcseqs
Requires Python 3.11 or later. The only required dependency is
mhcgnomes >= 3.41.0. The DataFrame
loaders also need pandas 3, which pip install "mhcseqs[pandas]" installs.
Quick start
Build the database once (downloads IMGT/HLA and IPD-MHC sources into
~/.cache/mhcseqs/), then look an allele up:
import mhcseqs
mhcseqs.build() # only needed once; returns a BuildPaths dataclass
r = mhcseqs.lookup("HLA-A*02:01")
print(r.allele, r.species_category, r.mhc_class, r.chain)
print("mature starts at", r.mature_start)
print("groove1", r.groove1)
print("architecture", r.domain_architecture)
HomoSapiens-A*02:01 human I alpha
mature starts at 24
groove1 GSHSMRYFFTSVSRPGRGEPRFIAVGYVDDTQFVRFDSDAASQRMEPRAPWIEQEGPEYWDGETRKVKAHSQTHRVDLGTLRGYYNQSEA
architecture signal_peptide>g_alpha1>g_alpha2>c1_alpha3>tail_linker>transmembrane>cytoplasmic_tail
lookup also takes IEDB-style mutations
(mhcseqs.lookup("HLA-A*02:01", mutations=["K66A", "D77S"])), and
load_sequences_dataframe() / load_sequences_dict() load the whole build at
once. See the Python API guide.
Command line
mhcseqs build # download sources and build CSVs
mhcseqs lookup "HLA-A*02:01" # print one allele's record
mhcseqs data list # cached downloads and built CSVs
mhcseqs data install mhc-proteins # versioned UniProt record dataset
mhcseqs <command> --help lists every option; the
command-line guide shows the output
of each.
Documentation
Full documentation: pirl-unc.github.io/mhcseqs.
- Command line:
build,lookup, and thedatasubcommands - Python API:
AlleleRecordfields, DataFrame loaders, allele and species utilities, module reference - Structural decomposition: the domain grammar, how the alignment-free parser scores a decomposition, groove status codes, literature basis
- Datasets and columns: what a build contains, column meanings, and the versioned
mhc-proteinsrecord layer
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 check and ruff format --check
To work on the documentation site:
pip install -e ".[docs]"
mkdocs serve
mkdocs build --strict
License
The mhcseqs code is licensed under
Apache 2.0. The independently
distributed UniProt-derived mhc-proteins data is licensed under
CC BY 4.0 with attribution to the
UniProt Consortium.
Metadata
Release files for mhcseqs 2.6.18
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mhcseqs-2.6.18.tar.gz | 1.6 MB | Without provenance | Details for mhcseqs-2.6.18.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mhcseqs-2.6.18-py3-none-any.whl | Python 3 | none | any | Details for mhcseqs-2.6.18-py3-none-any.whl |
Total release size: 3.2 MB
Release files / mhcseqs-2.6.18.tar.gz
| Download URL | mhcseqs-2.6.18.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a0ec120bf5ec37f74498fa0d4ee89ff34929f377b68662f7f2f812594707a6a7
|
|
BLAKE2b-256 checksum How to use checksums |
e0679da98a814ec9fbe337114ea45814148489482aeb4e106eb2789b0cc95cf6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / mhcseqs-2.6.18-py3-none-any.whl
| Download URL | mhcseqs-2.6.18-py3-none-any.whl |
|---|---|
| Size | 1.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36da66840a2a0d6f750d11ecd05b4df9fd8b23168c5534b01425894d41cf6af0
|
|
BLAKE2b-256 checksum How to use checksums |
501bb4577c519e587cfd5aacf2b531ff2b1192ab72bc6898aa0d1922a30e796e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for mhcseqs 2.6.18
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.