Skip to main content

Tests PyPI Python versions License Docs

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.

Development

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

See the testing guide and release instructions.

License

Apache License 2.0.

Metadata

Release files for mhctools 4.9.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mhctools 4.9.6
File Size Uploaded Provenance Actions
mhctools-4.9.6.tar.gz 1.2 MB Without provenance Details for mhctools-4.9.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mhctools 4.9.6
File Interpreter ABI Platform Actions
mhctools-4.9.6-py3-none-any.whl Python 3 none any Details for mhctools-4.9.6-py3-none-any.whl

Total release size: 2.1 MB

Release files / mhctools-4.9.6.tar.gz

Download URL mhctools-4.9.6.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
546e70278bffd9fc48224597e43f1698018681999e76bfc3dbd9f6a642d8c7e3
BLAKE2b-256 checksum
How to use checksums
dcd742c384e9045eece8c6acc74c9781a78e6440eed735b9871476116c720b70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Release files / mhctools-4.9.6-py3-none-any.whl

Download URL mhctools-4.9.6-py3-none-any.whl
Size 901.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fd2edbc1068f39bcc93170a168557f5cdab4e0c93b4e68bca4c8027f86e3a37c
BLAKE2b-256 checksum
How to use checksums
be458634963302d6f6fd66591c1ec553f589514ee87ce433b50d36d5d1ad73ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Security for mhctools 4.9.6

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

4.9.6 This release

2 release files No provenance

0.0.0

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