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.10 or newer.
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
Two optional extras add input sources: pip install 'topiary[pirlygenes]' for
cancer-testis antigens and tissue expression, and
pip install 'topiary[isovar]' for protein fragments assembled from RNA reads.
See installation details
for choosing a different Ensembl release and for the optional-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
| Guide | Covers |
|---|---|
| Quickstart | Input formats, Ensembl lookups, exclusion filtering, peptide-only models |
| Command-line interface | Predictor names, input modes, output columns, exit status |
| Ranking DSL | Filter and ranking expressions, multi-model disambiguation |
| Protein fragments | One antigen record for variants, fusions, ERVs, CTAs, viral and synthetic sources |
| RNA expression | Annotating predictions with Salmon, Kallisto, RSEM and other quantification |
| Cached predictions | Replaying stored scores instead of calling a predictor |
| Peptide properties | Charge, hydrophobicity, manufacturability and TCR-facing signals |
| Cross-reactivity | Nearest-self search and presentation evidence |
| Reading pVACseq, Exacto, combining sources | Importing other pipelines' reports and ranking them together |
| SV evidence reports | Complete structural-variant nomination inventories, including candidates with no recovered protein |
| API reference | Classes, functions and complete column lists |
Contributing
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
The synthetic Isovar integration tests need only the optional package:
pip install '.[isovar]' pytest pytest-cov pytest-xdist
./test.sh -m isovar --strict-markers
License
Apache License 2.0. See LICENSE.
5 maintainers
Metadata
5 maintainers
Release files for topiary 5.94.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| topiary-5.94.5.tar.gz | 2.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| topiary-5.94.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.9 MB
Release files / topiary-5.94.5.tar.gz
| Download URL | topiary-5.94.5.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a27788901f67cefaa5cd380df42ee76e2d8cafb441b2e46dde1a4f23e00693c0
|
|
BLAKE2b-256 checksum How to use checksums |
0a0c3cb2bf3e1bf320eb5948ae40cc82d4cae9ce74122b232b1d7df01eec53db
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
Release files / topiary-5.94.5-py3-none-any.whl
| Download URL | topiary-5.94.5-py3-none-any.whl |
|---|---|
| Size | 362.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
64dc4c4cdc4228b1cf02c680085809aba18dccd22d57023a3d801524dd23ec18
|
|
BLAKE2b-256 checksum How to use checksums |
7dcbd32b934ae88697202f4e69a148dec6a510bef1678d4bfe6e3048699b688d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
