mhctools

mhctools is a Python library for running MHC binding, presentation, immunogenicity, and antigen-processing predictors. It provides a common interface to tools such as NetMHCpan and MHCflurry, with results you can inspect in Python or export as a pandas DataFrame.

In the openvax stack, mhctools is the predictor layer: it parses allele names with mhcgnomes, runs mhcflurry and external tools, and feeds epitope pipelines such as topiary and vaxrank.

Install

Requires Python 3.11 or later and pandas 3.x.

pip install mhctools
mhctools fetch mhcflurry

MHCflurry is installed with mhctools; the second command downloads its model weights. Most other predictors need model weights or an external installation. Use mhctools ls to locate models and mhctools predictors to check which can run. The installation guide explains downloads, optional backends, and licensing.

Quick start

from mhctools import MHCflurry

predictor = MHCflurry(alleles=["HLA-A*02:01", "HLA-B*07:02"])
results = predictor.predict(["SIINFEKL", "GILGFVFTL"])

for result in results:
    affinity = result.affinity
    if affinity is not None:
        print(result.peptide, affinity.allele, affinity.value)

SIINFEKL HLA-A*02:01 6249.062082358259
GILGFVFTL HLA-A*02:01 25.84136114436916

Each result corresponds to one input peptide. The affinity accessor selects the strongest prediction across alleles, with IC50 in nM. Use predict_dataframe() for a pandas table or predict_proteins() to scan protein sequences. See results and DataFrames.

Command line

mhctools is one executable. The bare command predicts for peptides or FASTA sequences and writes a tab-separated table to stdout:

mhctools --sequence SIINFEKL GILGFVFTL --mhc-predictor mhcflurry --mhc-alleles 'HLA-A*02:01'

source_sequence_name	offset	peptide	allele	score	affinity	percentile_rank	prediction_method_name	length
	0	SIINFEKL	HLA-A*02:01	0.192203	6249.06	7.96416	mhcflurry	8
	0	GILGFVFTL	HLA-A*02:01	0.699441	25.8414	0.130863	mhcflurry	9

Subcommands cover artifacts (ls, fetch, predictors), table annotation (predict-table), peptidase activity (cleavage, cleavenet), TCR scoring (mixtcrpred), vaccine modeling (vaccine-report, vaccine-trajectory, vaccine-windows, vaccine-compare) and evaluation (benchmark). Run mhctools --help to see commands and prediction options, or mhctools --version to identify the installed release.

Enable Bash/zsh tab completion for this shell:

eval "$(register-python-argcomplete mhctools)"

Alternatively, run activate-global-python-argcomplete once and start a new shell to enable completion for all participating OpenVax tools. See the command-line guide for details.

Documentation

Full documentation: openvax.github.io/mhctools.

• Getting started: first prediction, start here
• Choosing a predictor and known limits
• Predictor matrix: Python classes, CLI names, inputs, and installation routes
• Recipes: protein scans, multiple samples, and table annotation
• Command line and API reference
• Peptidase activity, vaccine reports, and benchmarks

Development

./develop.sh
./lint.sh
./test.sh

See the testing guide and release instructions.

License

Apache License 2.0.