Metadata-Version: 2.4
Name: panelbc
Version: 1.1.0
Summary: Focus-anchored minimal breast-cancer prognostic panel (ICMR Objective 3)
Author: Authors withheld
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: lifelines
Requires-Dist: psutil
Provides-Extra: full
Requires-Dist: scikit-survival; extra == "full"
Requires-Dist: xgboost; extra == "full"
Requires-Dist: lightgbm; extra == "full"
Requires-Dist: shap; extra == "full"
Requires-Dist: statsmodels; extra == "full"
Requires-Dist: matplotlib; extra == "full"
Requires-Dist: seaborn; extra == "full"
Provides-Extra: deep
Requires-Dist: torch; extra == "deep"
Dynamic: license-file

# panelbc — Focus-Anchored Breast-Cancer Prognostic Panel

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A minimal, cheap, multiply-validated breast-cancer prognostic gene panel and the code that produced it.
**ICMR grant IIRPSG-2024-01-02447**, Objective 3.

Starting from a mechanistically-defined protein complex (**EEF1A2, IQGAP1, IQGAP2, FRG1**), an unbiased
genome-wide, leakage-free search yields a **7- or 9-gene panel** that matches or beats the 50-gene PAM50
signature at a fraction of the genes, validated across **four independent cohorts on three continents**
(TCGA, METABRIC, SCAN-B, GSE20685; ~6,800 patients).

| Panel             | Genes                                            | External C-index (LOCO) |
| ----------------- | ------------------------------------------------ | ----------------------- |
| **7-gene**  | IQGAP1, IQGAP2, EEF1A2, FRG1, FLT3, CLIC6, SUSD3 | 0.65                    |
| **9-gene**  | + ZIC2, P4HA2                                    | 0.67                    |
| PAM50 (reference) | 50 genes                                         | 0.63                    |

> **Scientific note.** The predictive signal is carried by the *discovered* genes (FLT3, CLIC6, SUSD3,
> ZIC2, P4HA2); the four complex genes are near-random as predictors on their own (C≈0.54) and are
> retained as the biological anchor and discovery scaffold, not as predictive features. See `docs/`.

## Install

```bash
pip install -e .            # core scoring (numpy/pandas/scipy/scikit-learn/lifelines)
pip install -e ".[full]"    # + reproduction dependencies (xgboost, shap, sksurv, ...)
pip install -e ".[deep]"    # + torch for the deep-learning stage
```

## Quick start — score your own cohort

```python
import pandas as pd, panelbc
expr = pd.read_csv("my_expression.csv", index_col=0)   # samples x genes (any scale)
scores = panelbc.risk_score(expr, panel="9gene")       # higher = higher risk
groups = panelbc.risk_group(expr, panel="9gene")       # Low / Intermediate / High
```

or from the command line:

```bash
python scripts/predict.py --expr my_expression.csv --panel 9gene --out scores.csv
```

## Reproduce the headline benchmark

With the cohort checkpoints in `data/` (see [docs/DATA.md](docs/DATA.md)):

```bash
python scripts/reproduce.py
# model           TCGA  METABRIC  SCAN-B    MEAN
# 7-gene         0.678     0.608   0.676   0.654
# 9-gene         0.710     0.617   0.688   0.671
# focus-only     0.569     0.532   0.516   0.539
```

## Repository layout

```
panelbc/            installable package: locked panel defs (panels.json) + scoring
scripts/            predict.py (score a CSV), reproduce.py (headline benchmark)
analysis/           the 13 ordered stage scripts for the full study (01..13) + helpers
tests/              pytest suite (scoring correctness, direction, missing-gene handling)
docs/               DATA.md (how to obtain/rebuild cohort data), METHODS.md
requirements.txt    pip dependencies (core + extended tiers, with exact pins for reproduction)
pyproject.toml      installable package metadata (pip install -e .)
```

## Install

```bash
pip install -r requirements.txt     # dependencies
pip install -e .                    # the panelbc package + panelbc-predict CLI
pytest tests/ -q                    # 5 tests, should all pass
```

## The full analysis pipeline (`analysis/`)

Thirteen ordered stages documenting the complete study: dataset build (Aim I) -> transcriptional
cross-talk (Aim II) -> genome-wide gene discovery -> leakage-free forward selection ->
parsimony/cost frontier -> panel head-to-head -> deep learning (Phase II) -> 4th-cohort
validation -> statistical rigor (calibration/DCA/clinical-independence) -> tumor-vs-normal (Aim III)
-> (near-)exhaustive gene-set search -> KEGG pathway novelty -> immune-infiltration control.
Stages 11-13 are the extended analyses:

- **11_exhaustive_search.py** — numba-JIT ridge-Cox engine; exhaustive enumeration of all 3-5 gene
  panels + wide-beam 6-10, anchored and free. Shows the best free panel contains zero focus genes
  at every size and plateaus at ~0.70.
- **12_pathway_novelty.py** — KEGG annotation of every panel gene; focus and discovered genes occupy
  disjoint pathway space (novel combination, not a known module). Requires NCBI + KEGG network access.
- **13_immune_control.py** — confirms the panel is not an immune-infiltration surrogate (risk-immune
  correlation ~0; immune adds nothing to C-index). Turnkey: runs from the six checkpoints.

These are the faithful record of what was computed in a persistent analysis kernel; stages 01-10 share
in-memory state and are meant to be read/run in order (see `analysis/helpers_reference.py` for the
shared functions), while 11-13 are more self-contained. The **installable `panelbc` package +
`scripts/`** are the turnkey, tested surface.

## Method summary

- Expression **z-scored within each cohort** before pooling — neutralises TPM/RSEM/microarray scale differences.
- Prognosis = penalised Cox; discrimination = Harrell's C-index.
- **Leakage-free**: survival-based gene selection done inside CV folds only.
- **External validation** = leave-one-cohort-out + a fully held-out 4th cohort.

## Data availability

All cohorts are public (cBioPortal, GEO). GDC/UCSC-Xena were unreachable in the original environment,
so TCGA RSEM was obtained from cBioPortal's PanCancer Atlas. See [docs/DATA.md](docs/DATA.md).

## Citation

See [CITATION.cff](CITATION.cff).

## License

MIT — see [LICENSE](LICENSE).
