tsarina
Tsarina selects shared cancer immunotherapy targets for an individual patient or a population HLA panel.
It starts with reusable cancer-testis antigen (CTA), oncogenic-virus, and recurrent-mutation targets. It then combines tumor context, public immunopeptidomics evidence, healthy-tissue safety evidence, and predicted HLA presentation to produce ranked peptide-MHC (pMHC) candidates.
Workflows
| Goal | Entry point | Result |
|---|---|---|
| Prioritize targets for one patient | tsarina personalize or personalized_targets() |
Ranked CTA, viral, and mutant pMHCs for that patient's HLA type and tumor |
| Design an off-the-shelf CTA panel | tsarina panel |
CTA × HLA matrix with evidence tiers and population-coverage estimates |
| Assemble a shared CTA vaccine | tsarina vaccine |
Mortality-ranked proteoforms, sequence funnel, junction audit and DNA/RNA construct |
| Inspect public peptide observations | tsarina hits |
Cancer, healthy-tissue, and restriction evidence for specified peptides |
See: documentation — inputs, dataset setup and workflow details.
Install
Requires Python 3.10 or newer and OncoRef 1.23.1 or newer.
pip install tsarina
Install the optional peptide-generation and partitioning dependencies for full functionality:
pip install "tsarina[all]"
Quick start
Prioritize targets for a patient:
tsarina personalize \
--hla 'HLA-A*02:01,HLA-A*24:02,HLA-B*07:02' \
--cta 'MAGEA4=142.5,PRAME=87.3' \
--mutations "KRAS G12D" \
--viruses hpv16 \
--output patient-targets.csv
Build the default global CTA × HLA panel:
tsarina panel --format long --output panel.csv
Both workflows can use registered IEDB or CEDAR ligand exports as public immunopeptidomics evidence. See Data and evidence for setup and interpretation.
Target categories
| Category | Candidate source | Tumor-specific context |
|---|---|---|
| CTA | The current-policy oncoref CTA set | Tumor RNA expression and reproductive-tissue restriction |
| Viral | Proteomes from nine oncogenic viruses | Virus detected in the tumor |
| Mutant | Nineteen recurrent hotspots across seven driver genes | Matching mutation detected in the tumor |
Oncoref is the single authority for CTA membership, aliases, HPA restriction
calls, and proteoform groups. Tsarina adds downstream evidence and scoring
without maintaining a second CTA definition library. Default human membership
uses oncoref.cta_selection.results(); historical HPA annotations remain
available through CTA_hpa_evidence(). The exact boundary is
documented in CTA ownership and downstream evidence.
How ranking works
Target selection follows five stages:
- choose candidates from the relevant shared-target sets;
- enforce tumor context and exclude non-target human peptide matches;
- annotate public cancer and healthy-tissue MS observations;
- predict presentation by the requested HLA alleles; and
- rank pMHCs with explicit evidence and safety provenance.
Public MS evidence strengthens a candidate but does not redefine CTA membership. Healthy, direct-ex-vivo observations outside reproductive tissues and thymus are treated as safety evidence.
Documentation
- Documentation guide — workflow selection and shared concepts
- Personalized target selection — patient inputs, prioritization, and output schema
- CTA panel design — automatic selection, evidence tiers, HLA panels, and coverage
- CTA vaccine design — mortality-weighted p95 selection, current-policy selection, historical strict/loose comparisons, MS-supported stretches, construct search and full audit
- Canine evidence and DLA design — frozen dog inputs, independent-dog RNA prevalence, exact MS support and exploratory DLA constructs
- Data and evidence — data registry, observation classification, scoring, and naming
- CTA ownership and downstream evidence — oncoref/Tsarina responsibilities and maintenance
Development
./develop.sh
./format.sh
./lint.sh
./test.sh
develop.sh uses the active virtualenv (or creates .venv) and requires
pip >=23.0. It resolves Tsarina and present sibling checkouts together, checks
the proposed versions against installed consumers before changing packages,
and runs pip check after installation. If a checkout is incompatible, update
that checkout or use a separate virtualenv; the refused install leaves the
installed packages unchanged. Missing siblings use their released packages.
Real MHCflurry model integration tests run in a separate CI job. To run them locally (Python 3.10+):
pip install -e ".[test-mhcflurry]"
mhcflurry downloads fetch models_class1_presentation
pytest tests/test_mhcflurry_integration.py --run-mhcflurry
These tests check the downloaded presentation bundle, including its affinity
calibration, through Tsarina's scoring interface. Enabling them requires the
dependency and models; missing prerequisites fail rather than skip. Use
./test.sh --run-mhcflurry to include them in the full suite.
./deploy.sh requires this extra and model bundle and always runs these tests.
Metadata
Release files for tsarina 1.37.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tsarina-1.37.0.tar.gz | 2.1 MB | Without provenance | Details for tsarina-1.37.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tsarina-1.37.0-py3-none-any.whl | Python 3 | none | any | Details for tsarina-1.37.0-py3-none-any.whl |
Total release size: 2.8 MB
Release files / tsarina-1.37.0.tar.gz
| Download URL | tsarina-1.37.0.tar.gz |
|---|---|
| Size | 2.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4036e088c208af719161781d0e70200a1534980826cc178aba762cc3a12e0ec8
|
|
BLAKE2b-256 checksum How to use checksums |
cafa47f220fb5b6a528ab270a97e839ca323d1aee09d06389f68fcc1e64112e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
Release files / tsarina-1.37.0-py3-none-any.whl
| Download URL | tsarina-1.37.0-py3-none-any.whl |
|---|---|
| Size | 679.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3ed4a21cd82ebd71348e08ccec8f200c805b1a2bf6704086861e0627dc8742f3
|
|
BLAKE2b-256 checksum How to use checksums |
d0f0525a20ba05e5be8a26cfe90f3b794c1db976ce1f45df38ef0db0271d624d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
Security for tsarina 1.37.0
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.