mhctools
One Python interface to ~30 MHC binding, presentation, immunogenicity, and antigen-processing predictors.
Each predictor has its own input format, output format, allele spelling, and
installation ritual. mhctools gives them all the same predict() call and the
same result objects, so swapping NetMHCpan for MHCflurry is a one-line change
and comparing them is a DataFrame. Everything runs locally.
Documentation: https://openvax.github.io/mhctools/
Install and predict
pip install mhctools
mhctools fetch mhcflurry # MHCflurry ships as a dependency; this downloads its weights
from mhctools import MHCflurry
predictor = MHCflurry(alleles=["HLA-A*02:01", "HLA-B*07:02"])
results = predictor.predict(["SIINFEKL", "GILGFVFTL"])
for r in results:
if r.affinity:
print(f"{r.peptide} -> {r.affinity.allele} IC50={r.affinity.value:.1f}nM")
That is the whole pattern. predict() returns one PeptideResult per input
peptide, in input order. Each exposes an accessor per kind of prediction
(r.affinity, r.presentation, r.immunogenicity, ...) that is None when
the predictor does not produce that kind. Scan proteins with
predict_proteins(), and get a pandas DataFrame from any *_dataframe() method.
See results and DataFrames.
Calis needs no download at all; most predictors need model weights or an
external tool first (see below). The command line does the same job:
mhctools --sequence SIINFEKL SIINFEKLQ --mhc-predictor mhcflurry --mhc-alleles A0201
Which predictor?
| I want to predict… | Kind | Predictors |
|---|---|---|
| Binding affinity to an allele | pMHC_affinity |
NetMHCpan, NetMHC, NetMHCIIpan, NetMHCcons, MHCflurry, CapHLA, SMM, SMMPMBEC |
| Surface presentation | pMHC_presentation |
NetMHCpan41/42, NetMHCIIpan, MHCflurry, CapHLA, MixMHCpred (I), MixMHC2pred (II), BigMHC |
| How long the pMHC complex lasts | pMHC_stability |
NetMHCstabpan |
| Combined antigen processing | antigen_processing |
MHCflurry |
| Proteasomal cleavage | proteasome_cleavage |
Pepsickle, NetChop, NetCleave_I |
| Endolysosomal cleavage (class II) | endolysosomal_cleavage |
NetCleave_II |
| TAP transport into the ER | tap_transport |
DeepTAP |
| ERAP1 N-terminal trimming | erap_trimming |
ERAMER |
| Whether a T cell responds | immunogenicity |
Calis, PRIME, BigMHC_IM, DeepImmuno, TLimmuno2 (II) |
| Whether a specific TCR recognises it | pMHC_TCR_binding |
NetTCR, Tulip, MixTCRpred |
| How long the free peptide survives | peptide_half_life |
PeptiVerse, PlifePred2 |
| Which peptidase cuts which bond | none | cleavage API |
- Predictor matrix: every predictor, class, command-line name, input, install route and license on one page.
- Choosing a predictor and known limits. Several of these models are weaker than their own papers suggest; read the limits before you trust a score.
RandomBindingPredictor is built in and produces random affinities, which is
occasionally useful as a null baseline.
Getting models
Most predictors need something downloaded first, with one command for all of it:
mhctools ls # what exists, where it lives, who manages it
mhctools fetch mhcflurry # get it
mhctools predictors # can it actually run?
fetch is idempotent. Academic-licensed tools need an explicit
--accept-license, and the DTU NetMHC family needs a license you request from
DTU directly. See getting models
and licensing.
Beyond peptide-MHC
- Per-bond peptidase evidence, including contextual batches for epitopes with flanks and complete vaccine constructs under tumor, APC and extracellular scenarios.
- Route-aware vaccine reports:
mhctools vaccine-reportwrites a sequence-centered PDF with route policies and checksums. - Assay-aware benchmarks:
mhctools benchmarkevaluates source-linked observations with training-overlap reporting. - Peptide PK, uptake and exposure result kinds.
Documentation
| Start here | |
|---|---|
| Command line | Every mhctools subcommand |
| Results and DataFrames | PeptideResult, Prediction, columns |
| Recipes | Scan proteins, many genotypes, annotate a table |
| Allele names | Accepted spellings and errors |
| Troubleshooting | Common failures |
| Migration guide | Old names and what replaced them |
Development
./develop.sh # editable install
./lint.sh # ruff
./test.sh # pytest
See the testing guide for a complete run with no skipped tests. Releases are described in RELEASING.md.
5 maintainers
Metadata
5 maintainers
Release files for mhctools 3.46.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mhctools-3.46.2.tar.gz | 541.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mhctools-3.46.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 855.4 kB
Release files / mhctools-3.46.2.tar.gz
| Download URL | mhctools-3.46.2.tar.gz |
|---|---|
| Size | 541.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69307c82607776fc37a3a4f20cdf22899462547856084e063ab4ca69bfe4f9ef
|
|
BLAKE2b-256 checksum How to use checksums |
9157da6f121aab8c0cf64dfa700fef9a7d3ed03f7e61953723a844f2b9a5af9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
Release files / mhctools-3.46.2-py3-none-any.whl
| Download URL | mhctools-3.46.2-py3-none-any.whl |
|---|---|
| Size | 314.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
31c5a28fd49339a04c51b0625af364a2f300c99bd697da412f91066044af2798
|
|
BLAKE2b-256 checksum How to use checksums |
807dabfbfeaadedb466128ebd80f380e689cf31fa1ce4ed3af5eaf19f4f40198
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
