Topiary

Topiary predicts which peptides from an antigen source are presented by a patient's MHC molecules, then filters and ranks them. Inputs are protein sequences, peptides, somatic variants or a pipeline's report, plus a list of HLA alleles; output is a DataFrame (or CSV/TSV/HTML) with one row per peptide-allele-prediction. Binding predictions come from mhctools models such as NetMHCpan and MHCflurry.

It is used for personalized cancer vaccine design, viral epitope mapping, and characterizing T-cell responses.

Documentation: openvax.github.io/topiary

Installation

Topiary requires Python 3.11 or newer and pandas 3.x (pandas>=3,<4).

pip install topiary

MHC binding predictors are installed separately and called through mhctools. MHCflurry installs with pip:

pip install mhcflurry && mhcflurry-downloads fetch

NetMHCpan and the other DTU tools require a license from DTU Health Tech.

Variant annotation, gene lookups and SelfProteome need a local Ensembl annotation database:

pyensembl install --release "$(python -c 'from pyensembl import ensembl_grch38; print(ensembl_grch38.release)')" --species human

The normal install includes Isovar for RNA-derived protein fragments, PirlyGenes and OncoRef for cancer-testis antigens and tissue expression, and WEIRDO for peptide foreignness. No installation extras are needed. See installation details for choosing a different Ensembl release and compatible package versions.

Predict binding for a few peptides

from topiary import TopiaryPredictor
from mhctools import NetMHCpan

predictor = TopiaryPredictor(
    models=[NetMHCpan],
    alleles=["HLA-A*02:01"],
)

df = predictor.predict_from_named_peptides({
    "peptide_1": "YLQLVFGIEV",
    "peptide_2": "LLFNILGGWV",
    "peptide_3": "GILGFVFTL",
})

Each row of df is one peptide, allele and prediction kind, with value (the raw prediction, IC50 in nM for binding affinity), score (normalized, higher is better) and percentile_rank (lower is better). Several models can run together — models=[NetMHCpan, MHCflurry] — and each contributes its own rows.

To scan whole proteins with a sliding window instead of scoring peptides as given, use predict_from_named_sequences({"BRAF": "MAALSGGGG..."}).

Predict from somatic variants

The CLI runs the same pipeline from a VCF, translating each variant, tiling peptides across the mutated region, and keeping only peptides that overlap it:

topiary \
  --vcf somatic.vcf \
  --mhc-predictor netmhcpan \
  --mhc-alleles HLA-A*02:01,HLA-B*07:02 \
  --filter-by "ba <= 500 | el.rank <= 2" \
  --only-novel-epitopes \
  --output-csv epitopes.csv

The equivalent Python call is predictor.predict_from_variants(variants) on a varcode variant collection.

Filter and rank

Filters and ranking expressions are written the same way in Python and as strings for the CLI:

from topiary import TopiaryPredictor, Affinity, Presentation
from mhctools import NetMHCpan

predictor = TopiaryPredictor(
    models=[NetMHCpan],
    alleles=["HLA-A*02:01"],
    filter_by=(Affinity <= 500) | (Presentation.rank <= 2.0),
    sort_by=Affinity.logistic(350, 150),
)

Affinity, Presentation, Stability and Processing each read a prediction kind, through .value, .rank or .score. Expressions combine with arithmetic and boolean operators, normalizing transforms, and any column in the DataFrame — RNA expression, peptide properties, custom annotations. The string forms (affinity <= 500 | el.rank <= 2) go to --filter-by and --sort-by. The ranking DSL guide has the full grammar.

Where to read more

Contributing

Install development tools with pip install -r requirements-dev.txt. Run ./lint.sh and ./test.sh before submitting changes. The full suite uses real Ensembl annotations and external MHC predictors; collecting tests does not load either:

python -m pytest tests --collect-only

Run the synthetic Isovar integration tests without downloading Ensembl data:

pip install . pytest pytest-cov pytest-xdist
./test.sh -m isovar --strict-markers

License

Apache License 2.0. See LICENSE.