Metadata-Version: 2.4
Name: oncoref
Version: 1.8.0
Summary: Curated cancer reference data: ontology, TMB, incidence/mortality, and expression
Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/pirl-unc/oncoref
Project-URL: Repository, https://github.com/pirl-unc/oncoref
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: pyarrow
Requires-Dist: PyYAML
Requires-Dist: pyensembl
Provides-Extra: plots
Requires-Dist: matplotlib; extra == "plots"
Requires-Dist: adjustText; extra == "plots"
Requires-Dist: matplotlib_venn>=1.0; extra == "plots"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: adjustText; extra == "dev"
Requires-Dist: matplotlib_venn>=1.0; extra == "dev"
Dynamic: license-file

# oncoref

[![Tests](https://github.com/pirl-unc/oncoref/actions/workflows/tests.yml/badge.svg)](https://github.com/pirl-unc/oncoref/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/oncoref.svg)](https://pypi.org/project/oncoref/)

Curated cancer reference data — cancer-type ontology, tumor mutational burden
(TMB), incidence/mortality, checkpoint-inhibitor (ICI) response, per-cohort RNA-seq expression,
and cancer-testis antigens — behind one small Python API, a data fetch/cache
CLI, and a set of reference plots.

## oncoref is the base layer

`oncoref` is **designed as the base layer** of the openvax/PIRL stack — the
intended single upstream **source of truth** for cancer reference data, meant to
become a shared dependency of
[pirlygenes](https://github.com/pirl-unc/pirlygenes),
[trufflepig](https://github.com/pirl-unc/trufflepig), and
[tsarina](https://github.com/pirl-unc/tsarina). Adoption is still in progress —
most of these don't depend on it yet. Architecturally it stays at the bottom: it
depends only on pandas / numpy / pyarrow / PyYAML, it **never imports its
consumers** (data and logic flow only downward), and it **owns** these
definitions rather than mirroring them from elsewhere.

Anything that needs to know about

- **gene expression of cancer samples** — per-cohort RNA-seq in a normalized,
  comparable space: summary stats, tail-weighted percentiles, and medoid/exemplar
  samples per cancer type/subtype;
- **HPA protein / RNA** normal-tissue expression;
- the **definition of cancer-testis antigens** — the HPA tissue-restriction call
  over the candidate list (HPA-only; no MS/peptide layer);
- the **ontology of cancer types** — codes, the parent/child hierarchy, subtypes,
  families, characteristic driver fusions, and the cross-cutting MSI/POLE/HPV
  groupings; and
- **checkpoint-inhibitor response rates** and **TMB** per cancer type

depends on `oncoref` — including `pirlygenes` (gene-set curation/analysis),
`tsarina` (personalized target selection), `hitlist` (panel selection),
`trufflepig` (sample classification), and anything else downstream.

Everything keys on the cancer-type registry. The small curated tables ship in the
wheel; the heavy per-cohort expression bundle downloads on first use from
oncoref's own GitHub Release.

## Install

```bash
pip install oncoref
```

## Python API

```python
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("LUAD_EGFR")                # 6.9  (inherited from LUAD)
od.cancer_burden("pancreas", metric="us_mortality_pct")
od.burden_category("SARC_OS")             # -> "bone_and_joint" (incidence/mortality bucket)
od.cancer_ici_response("SKCM")            # 42  (anti-PD-1 ORR %; fallback aPD-1 → aPD-L1 → combo)
od.cancer_ici_response("SKCM", regimen="PD-1+CTLA-4")   # 57.6  (pin a regimen)

# Cancer-testis antigens (HPA-derived tissue-restriction):
od.cta_gene_names()                       # expressed CTA symbols (MAGEA4, CT83, …)
od.cta_evidence()                         # full HPA restriction table

# 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)
```

### Domains

- **Ontology** — `cancer_type_registry`, `resolve_cancer_type`,
  `cancer_type_info`, `cancer_types_in_family`, `viral_status`, `fusion_status`,
  the cohort vocabulary (`cohort_registry`, `cohort_aggregates`).
- **TMB** — `cancer_tmb`, `cancer_tmb_df` (parent-chain inheritance).
- **Incidence / mortality** — `cancer_burden`, `burden_category` (ACS / GLOBOCAN).
- **Checkpoint response** — `cancer_ici_response` (ORR per type/regimen: anti-PD-1,
  anti-PD-L1, anti-PD-1+anti-CTLA-4), with `cancer_apd1_response` the PD-1 shortcut.
- **Expression** — `cohort_gene_percentiles`, `within_sample_top_fraction`,
  `representative_cohort_samples` over the lazy-downloaded per-cohort bundle.
- **Cancer-testis antigens** — `cta_gene_names`/`cta_gene_ids`, `cta_evidence`,
  `synthesize_restriction` (HPA-only tissue-restriction; MS evidence stays in the
  target-selection layer).
- **HPA normal tissue** — `hpa_rna_consensus`, `hpa_normal_tissue` (IHC),
  `hpa_single_cell`, and per-gene lookups (`gene_tissue_ntpm`,
  `gene_protein_tissues`, `gene_cell_type_ntpm`) over HPA v23, fetched on demand
  (`oncoref hpa fetch`).
- **Genome reference** — `canonical_gene_id_and_name`, `find_gene_id_by_name`,
  `find_gene_name_from_ensembl_{gene,transcript}_id`, `aggregate_gene_expression`
  (pyensembl-backed symbol ↔ Ensembl-ID resolution). pyensembl ships with the
  package, but resolution needs a downloaded human release once:
  `pyensembl install --release 111 --species homo_sapiens` (the accessors return
  `None` until then).
- **Peptides** — `cta_specific_9mer_counts`, `cta_specific_9mer_load` (per-cohort
  mean per-patient CTA-specific 9-mer load): 9-mers found in a CTA protein but in no
  non-CTA protein, enumerated from the reference proteome and cached per release.
- **Plots** (`pip install oncoref[plots]`) — `oncoref.plots.apd1_vs_tmb`,
  `apd1_orr_bars`, `incidence_vs_mortality`, the CTA/coverage figures, and
  `oncoref.cta_curation_plots.render`.

## CLI

```bash
oncoref cancer-type prostate     # registry info as JSON
oncoref tmb LUAD_EGFR            # 6.9
oncoref ici SKCM                # 42  (--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

# expression-bundle cache (per-cohort expression):
oncoref cache fetch             # download the ~340 MB bundle
oncoref cache status            # which bundle paths are cached (no download)
oncoref cache dir               # where the data bundle is cached
oncoref cache prune --yes       # delete stale version caches
oncoref hpa fetch               # download HPA reference data (RNA / IHC / single-cell)
oncoref version
```

## Development

```bash
./develop.sh   # editable install with dev extras
./format.sh    # ruff format
./lint.sh      # ruff check + format --check
./test.sh      # lint + pytest with coverage
```

## License

Apache 2.0.
