hinna0818/ukbanalytica_v2/ukbsci-survival

ukbsci-survival — Survival visualization for UK Biobank cohorts

0. RAP guardrails

This skill consumes a cohort data.table from ukbsci-cohort and produces PNG / PDF figures plus an aggregate "data behind the figure" CSV. Figures contain curves + numbers-at-risk only and may be shared with the local agent. Per-participant intermediate tables (e.g. expanded long-format survival sets) stay in /mnt/project/....

Strict local-agent boundary: this skill is for script generation, workflow planning, package guidance, and interpretation of aggregate outputs. The agent must not read, inspect, summarize, or process real UK Biobank RAP participant-level data, including de-identified row-level tables, raw RAP fields, exact dates, per-row predictions, row-level SHAP matrices, screenshots, tracebacks, or logs containing row-level values. Generate scripts for the user to run inside RAP; only aggregate results or rendered figures may be shared back with the agent. See ../references/agent-privacy-boundary.md.

1. When to load

• Draw a Kaplan-Meier curve, stratified or unstratified.
• Add a risk table beneath the KM curve.
• Show log-rank p-value comparing arms.
• Annotate median survival lines / censoring marks.

2. When NOT to load

• Fit / batch-fit Cox or Fine-Gray models → ukbsci-regression.
• Build the survival dataset or define cases → ukbsci-cohort.
• Subgroup × interaction tests → ukbsci-subgroup-sensitivity.
• Time-dependent ROC for ML predictions → ukbsci-ml.
• Forest / volcano / calibration plots → ukbsci-plot.

3. Prerequisites

library(UKBAnalytica)
library(survival)
library(survminer)            # plot_km_curve uses ggsurvplot under the hood
 
stopifnot(all(c("outcome_status", "outcome_surv_time") %in% colnames(cohort)))

4. Pipeline

Phase 1 — One-arm KM (no grouping)

p <- plot_km_curve(
  data       = cohort,
  time_col   = "outcome_surv_time",
  status_col = "outcome_status",
  conf_int   = TRUE,
  risk_table = TRUE,
  title      = "Overall survival",
  xlab       = "Follow-up (years)",
  ylab       = "Event-free probability"
)

plot_km_curve() returns a ggplot2 object (or a list $km_plot + $risk_table when risk_table = TRUE). Save with the standard helper:

ggplot2::ggsave("/mnt/project/<area>/05-figs/Fig03-km_overall.pdf",
                p, width = 7, height = 6)
ggplot2::ggsave("/mnt/project/<area>/05-figs/Fig03-km_overall.png",
                p, width = 7, height = 6, dpi = 300)

Phase 2 — Stratified KM

p <- plot_km_curve(
  data         = cohort,
  time_col     = "outcome_surv_time",
  status_col   = "outcome_status",
  group_col    = "Hypertension_history",
  conf_int     = TRUE,
  risk_table   = TRUE,
  censor_marks = TRUE,
  palette      = "jco",              # "jco", "nejm", "lancet", or custom vector
  median_line  = TRUE,
  pvalue       = TRUE,                # log-rank p
  legend_title = "Baseline HTN",
  xlim         = c(0, 15),
  break_time   = 3
)

Log-rank p-value is computed only when `group_col` is supplied.

Phase 3 — Save aggregate figure source data

plot_km_curve() does not write a source CSV automatically. Build it from survival::survfit() and save alongside the figure for transparency:

fit <- survfit(Surv(outcome_surv_time, outcome_status) ~ Hypertension_history,
               data = cohort)
km_data <- data.table::data.table(
  time     = fit$time,
  n.risk   = fit$n.risk,
  n.event  = fit$n.event,
  n.censor = fit$n.censor,
  surv     = fit$surv,
  lower    = fit$lower,
  upper    = fit$upper,
  strata   = rep(names(fit$strata), fit$strata)
)
fwrite(km_data,
       "/mnt/project/<area>/05-figs/data/Fig03-km_overall.csv")

5. Common pitfalls

1. `plot_km_curve()` requires `survminer` for the risk-table layout. If

it is not installed on the RAP node, the user will see a missing-package error; install before running.

1. **palette accepts presets ("jco", "nejm", "lancet") or a custom vector

of hex codes.** Mixing the two will silently fall back to a default.

1. `xlim` units must match `time_col`. outcome_surv_time in

UKBAnalytica is in years; passing xlim = c(0, 365) would clip almost the whole curve.

1. Prevalent participants. They have outcome_status = NA and

outcome_surv_time = NA; survfit() drops them automatically. Don't filter manually unless you intend to also drop censored cases.

1. Group with `NA` levels. group_col rows where the stratifier is NA

are dropped silently. If the group sizes look smaller than the cohort, that is why.

1. Risk-table fonts. Default font sizes target a 7-inch-wide figure. For

manuscript single-column (3.5 inch), shrink fontsize = 2.5 in the ggsurvplot defaults (edit the returned object).

1. Median-line for low event-rate cohorts. If the curve never crosses

0.5, the median line is invisible — this is correct behaviour, not a bug.

6. Key functions

7. Related skills

8. References

• `references/functions.md`
• `references/examples.md` — overall KM, stratified

KM, and "two-panel" KM (incidence + risk-table) example