mhctools 3.3.0

Python interface to MHC binding, presentation, immunogenicity, and antigen processing predictors

mhctools

Python interface to MHC binding, presentation, immunogenicity, and antigen processing predictors.

Installation

pip install mhctools

For MHCflurry support, also run:

mhcflurry-downloads fetch

Data model

Every predictor returns results as two nested dataclasses:

• PeptideResult — all predictions for one peptide (across alleles and prediction kinds). This is what you get back per peptide from predict().
• Pred — a single prediction: one peptide, one allele, one measurement kind (e.g. affinity, presentation, immunogenicity). Frozen and self-contained.

predict(["SIINFEKL", "GILGFVFTL"])
  → [PeptideResult, PeptideResult]
       └── .preds = (Pred(allele=A0201, kind=affinity, ...),
                     Pred(allele=A0201, kind=presentation, ...),
                     Pred(allele=B0702, kind=affinity, ...),
                     ...)

Both convert to DataFrames and have consistent column names for easy downstream analysis.

Quick start

from mhctools import NetMHCpan41

predictor = NetMHCpan41(alleles=["HLA-A*02:01", "HLA-B*07:02"])

# predict() returns a list of PeptideResult — one per peptide
results = predictor.predict(["SIINFEKL", "GILGFVFTL"])

for result in results:
    best = result.best_affinity
    if best:
        print(f"{best.peptide} -> {best.allele} IC50={best.value:.1f}nM")

Python API

Predicting peptides

from mhctools import NetMHCpan41

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

result = results[0]                   # PeptideResult for "SIINFEKL"
result.preds                          # tuple of Pred objects
result.best_affinity                  # Pred with highest affinity score
result.best_affinity.allele           # "HLA-A*02:01"
result.best_affinity.value            # IC50 in nM
result.best_affinity.score            # higher = better (~0-1)
result.best_affinity.percentile_rank  # lower = better (0-100)

result.best_affinity_by_rank          # Pred with lowest percentile rank
result.best_presentation              # best EL/presentation score
result.best_presentation_by_rank      # best EL percentile rank
result.best_stability                 # best pMHC stability (if available)
result.best_stability_by_rank

# filter by kind or allele
result.filter(kind=Kind.pMHC_affinity)
result.filter(allele="HLA-A*02:01")

NetMHCpan 4.1 automatically emits both pMHC_affinity and pMHC_presentation predictions per peptide-allele pair.

Scanning proteins

predict_proteins() takes a dictionary of protein sequences and returns {sequence_name: list[PeptideResult]}:

proteins = predictor.predict_proteins(
    {"TP53": "MEEPQSDPSVEPPLSQETFS...", "KRAS": "MTEYKLVVVGAGGVGKS..."},
    peptide_lengths=[9, 10],
)

for pp in proteins["TP53"]:
    best = pp.best_affinity
    if best and best.value < 500:
        print(f"  offset={best.offset} {best.peptide} IC50={best.value:.0f}")

DataFrames

Every level has a _dataframe variant that flattens to a pandas DataFrame with consistent columns:

df = predictor.predict_dataframe(["SIINFEKL"], sample_name="pat001")
df = predictor.predict_proteins_dataframe({"TP53": "MEEPQ..."}, sample_name="pat001")

Columns: sample_name, peptide, n_flank, c_flank, source_sequence_name, offset, predictor_name, predictor_version, allele, kind, score, value, percentile_rank.

Multi-sample predictions

MultiSample runs a predictor across multiple samples, each with its own HLA genotype:

from mhctools import MultiSample, NetMHCpan41

ms = MultiSample(
    samples={
        "pat001": ["HLA-A*02:01", "HLA-B*07:02"],
        "pat002": ["HLA-A*01:01", "HLA-B*08:01"],
    },
    predictor_class=NetMHCpan41,
)

# {sample_name: list[PeptideResult]}
results = ms.predict(["SIINFEKL", "GILGFVFTL"])

