Skip to content

Topiary

Predict which peptides from protein sequences will be presented by MHC molecules, making them potential T-cell epitopes. Used in cancer immunotherapy research to find mutant peptides (neoantigens) that the immune system could target.

Core idea: Given protein sequences + HLA alleles + one or more MHC prediction models, Topiary scans all possible peptides and returns those predicted to be presented by MHC, ranked by any combination of binding affinity, presentation score, processing score, and stability.

Features

  • Multiple MHC prediction models — NetMHCpan, MHCflurry, NetMHCIIpan, etc. via mhctools; combine and rank across models
  • Composable ranking DSL — filter, rank, and score with operator expressions over affinity, presentation, stability, wildtype comparisons, and peptide properties
  • Universal antigen abstraction — ProteinFragment runs somatic variants, fusions, ERVs, CTAs, viral, and synthetic antigens through one pipeline
  • Cached predictions — CachedPredictor reuses pre-computed scores (mhctools output, NetMHC stdout, generic TSV) so you can iterate on filters and ranking without re-running the predictor
  • Multiple input modes — VCF/MAF variants, FASTA, CSV, gene names, LENS reports, pVACseq output
  • Expression- and tissue-aware prioritization — exclude peptides from vital-organ proteomes, prioritize by RNA expression

Quick example

Score the PRAME cancer-testis antigen against two HLA class I alleles, keeping strong binders and presentation hits and sorting by presentation score:

from topiary import TopiaryPredictor
from mhctools import NetMHCpan

PRAME = (
    "MERRRLWGSIQSRYISMSVWTSPRRLVELAGQSLLKDEALAIAALELLPRELFPPLFMAA"
    "FDGRHSQTLKAMVQAWPFTCLPLGVLMKGQHLHLETFKAVLDGLDVLLAQEVRPRRWKLQ"
    "VLDLRKNSHQDFWTVWSGNRASLYSFPEPEAAQPMTKKRKVDGLSTEAEQPFIPVEVLVD"
    "LFLKEGACDELFSYLIEKVKRKKNVLRLCCKKLKIFAMPMQDIKMILKMVQLDSIEDLEV"
    "TCTWKLPTLAKFSPYLGQMINLRRLLLSHIHASSYISPEKEEQYIAQFTSQFLSLQCLQA"
    "LYVDSLFFLRGRLDQLLRHVMNPLETLSITNCRLSEGDVMHLSQSPSVSQLSVLSLSGVM"
    "LTDVSPEPLQALLERASATLQDLVFDECGITDDQLLALLPSLSHCSQLTTLSFYGNSISI"
    "SALQSLLQHLIGLSNLTHVLYPVPLESYEDIHGTLHLERLAYLHARLRELLCELGRPSMV"
    "WLSANPCPHCGDRTFYDPEPILCPCFMPN"
)

predictor = TopiaryPredictor(
    models=NetMHCpan,
    alleles=["HLA-A*02:01", "HLA-B*07:02"],
    filter_by="affinity <= 500 | el.rank <= 2",
    sort_by="el.score",
)

df = predictor.predict_from_named_sequences({"PRAME": PRAME})

Installation

Requires Python ≥ 3.10. Osteosarc, including its read-extraction dependency, is installed with Topiary.

pip install topiary

For Ensembl-based features (variant annotation, gene lookups, SelfProteome), install the default reference selected by PyEnsembl:

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

If you install a different release, select it explicitly with release= or --ensembl-release; installing it does not change the default.

For cancer-testis antigen and tissue expression features:

pip install 'topiary[pirlygenes]'

For RNA-assembled protein fragments from Isovar:

pip install 'topiary[isovar]'

See the Quickstart for more examples, Protein Fragments for the universal antigen abstraction, Cached Predictions for running from pre-computed scores, Ranking DSL for the expression system, and API Reference for full details.