oncoref

oncoref is the base-layer package for shared cancer reference data: cancer-type ontology, cohorts, expression, clean transcripts-per-million (TPM) normalization, tumor mutational burden (TMB), incidence/mortality, immune-checkpoint inhibitor (ICI) response, Human Protein Atlas (HPA) normal-tissue expression, and HPA-derived cancer-testis antigen references.

Downstream packages such as pirlygenes and trufflepig should delegate parity-clean shared primitives here, but they keep different kinds of work: pirlygenes owns curated gene sets and panels, while trufflepig owns per-sample interpretation, quality-control (QC) narration, and rule firing.

Use this page as the quick orientation. The API guide is the detailed module map, with examples and notes about compatibility modules.

Install

pip install oncoref

Stack Boundary

  • oncoref: empirical base facts and canonical identifiers. Use it for cancer codes, gene IDs, reference expression/normalization, epidemiology, TMB, ICI/anti-PD-1 response, HPA normal tissue, and source-anchored cancer-testis antigen (CTA) facts. If a row has an n, confidence interval, source cohort, or PMID/DOI anchoring a measurement, it usually belongs here.
  • pirlygenes: curated gene selections. Use it for lineage/family/compartment panels, discriminators, surfaceome, TME and stem-cell markers, response signature panels, target-to-therapy registries, and other purpose-specific gene sets keyed to oncoref IDs.
  • trufflepig: per-sample application. Use it for sample QC narration, library-prep/source warnings, deconvolution, scoring, and tumor-sample rules.

Data Model

Three distinctions keep oncoref results interpretable:

  1. A cancer ontology code, an expression cohort, and a clinical evidence scope are related but not interchangeable. Registry fields state whether a code has its own cohort, a computed member union, a parent fallback, or no expression backing.
  2. Small reference and provenance tables ship in the Python wheel. Large expression matrices and HPA datasets live in versioned download caches.
  3. Availability and eligibility are explicit. Accessors distinguish a missing artifact, a QC-ineligible reference, and a valid empty gene selection.

Public results use canonical cancer codes and Ensembl gene IDs so downstream packages can join domains without maintaining private name mappings.

Start Here

  • Need cancer-type codes, hierarchy, molecular subtypes, or matched normal tissues? Start with Cancer Vocabulary.
  • Need expression values or clean-TPM normalization? Start with Expression And Normalization.
  • Need anti-PD-1 or broader checkpoint-inhibitor response estimates? Start with ICI Response.
  • Need cancer-testis antigen definitions, patient coverage, or CTA-specific peptide load? Start with CTA Antigens.
from oncoref import cancer_ontology, ici_response

crc_msi = cancer_ontology.cancer_type_records(subtype_group="MSI", under="CRC")
crc_msi[["code", "parent_code", "ontology_level", "ontology_kind", "evidence_source_code"]]

# Mismatch repair (MMR) / microsatellite instability (MSI) queries keep
# positive, negative, and confounder classes explicit.
cancer_ontology.mmrd_cancer_codes(expression_only=True)
cancer_ontology.mmr_confounder_cancer_codes()

ici_response.best_available_ici_response("COAD_MSI")

Data Domains

Domain Public modules Use for
Cancer vocabulary oncoref.cancer_ontology, oncoref.cohorts Registry records, aliases, hierarchy, subtype axes, reference-source backing, MMR/MSI classifier status, cohort IDs, matched normal tissues
ICI response oncoref.ici_response Anti-PD-1 and broader ICI references, regimen-aware lookups, extracted endpoint estimates
CTA references oncoref.cta, oncoref.cta_coverage, oncoref.cta_peptides HPA-derived CTA facts, patient coverage, CTA-specific 9-mer counts and load
Antigen panels oncoref.antigen_coverage Coverage calculations for caller-supplied non-CTA gene lists
Expression oncoref.expression, oncoref.expression_builders Source-matrix ingestion, per-sample accessors, percentiles, representatives, within-sample summaries, and reference-expression accessors
Normalization oncoref.normalization, oncoref.gene_families Clean TPM, housekeeping normalization, technical-RNA filtering, normalization/QC reference families
Genes and proteoforms oncoref.gene_ids, oncoref.genome, oncoref.proteoforms Gene ID resolution, Ensembl lookup, proteoform grouping
Other references oncoref.tmb, oncoref.incidence, oncoref.fusions TMB, incidence/mortality burden, defining fusions
Legacy compatibility oncoref.response_signatures Transitional historical response-signature surface; new or extended therapy-signature panels belong in pirlygenes
Data management oncoref.catalog, oncoref.data_bundle, oncoref.reference_data, oncoref.hpa Dataset inventory, download/cache status, HPA reference data