Skip to main content

CI PyPI Python versions Docs

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 the data subcommands
  • Python API: AlleleRecord fields, 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-proteins record 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)

Source distribution for mhcseqs 2.6.18
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)

Table of built distributions (wheels) for mhcseqs 2.6.18
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

2.6.18 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page