tiangzlab/omicsclaw/bulkrna-survival

bulkrna-survival

When to use

Load when comparing bulk expression strata against clinical time-to-event data with Kaplan-Meier and log-rank tests. R survival also fits Cox HR; Python reports a descriptive events/person-time ratio. Skip missing clinical outcomes.

Use from a step

from skills._sdk.notebook import load_skill, write_output
library = load_skill("bulkrna-survival")
result = library.analyze(data, clinical=clinical, backend="python")
write_output(result, "tables/result.csv")
write_output(library.curve_figure(result, gene="G"), "figures/result.png")

Read expression and metadata with read_input before calling the library. examples/example_step.py constructs a small synthetic dataset and checks its results through the step runner and fresh-kernel replay.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

analyze(data: pd.DataFrame, *, clinical: pd.DataFrame, genes: list[str] | None=None, cutoff_method: str='median', backend: str='auto') -> pd.DataFrame

Return gene-wise survival comparisons without modifying expression.

:param data: Nonnegative feature-by-sample expression. :param clinical: Clinical table with unique sample, nonnegative time and binary event columns. :param genes: Genes to test; None uses every row. Missing genes raise. :param cutoff_method: CLI default median; optimal scans cuts with unadjusted p-values. :param backend: auto prefers R survival with Cox HR, as the CLI did; python uses an events/person-time ratio. :returns: Per-gene table with diagnostics and KM points attached in attrs. :raises ValueError: Identifiers, clinical values, requested genes or comparison groups are invalid. :raises ImportError: Explicit R backend lacks survival or Matrix. :raises RuntimeError: The requested R method fails or returns incomplete results.

run_info(data: pd.DataFrame, *, keep: bool=True) -> dict

Return actual backend, HR estimator and summary.

:param data: Result from analyze. :param keep: Keep diagnostics by default; the CLI passes False. :returns: Diagnostics dictionary. :raises ValueError: The table has no analysis diagnostics.

km_table(data: pd.DataFrame) -> pd.DataFrame

Return the fitted Kaplan-Meier points for both expression strata.

:param data: Result from analyze. :returns: New table with gene, group, time and survival columns. :raises ValueError: The result lacks stored curves.

curve_figure(data: pd.DataFrame, *, gene: str)

Plot the stored Kaplan-Meier curves for one analyzed gene.

:param data: Result from analyze. :param gene: Exact gene identifier in the result. :returns: Matplotlib Figure. :raises ValueError: No curve exists for the requested gene.

<!-- api:end -->

Methods and parameters

The function library returns DataFrames and Figures. The CLI loads the same library and owns reports and file writes. R runs in a temporary directory using Matrix Market, feature/sample identifiers and metadata. No R intermediate is a permanent CLI output.

Gotchas

• analyze(backend="auto") prefers R survival, which fits Cox PH hazard ratios. Its Python fallback uses a descriptive events/person-time ratio. run_info()["hazard_estimator"] distinguishes them.
• analyze raises for missing genes or insufficient high/low groups; it does not silently deliver a subset of the requested genes.
• analyze(cutoff_method="optimal") scans cutoffs and reports unadjusted p-values. Treat the selected-cutoff test as exploratory.
• km_table exposes both KM curves. Median survival is None when a curve never reaches 0.5; no extrapolated median is invented.
• run_info()["dropped_expression_samples"] reports samples excluded by the expression/clinical intersection. Clinical IDs must be unique.

Inputs and outputs

Feature-by-sample expression CSV and a clinical CSV containing unique sample, nonnegative time and binary event.

CLI outputs:

• tables/survival_results.csv
• figures/km_<gene>.png per successful gene
• figures/forest_plot.png when at least two genes succeed
• report.md, result.json
• reproducibility/commands.sh

CLI

python skills/bulkrna/bulkrna-survival/bulkrna_survival.py --demo --output /tmp/bulkrna_survival_demo

Run the script with --help for real-input arguments.

See also

• references/parameters.md
• references/methodology.md
• references/output_contract.md

Dependencies

matplotlib, numpy, pandas, scipy, survival, Matrix