# {sample_name: {seq_name: list[PeptideResult]}}
protein_results = ms.predict_proteins({"TP53": "MEEPQ..."})

# flat DataFrames with sample_name column
df = ms.predict_dataframe(["SIINFEKL"])
df = ms.predict_proteins_dataframe({"TP53": "MEEPQ..."})

Measurement kinds

The Kind enum describes what biological quantity a Pred measures:

Kind	Meaning
pMHC_affinity	Peptide-MHC binding affinity
pMHC_presentation	Likelihood of surface presentation (EL/processing)
pMHC_stability	Peptide-MHC complex stability
immunogenicity	T-cell immunogenicity
antigen_processing	Combined processing score
proteasome_cleavage	Proteasomal cleavage score
tap_transport	TAP transport score (reserved, not yet used)
erap_trimming	ERAP trimming score (reserved, not yet used)

The Pred object

Every prediction is a frozen, self-contained Pred dataclass:

from mhctools import Pred, Kind

pred = Pred(
    kind=Kind.pMHC_affinity,
    score=0.85,           # ~0-1, higher = better
    peptide="SIINFEKL",
    allele="HLA-A*02:01",
    value=120.5,          # IC50 in nM
    percentile_rank=0.8,
    source_sequence_name="TP53",
    offset=42,
    predictor_name="netMHCpan",
    predictor_version="4.1",
)

score is always higher-is-better. value is in native units (nM for affinity, hours for stability). percentile_rank is always optional, 0-100, lower = stronger.

Supported predictors

MHC binding & presentation

Predictor	Kinds produced	Requires
NetMHCpan / NetMHCpan41 / NetMHCpan42	affinity + presentation	NetMHCpan
NetMHCpan4	affinity or presentation	NetMHCpan 4.0
NetMHCpan3 / NetMHCpan28	affinity	older NetMHCpan
NetMHC / NetMHC3 / NetMHC4	affinity	NetMHC
NetMHCIIpan / NetMHCIIpan43	affinity or presentation	NetMHCIIpan
NetMHCcons	affinity	NetMHCcons
NetMHCstabpan	stability	NetMHCstabpan
MHCflurry	affinity + presentation	pip install mhcflurry + mhcflurry-downloads fetch
BigMHC	presentation or immunogenicity	BigMHC clone (set BIGMHC_DIR)
MixMHCpred	presentation	MixMHCpred
IedbNetMHCpan / IedbSMM / IedbNetMHCIIpan	affinity	IEDB web API
RandomBindingPredictor	affinity	(built-in)

Antigen processing

Predictor	Kinds produced	Requires
Pepsickle	proteasome cleavage	pip install mhctools[pepsickle]
NetChop	proteasome cleavage	NetChop

Processing predictors use configurable scoring to aggregate per-position cleavage probabilities into peptide-level scores. See ProcessingPredictor and ProteasomePredictor for details.

Commandline examples

Prediction for user-supplied peptide sequences

mhctools --sequence SIINFEKL SIINFEKLQ --mhc-predictor netmhc --mhc-alleles A0201

Automatically extract peptides as subsequences of specified length

mhctools --sequence AAAQQQSIINFEKL --extract-subsequences --mhc-peptide-lengths 8-10 --mhc-predictor mhcflurry --mhc-alleles A0201

Legacy API

The old predict_peptides() and predict_subsequences() methods still work and return BindingPredictionCollection objects:

predictor = NetMHCpan(alleles=["A*02:01"])
collection = predictor.predict_subsequences(
    {"1L2Y": "NLYIQWLKDGGPSSGRPPPS"},
    peptide_lengths=[9],
)
df = collection.to_dataframe()

for bp in collection:
    if bp.affinity < 100:
        print("Strong binder: %s" % bp)

To convert legacy results to the new types:

preds = collection.to_preds()           # list of Pred
pp_list = collection.to_peptide_preds() # list of PeptideResult