Skip to main content

Tests Coverage Status PyPI

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 another pipeline's report, plus a list of MHC alleles; the output is a DataFrame (or CSV/HTML file) with one row per peptide, allele and prediction. It is used for personalized cancer vaccine design, viral epitope mapping and characterizing T-cell responses. In the openvax stack, Topiary runs MHC predictors through mhctools, translates variants with varcode and pyensembl, reads RNA evidence from isovar, and supplies the predictions and ranking expressions that vaxrank uses.

Install

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

pip install topiary

MHC predictors are installed separately and called through mhctools. MHCflurry installs with pip; its models are a separate download:

pip install mhcflurry
mhcflurry-downloads fetch

NetMHCpan and the other DTU tools need a license from DTU Health Tech. Variant annotation, gene lookups and SelfProteome need a local Ensembl annotation database:

pyensembl install --release 115 --species human

Isovar, PirlyGenes, OncoRef and WEIRDO are installed with Topiary; there are no extras to choose. Installation details covers other Ensembl releases and compatible package versions.

Quick start

Score two viral peptides against two HLA alleles with MHCflurry:

from mhctools import MHCflurry
from topiary import TopiaryPredictor

peptides = {"influenza_M1": "GILGFVFTL", "CMV_pp65": "TPRVTGGGAM"}
columns = ["peptide", "allele", "kind", "value", "score", "percentile_rank"]

predictor = TopiaryPredictor(
    models=[MHCflurry],
    alleles=["HLA-A*02:01", "HLA-B*07:02"],
)
df = predictor.predict_from_named_peptides(peptides)
print(df[columns].to_string(index=False))
   peptide      allele               kind        value    score  percentile_rank
 GILGFVFTL HLA-A*02:01      pMHC_affinity    25.841361 0.699441         0.130863
 GILGFVFTL HLA-B*07:02      pMHC_affinity 14185.201956 0.116437         8.844587
 GILGFVFTL HLA-A*02:01  pMHC_presentation          NaN 0.850049         0.193547
 GILGFVFTL             antigen_processing          NaN 0.175628              NaN
TPRVTGGGAM HLA-A*02:01      pMHC_affinity   556.503394 0.415730         1.541447
TPRVTGGGAM HLA-B*07:02      pMHC_affinity    14.428557 0.753303         0.003906
TPRVTGGGAM HLA-B*07:02  pMHC_presentation          NaN 0.941776         0.062445
TPRVTGGGAM             antigen_processing          NaN 0.300611              NaN

Each row is one peptide, allele and prediction kind. value is the raw prediction (IC50 in nM for binding affinity), score is higher-is-better and percentile_rank is lower-is-better. MHCflurry predicts affinity for each allele, presentation for the genotype (reported under its best allele) and antigen processing with no allele.

Pass filter_by=Affinity <= 500 (with from topiary import Affinity) to keep only the pairs predicted to bind at 500 nM or tighter, and sort_by= to rank them. Both take expressions that combine prediction fields, arithmetic, normalizing transforms and any DataFrame column; see the ranking DSL guide. To scan whole proteins with a sliding window, use predict_from_named_sequences; for varcode variants, use predict_from_variants.

Command line

The topiary command runs the same pipeline from variants, sequence files or gene names. This run translates KRAS G12D, scores the mutant peptides and keeps the binders (Ensembl data for --genome grch38 must be installed as above):

topiary \
  --variant 12 25245350 C T \
  --genome grch38 \
  --mhc-predictor mhcflurry \
  --mhc-alleles 'HLA-A*11:01,HLA-C*08:02' \
  --filter-by "affinity <= 500" \
  --only-novel-epitopes
  peptide      allele               kind      value    score  percentile_rank                      source_sequence_name
VVGADGVGK HLA-A*11:01      pMHC_affinity 126.927288 0.552337         0.505538 KRAS_p.G12D_chr12_g.25245350C_T__567b9678
VVGADGVGK HLA-A*11:01  pMHC_presentation        NaN 0.727242         0.375163 KRAS_p.G12D_chr12_g.25245350C_T__567b9678
VVGADGVGK             antigen_processing        NaN 0.465049              NaN KRAS_p.G12D_chr12_g.25245350C_T__567b9678
GADGVGKSA HLA-C*08:02      pMHC_affinity 108.830353 0.566554         0.282237 KRAS_p.G12D_chr12_g.25245350C_T__567b9678
GADGVGKSA HLA-C*08:02  pMHC_presentation        NaN 0.534686         0.686717 KRAS_p.G12D_chr12_g.25245350C_T__567b9678
GADGVGKSA             antigen_processing        NaN 0.215621              NaN KRAS_p.G12D_chr12_g.25245350C_T__567b9678
6 prediction rows (2 unique peptides, 2 named alleles)

--vcf, --maf, --fasta, --peptide-csv and --gene-names select other inputs, and --output-csv results.csv saves every row instead of printing a preview. The command-line guide lists predictor names, input modes, output columns and exit status.

Documentation

The full documentation is at openvax.github.io/topiary. In reading order:

  1. Quickstart: protein scans, input files, Ensembl and tissue lookups, multiple models.
  2. Command-line interface: predictor names, input modes, output columns, exit status.
  3. Ranking DSL: filter and ranking expressions in Python and as strings.
  4. Protein fragments: one antigen record for variants, fusions, ERVs, CTAs, viral and synthetic sources.
  5. Cached predictions: replay stored scores instead of calling a predictor.
  6. API reference: classes, functions and complete column lists.

Other guides cover RNA expression, peptide properties, cross-reactivity, structural-variant evidence reports, reading pVACseq, LENS and Exacto reports, and combining those sources with fresh predictions in one ranking.

Development

./develop.sh                          # editable install (uses uv)
pip install -r requirements-dev.txt   # lint, test and docs tools
./lint.sh
./test.sh                             # full suite: needs Ensembl data and predictors
python -m pytest tests --collect-only # collecting loads no Ensembl data or predictors
./test.sh -m isovar --strict-markers  # synthetic Isovar tests, no Ensembl download
mkdocs build --strict                 # docs site

Every pull request bumps __version__ in topiary/__init__.py and adds a CHANGELOG entry; RELEASING.md describes the release steps.

License

Apache License 2.0. See LICENSE.

Metadata

Release files for topiary 5.111.3

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

Source distribution (sdist)

Source distribution for topiary 5.111.3
File Size Uploaded Provenance Actions
topiary-5.111.3.tar.gz 2.6 MB Without provenance Details for topiary-5.111.3.tar.gz

Built distribution (wheel)

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

Total release size: 3.0 MB

Release files / topiary-5.111.3.tar.gz

Download URL topiary-5.111.3.tar.gz
Size 2.6 MB
Tags Source
SHA-256 checksum
How to use checksums
07c917c5fd6bcb875cdd5f099f4d9a0ae792c866419ba2b548e3c9688631a88d
BLAKE2b-256 checksum
How to use checksums
39811a2d1e03946544f5b4fb508743ae0a3d5ae439a7ceb90a92102d8c211fdf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / topiary-5.111.3-py3-none-any.whl

Download URL topiary-5.111.3-py3-none-any.whl
Size 403.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
946eb8ed4c6ef346a78e0f8556f1690ba1d528b8503e4abdf92d7d4bd46f5e6a
BLAKE2b-256 checksum
How to use checksums
6d142abe05bcee9ad49465c02e78924f572d593e94da760e07378feeaca50d93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for topiary 5.111.3

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

5.111.3 This release

2 release files No provenance

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