mhcmatch — which neoantigens are presented, and which ones a T cell will see

Pure Python, no compiled extension beyond the seqtree search core. MHC-I and MHC-II, human and mouse. Every reference dataset is fetched from isalgo/pmhc_data on first use, so a fresh pip install runs every example here with no manual downloads.

pip install mhcmatch

# rank a donor's neoantigen candidates end to end
mhcmatch rank fasta candidates.fasta --alleles donor.alleles --cls mhc1 --tumor SKCM --out ranked.tsv

import mhcmatch

store = mhcmatch.Store.from_pmhc(tier="shortlist", species="human")  # auto-fetched, cached
store.restriction("NLVPMVATV", calibrated=True)   # ranked alleles + %rank / P(present) / band
store.binder_score("NLVPMVATV")                   # the single-number binder index
store.scan_protein(my_protein, cls="mhc1")        # which windows are presented

📖 Full documentation · Getting started · Command reference · The EPIC scorer · Notebooks

Pick your entry point

The fifteen things people actually come here to do. The CLI page has every command with every flag.

Four things that surprise people, and each is a link away from its detail:

• predict and rank fasta drop nothing by default. --rank-threshold takes sb / wb / none / a percentage, and the tiers are class-aware, because a bare number cannot be: 2.0 is the weak cut for class I and the strong cut for class II. On class II a flat 2.0 kept 0 of 56 scored pairs in testing — an empty table, returncode 0.
• Two whitelists, because they make two different claims. --keep-genes 'TP53,KRAS' keeps a candidate for its gene; --keep-epitopes builtin keeps it for being one of 23,299 assay-validated immunogenic peptides. Matched rows carry keep_reason, because a row kept for its gene is not evidence about its peptide. → CLI
• cassette and vector are two jobs, not two names. cassette chooses units and scores a finished construct; vector assembles one already chosen. One mhcmatch cassette verb hides the split on the CLI; the Python column above does not. → Designing a cassette
• predict and restriction are different axes. predict asks is it presented at all (the NetMHCpan %Rank_EL analogue); restriction asks which allele. A peptide can top one and not the other — NLVPMVATV is unambiguously A*02:01-restricted yet bands mid-pack against A*02:01's own ligands.

The shipped model

Expression, Presentation, Immunogenic Complementarity — four blocks, listed here in the order that spells the name:

The fit enters them presentation first — presentation, expression, physchem, corpus, which is the blocks list on the artifact itself — so a later block's coefficient is what that term is worth after the earlier ones. Read a coefficient against that order, not against the acronym.

One artifact per (cls, species, mode), and no fallback — asking for a cell that was never fitted raises rather than scoring it with a neighbour's coefficients.

Human class I is the cell this library is built around. Human class II is fitted on far fewer rows from far fewer assays and its AUROC says so; the mouse cells are thinner again, and mouse class II is the thinnest of all. Read a class-II or mouse number as a transfer that was checked, not as a second headline.

Two things the table does not show.

A ninth cell ships that is not a default. mhc2.human.neoantigen has a second fit carrying the three corpus terms, reached as rank.aggregate("mhc2", "human", variant="corpus"). It exists because the corpus block became computable at class II in 1.20.0 — the HLA Ligand Atlas gives 132,818 class-II peptides over 29 benign tissues, against the 27,987 of the class-II thymic fraction alone. It is not the default because computing it answered in the negative: on the same 1,112 rows all three coefficients span zero, C_corpus_thymus at +0.0170 (95 % CI −0.4944 to +0.3995, sign held in 53 % of resamples). At class II the corpus block adds nothing, and the six-term fit is what a class-II score should use. The same corpus rebuild is what made the mouse class-I cell fittable, where the block does carry.

mode="pathogen" is a supported surface, not an internal. Four cells are fitted on IEDB T-cell corpora whose negative class is "assayed and did not respond", which is a different question from the neoantigen cells' "nominated and did not respond" — so the two are not comparable term by term, and a pathogen cell drops expression outright, there being no host gene to measure. Reach them with --epitope pathogen. They also back the physicochemistry work, which is why the pathogen corpora are maintained alongside the neoantigen ones.

The AUROC column is three different protocols — do not read it down, and do not average it. Coefficients are deliberately not written here: they move with every refit, and this table quoted a superseded set for a full release each time it was maintained by hand. The record is docs/models.rst — every coefficient with its bootstrap interval, what each fit was trained on, how its AUROC was measured, and the caveats that come with each one, all generated from the artifacts on every docs build. Or ask the artifact:

mhcmatch models --all                 # which cells ship
mhcmatch rank --coefficients          # every term, its block, its coefficient
mhcmatch rank --holdout               # held-out AUROC, the grouped CVs, the corpus

Python

import mhcmatch
from mhcmatch import complement, expression, mimics, rank

store = mhcmatch.Store.from_pmhc(tier="shortlist", species="human")
store.decompose("NLVPMVATV")                         # anchor / TCR-facing split

aff = store.affinity_model("mhc1")
aff.predict_ic50("NLVPMVATV", "HLA-A*02:01")         # 18.9 nM (shortlist tier)
aff.amplitude("NLVPMVATL", "NLVPMVATV", "HLA-A*02:01")   # Kd_WT/Kd_MT (Łuksza eq. 9)

complement.score(peptides)                           # vectorised: pass the list, not a loop
complement.posterior(peptides, prior=4.2e-4)         # the log-odds carries NO prior; supply yours

rank.models()                                        # every shipped fit and its provenance
rank.aggregate("mhc1", "mouse")                      # the artifact itself

expression.gene_level("Trp53", species="mouse")      # FANTOM5 tissues + syngeneic models
mimics.neighbours(peptides, ref_sets, threads=0)     # threaded C++ neighbour search

pm = mhcmatch.Proteome.from_hf("human")
pm.find_sources(peptides, max_subs=1, threads=0)     # batch; find_source() is the single-query form
pm.wildtype("NLVPMVATV")                             # the WT counterpart, for agretopicity

Every one of these takes a list and returns one per input. Passing a list beats looping the single-query form by orders of magnitude — the batch call reaches C++ once with the GIL released. → Batch and threads

Advanced entry points — mimicry (signed per-component mimicry risk), portfolio (the over-dispersion and support machinery under cassette score), luksza (the published R term), recognition (the ESM head), calibrate, known, ligand, pseudoseq. → API reference

Install extras

The base install is seqtree, numpy and huggingface_hub. Every model that ships by default runs on it — torch is not required to score recognition, and asking for a head without its extra raises a named error rather than silently degrading.

mhcmatch bootstrap optionally pre-fetches the ligand panel (~16 MB) — it only decides when reference data is fetched, which matters on a compute node with no outbound network.

Deeper reading

Everything answering "why does it do that" rather than "how do I run it" is in README_EXT.md, so this page stays the length of a page:

Development

bash setup.sh            # repo-local .venv + editable install (uses a sibling ../seqtree if present)
bash setup.sh --tests    # + pytest
pytest -q

Theory and derivations are in the manuscript repo (latex_sn/, Methods and Supplementary Note 1); what is planned and in flight is in ROADMAP.md.