oncoref
Curated cancer reference data — cancer-type ontology, tumor mutational burden (TMB), incidence/mortality, checkpoint-inhibitor (ICI) response, per-cohort RNA-seq expression, Human Protein Atlas (HPA) normal-tissue expression, and HPA-derived cancer-testis antigen references, plus matched CPTAC RNA/protein calibration sources — behind one small Python API, a data fetch/cache CLI, and a set of reference plots.
Role in the stack
The openvax/PIRL tools are split by ownership boundary, not by file format.
oncoref is the base layer: downstream packages can depend on it, but it never
imports its consumers.
- oncoref is the empirical base: what is true, measured, or canonically named
about cancer types, cohorts, genes, and reference datasets. It owns gene
identity and canonicalization, the cancer-type ontology/registry, expression
reference data and normalization, epidemiology, TMB, ICI/anti-PD-1 response, and
source-anchored cancer-testis antigen (CTA) facts. If a row has an
n, a confidence interval, a source cohort, or a PMID/DOI anchoring a measurement, it is usually an oncoref fact. - pirlygenes owns curated gene sets and panels: which genes are useful for a purpose. That includes lineage/family/compartment/supertype panels, discriminators, surfaceome, tumor microenvironment (TME) and stem-cell markers, response-signature panels, target-to-therapy registries, and other opinionated selections keyed to oncoref cancer codes and gene IDs. An empty set can be a valid pirlygenes answer.
- trufflepig owns per-sample interpretation: quality-control (QC) narration, library-prep/source warnings, deconvolution, scoring, and rule tables that fire against one tumor sample.
Adoption is staged: consumers can delegate parity-clean primitives while retaining their own curated artifacts and compatibility APIs. Shared facts and identifiers should be fixed here; purpose-specific panels and per-sample rules stay downstream.
Core model
- Canonical identities first. Cancer facts key on the cancer-type registry; expression cohorts and evidence scopes are explicit rather than inferred from names. Gene APIs resolve to a canonical Ensembl space.
- Small facts in the wheel, large matrices on demand. Ontology, gene, burden, response, and provenance tables install with the package. The large expression bundle and HPA datasets use versioned download caches.
- Provenance is part of the result. Reference rows expose source scope, sample counts, versions, and review status. Missing or ineligible data stays distinguishable from a valid empty result.
- Consumer policy stays downstream. oncoref exposes HPA-derived CTA calls and empirical expression facts; it does not turn them into therapy panels or one-sample decisions.
Install
pip install oncoref
Reference plotting is included in the standard installation. The pyensembl-backed genome integration remains optional because it also requires a separately installed Ensembl release:
pip install 'oncoref[genome]' # pyensembl-backed transcript and gene lookup
Quick start
The flat oncoref namespace remains available for compatibility and quick
interactive use. For new code, prefer the semantic submodules in
the API guide; they make it clearer
whether you are working with the cancer ontology, cohorts, ICI response, CTA
coverage, generic antigen-panel coverage, or CTA-specific peptides.
import oncoref as od
od.resolve_cancer_type("prostate") # -> "PRAD"
od.cancer_type_info("SARC_RMS_ARMS") # full registry record + burden + tmb
od.cancer_tmb("FL") # 5.05 (source-checked panel median)
od.cancer_burden("pancreas", metric="us_mortality_pct")
od.burden_category("SARC_OS") # -> "bone_and_joint" (incidence/mortality bucket)
od.cancer_ici_response("SKCM") # 43.7% in the selected trial setting
od.cancer_ici_response("SKCM", regimen="PD-1+CTLA-4") # 57.6 (pin a regimen)
od.therapy_benefit_toxicity_evidence(cancer_code="OV") # sourced clinical facts
od.rna_protein_calibrations(gene="TP53") # matched CPTAC cohort-specific models
od.rna_protein_hpa_priors(gene="TP53") # HPA normal-tissue RNA/IHC weak prior
# Cancer-testis antigens (HPA-derived tissue-restriction):
od.cta_gene_names() # expressed CTA symbols (MAGEA4, CT83, …)
od.cta_evidence() # full HPA restriction table
od.cta_clinical_target_evidence() # explicit clinical/canonical tier + leak flags
# Per-cohort expression percentiles (downloads the data bundle on first use):
od.cohort_gene_percentiles("PRAD") # per-gene p0…p100 vector (within-cohort)
od.within_sample_top_fraction("PRAD") # per-gene frac of samples top-5% (within-sample)
Domain map
| Question | Preferred modules |
|---|---|
| What does this cancer code mean? | oncoref.cancer_ontology, oncoref.cohorts |
| What expression reference is available? | oncoref.expression, oncoref.source_matrices |
| What matched RNA/protein calibration is available? | oncoref.rna_protein |
| What tumor-attributed or subtype summary is available? | oncoref.tumor_references |
| How is expression normalized or filtered? | oncoref.normalization, oncoref.gene_families |
| What is the canonical gene identity? | oncoref.gene_ids, oncoref.genome, oncoref.proteoforms |
| What is the TMB, burden, or ICI response evidence? | oncoref.tmb, oncoref.incidence, oncoref.ici_response |
| Which genes meet the HPA-derived CTA definition? | oncoref.cta, oncoref.cta_coverage, oncoref.cta_peptides |
| Where is a dataset cached or downloaded? | oncoref.catalog, oncoref.data_bundle, oncoref.hpa |
The API guide explains each domain, its provenance contract, and the distinction between reader, builder, and compatibility APIs.
Command line
See the TMB/ICI/aPD1 curation audit for corrected values, evidence gaps, and the complete row-by-row review ledger.
oncoref cancer-type prostate # registry info as JSON
oncoref tmb FL # 5.05
oncoref ici SKCM # 43.7 (--regimen to pin, --all-regimens to compare)
oncoref burden pancreas --metric us_mortality_pct
oncoref cta --count # number of expressed CTAs
oncoref plot apd1-vs-tmb --out apd1_vs_tmb.png
oncoref plot patient-coverage --gene-set cta --out coverage_out
oncoref plot cta-curation --out cta_curation_out
Data cache
oncoref data list # every wheel/bundle/HPA/source dataset
oncoref data status bundle # expression-bundle cache state (no download)
oncoref data metadata # package/data/cache/release contract JSON
oncoref data fetch bundle # download the large expression bundle
oncoref data fetch hpa # HPA RNA / immunohistochemistry / single-cell data
oncoref data dir bundle # where the data bundle is cached
oncoref data prune --yes # delete stale bundle version caches
oncoref version
Development
./develop.sh # create/refresh .venv and its editable install with dev extras
source .venv/bin/activate
oncoref version
./format.sh # ruff format
./lint.sh # ruff check + format --check
./test.sh # lint + the full pytest suite with coverage and two workers
The repository virtualenv is the canonical development CLI. It imports the
checkout directly, so source changes are visible without reinstalling; rerun
./develop.sh when dependencies or packaging metadata change. To use the same
CLI outside the checkout, add this shell alias rather than maintaining a
separate global pip installation:
alias oncoref=/absolute/path/to/oncoref/.venv/bin/oncoref
License
Apache 2.0.
1 maintainer
Release files for oncoref 1.8.196
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| oncoref-1.8.196.tar.gz | 13.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| oncoref-1.8.196-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 27.6 MB
Release files / oncoref-1.8.196.tar.gz
| Download URL | oncoref-1.8.196.tar.gz |
|---|---|
| Size | 13.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d50379caa67e9710c3ba59b36dc2013c5103354418b84f3fdf2a5e40462b76a2
|
|
BLAKE2b-256 checksum How to use checksums |
5205503947e8a57804e125304472939cdf99764c133cc8719f9fb0ecc4ea2157
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
Release files / oncoref-1.8.196-py3-none-any.whl
| Download URL | oncoref-1.8.196-py3-none-any.whl |
|---|---|
| Size | 13.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
29a7928d127e3ea57fb8f9a0921a96af1c6131bf853f8224d36afacd88c5a09e
|
|
BLAKE2b-256 checksum How to use checksums |
ead1e3205ae409c11e164673e4d917961dd86156a350d00f8f75d36585838e4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
