bulkrna-survival
Survival analysis for bulk RNA-seq — Kaplan-Meier curves, Cox proportional hazards, expression-based patient stratification.
SKILL.mdSkills/bulkrna/bulkrna-survival/SKILL.md
GitHubBulk RNA-seq Survival Analysis
Expression-based survival analysis for clinical bulk RNA-seq datasets. Stratifies patients by gene expression (median split or optimal cutoff), generates Kaplan-Meier plots, computes log-rank tests, and fits Cox proportional hazards models.
Core Capabilities
- Median-split or optimal-cutoff patient stratification by gene expression
- Kaplan-Meier survival curves with confidence intervals
- Log-rank test for comparing survival between expression groups
- Cox proportional hazards regression (univariate and multivariate)
- Multi-gene signature scoring and survival association
- Forest plot of hazard ratios for multiple genes
Why This Exists
- Without it: Researchers must combine expression data with clinical metadata in R, use the
survival/survminerpackages, manually iterate over genes, and create separate plots — often requiring significant R expertise. - With it: A single Python command performs expression-stratified survival analysis with Kaplan-Meier curves, log-rank tests, and Cox regression from a count matrix and clinical metadata file.
- Why OmicsClaw: Pure Python implementation using
lifelines(optional) with built-in fallback to scipy-based log-rank, integrated into the OmicsClaw reporting framework.
Algorithm / Methodology
Kaplan-Meier Estimation
- Sort patients by event time
- Compute survival probability at each time point: S(t) = ∏(1 - d_i/n_i)
- Greenwood's formula for confidence intervals
Log-Rank Test
- Compare survival distributions between high/low expression groups
- Chi-square test statistic with 1 degree of freedom
Cox Proportional Hazards
- Model: h(t|x) = h₀(t) × exp(β₁x₁ + β₂x₂ + ...)
- Estimates hazard ratios and 95% confidence intervals
- Concordance index (C-index) for model assessment
Patient Stratification
- Median split: Divide at median expression value
- Optimal cutoff: Maximize log-rank statistic across all possible cutpoints
Landmark Survival
When median survival is not reached (KM curve never crosses 50%), landmark survival rates are more robust. The system automatically computes S(t) with 95% CI at fixed time points (e.g., 1yr, 3yr, 5yr).
Clinical Validity Checks
| Check | Threshold | Action |
|---|---|---|
| Events Per Variable (EPV) | < 10 | Warns about potential overfitting in multi-gene models |
| Heavy censoring | > 80% censored | Warns that KM tail estimates are unreliable |
| Median not reached | KM never crosses 50% | Reports "Not reached" and uses landmark survival instead |
EPV Guideline
| EPV | Reliability |
|---|---|
| >= 20 | Very stable estimates |
| 10-20 | Adequate for most analyses |
| 5-10 | Interpret with caution |
| < 5 | Potentially severely overfitted |
Rule of thumb: no more than 1 gene per 10 events in the dataset.
Input Formats
| Format | Extension | Description |
|---|---|---|
| Expression matrix | .csv |
Genes as rows, samples as columns |
| Clinical data | .csv |
Must contain sample, time (in months/days), event (0/1) columns |
CLI Reference
python omicsclaw.py run bulkrna-survival --demo
python omicsclaw.py run bulkrna-survival --input expr.csv --clinical clinical.csv --genes TP53,BRCA1 --output results/
python bulkrna_survival.py --demo --output /tmp/survival_demo
Output Structure
output_directory/
├── report.md
├── result.json
├── figures/
│ ├── km_GENE1.png
│ ├── km_GENE2.png
│ └── forest_plot.png
├── tables/
│ ├── survival_results.csv
│ └── cox_results.csv
└── reproducibility/
└── commands.sh
Parameters
| Parameter | Default | Description |
|---|---|---|
--input |
— | Path to expression matrix CSV |
--clinical |
— | Path to clinical data CSV |
--genes |
— | Comma-separated gene list to analyze |
--cutoff-method |
median |
Stratification: median or optimal |
--output |
— | Output directory |
--demo |
— | Run with demo data |
Safety
- Local-first: All processing runs locally; no data is uploaded.
- Disclaimer: Every report includes the standard OmicsClaw disclaimer.
- Clinical data sensitivity: No PHI is transmitted; all data stays on local filesystem.
Integration with Orchestrator
Chaining partners:
bulkrna-de— Upstream: provides candidate genes for survival analysisbulkrna-enrichment— Parallel: genes associated with survival → pathway enrichmentbulkrna-ppi-network— Downstream: survival-associated genes → PPI network
Citations
- Kaplan-Meier — Kaplan & Meier, JASA 1958
- Cox PH — Cox, JRSSB 1972
- lifelines — Davidson-Pilon, JOSS 2019
Dependencies
Required: numpy, pandas, scipy, matplotlib Optional: lifelines (enhanced KM curves, Cox regression, C-index)
Related Skills
bulkrna-de— Differential expression upstreambulkrna-enrichment— Pathway enrichment of survival-associated genes