| name | ukbsci-survival |
| description | Survival visualization and post-Cox summary helpers for UK Biobank Research Analysis Platform (RAP) cohorts built with UKBAnalytica. Covers Kaplan-Meier curves with risk tables and log-rank p-values (plot_km_curve), and pairs with ukbsci-regression for time-to-event analyses. Use this skill when the user asks to draw a KM curve, show cumulative incidence, build a risk-table-augmented survival figure, or visualize stratified survival across exposure / treatment groups. Triggers: UKB KM curve, Kaplan-Meier, survival curve, log-rank, risk table, cumulative incidence, UKB 生存曲线, KM 曲线, /ukbsci-survival. Hard rule: local agents must not read or inspect real UKB RAP participant-level data; generate scripts for RAP execution and interpret aggregate outputs only.
|
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)
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",
median_line = TRUE,
pvalue = TRUE,
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
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.palette accepts presets ("jco", "nejm", "lancet") or a custom vector
of hex codes. Mixing the two will silently fall back to a default.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.- 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.
- 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.
- 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).
- 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
| Function | Returns |
|---|
plot_km_curve(data, time_col, status_col, group_col = NULL, conf_int = TRUE, risk_table = TRUE, censor_marks = TRUE, palette = "jco", title = NULL, xlab = "Time (years)", ylab = "Survival Probability", legend_title = "Group", median_line = TRUE, pvalue = TRUE, xlim = NULL, break_time = NULL) | ggplot2 object (or list $km_plot + $risk_table when risk_table = TRUE) |
7. Related skills
| Skill | When to switch |
|---|
ukbsci-cohort | Re-build outcome_status / outcome_surv_time if missing. |
ukbsci-regression | Fit Cox / Fine-Gray models on the same outcome. |
ukbsci-subgroup-sensitivity | KM by interaction strata + interaction tests. |
ukbsci-plot | All other figure families (forest, volcano, calibration). |
ukbsci-workflow | Phase 6b — KM curves as the headline survival figure. |
8. References
