Skip to main content

tsarina

Tests PyPI

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:

  1. choose candidates from the relevant shared-target sets;
  2. enforce tumor context and exclude non-target human peptide matches;
  3. annotate public cancer and healthy-tissue MS observations;
  4. predict presentation by the requested HLA alleles; and
  5. 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

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.36.0

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

Source distribution (sdist)

Source distribution for tsarina 1.36.0
File Size Uploaded Provenance Actions
tsarina-1.36.0.tar.gz 2.1 MB Without provenance Details for tsarina-1.36.0.tar.gz

Built distribution (wheel)

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

Total release size: 2.8 MB

Release files / tsarina-1.36.0.tar.gz

Download URL tsarina-1.36.0.tar.gz
Size 2.1 MB
Tags Source
SHA-256 checksum
How to use checksums
b96a186ed72ad4afc8f681a9f6baaf970d020005f963cbf627f648468e8f263e
BLAKE2b-256 checksum
How to use checksums
0da67a860785af6dadf74553874a7ecacd11b02f20729c0518db81bd01c67293
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.36.0-py3-none-any.whl

Download URL tsarina-1.36.0-py3-none-any.whl
Size 678.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
537728ea2cb2d2a2d59b61d7a87e9264303ccdd1f423dca5f0ff517a0ae528eb
BLAKE2b-256 checksum
How to use checksums
d9a7bad1aa9a77381ce4f5409b1e66e7765cb7936f35668fb5a322ace7739c05
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.36.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.

Release history Release notifications | RSS feed

This release

1.36.0 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