Survival curve
A Kaplan–Meier plot shows the probability of remaining event-free over time. Each subject contributes one observation: either the time the event happened, or the time of last follow-up for a censored subject who did not have the event. It is the standard tool for time-to-event outcomes in trials and epidemiology.
WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/survival.tsv'))
SELECT kuva_render(to_json({
'x_axis': {'name': 'time (months)'},
'y_axis': {'name': 'survival probability'},
'series': [{
'type': 'survival',
'groups': (SELECT list({'label': "group",
'times': ts,
'events': evs} ORDER BY "group")
FROM (SELECT "group",
list(time ORDER BY time) AS ts,
list(event = 1 ORDER BY time) AS evs
FROM d GROUP BY "group"))
}]
})) AS chart;
A group takes parallel times and events lists; event = 1 becomes the true the field expects, so the
long-format table is pivoted and typed in one pass. Tick marks on the curves are the censored
observations — the subjects still event-free at their last follow-up.
Several arms, with a p-value
One group per arm. There are two ways to get a p-value onto the chart:
pvalue_textrenders the string you give it, so the test has to be run in SQL (or elsewhere) and the formatted result passed in.logrank_pvalue: trueruns the log-rank test on the raw data and annotates the result (e.g.log-rank p = 0.023), overridingpvalue_text. Two groups use the exact Mantel–Haenszel statistic; three or more use theΣ (O−E)²/Eapproximation.
The example below passes a pre-computed string — a chart that invents a p-value is worse than one without, and a string keeps the number traceable to the query that produced it.
WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/survival.tsv'))
SELECT kuva_render(to_json({
'x_axis': {'name': 'time (months)'},
'y_axis': {'name': 'survival probability'},
'legend': {'position': 'outside_right_top'},
'series': [{
'type': 'survival',
'groups': (SELECT list({'label': "group",
'times': ts,
'events': evs} ORDER BY "group")
FROM (SELECT "group",
list(time ORDER BY time) AS ts,
list(event = 1 ORDER BY time) AS evs
FROM d GROUP BY "group")),
'pvalue_text': 'log-rank p = 0.031',
'legend': 'arm'
}]
})) AS chart;
Clinical annotations
Three options turn a survival plot into a publication-style clinical figure:
| Field | What it adds |
|---|---|
risk_table | A number-at-risk table below the plot: one row per group, counts at each x-axis tick. Space is reserved automatically. |
median_lines | Median-survival reference lines: a dashed horizontal at S = 0.5 out to each curve's median time, then a dashed vertical down to the axis. Groups that never reach 0.5 get no line. |
logrank_pvalue | The log-rank p-value, computed from the raw data and annotated (overrides pvalue_text). |
WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/survival.tsv'))
SELECT kuva_render(to_json({
'title': 'Kaplan-Meier with number at risk',
'x_axis': {'name': 'time (months)'},
'y_axis': {'name': 'survival probability'},
'legend': {'position': 'outside_right_top'},
'series': [{
'type': 'survival',
'groups': (SELECT list({'label': "group",
'times': ts,
'events': evs} ORDER BY "group")
FROM (SELECT "group",
list(time ORDER BY time) AS ts,
list(event = 1 ORDER BY time) AS evs
FROM d GROUP BY "group")),
'ci': true,
'ci_alpha': 0.15,
'risk_table': true,
'median_lines': true,
'logrank_pvalue': true,
'legend': 'arm'
}]
})) AS chart;
Reading the table: each cell is the number of subjects still under follow-up at that time — everyone whose observed time (event or censoring) is at least the tick. It is not the survival probability times N: when subjects are censored the two diverge, and a small count is the signal that the later steps of the curve rest on very few people.
Confidence bands
ci overlays the Greenwood 95 % band around each curve and ci_alpha sets its opacity. Bands that overlap
heavily are the visual version of "this difference is not significant", which is worth looking at before
quoting any p-value.
WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/survival.tsv'))
SELECT kuva_render(to_json({
'x_axis': {'name': 'time (months)'},
'y_axis': {'name': 'survival probability'},
'legend': {'position': 'outside_right_top'},
'series': [{
'type': 'survival',
'groups': (SELECT list({'label': "group",
'times': ts,
'events': evs} ORDER BY "group")
FROM (SELECT "group",
list(time ORDER BY time) AS ts,
list(event = 1 ORDER BY time) AS evs
FROM d GROUP BY "group")),
'ci': true,
'ci_alpha': 0.15,
'pvalue_text': 'p < 0.001',
'legend': 'arm'
}]
})) AS chart;
Colours
colors assigns one colour per group, by position. Give the arms colours that carry meaning — treatment
versus control, high versus low — rather than letting the palette decide, because the palette order depends
on how the groups were sorted.
WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/survival.tsv'))
SELECT kuva_render(to_json({
'x_axis': {'name': 'time (months)'},
'y_axis': {'name': 'survival probability'},
'legend': {'position': 'outside_right_top'},
'series': [{
'type': 'survival',
'groups': (SELECT list({'label': "group",
'times': ts,
'events': evs} ORDER BY "group")
FROM (SELECT "group",
list(time ORDER BY time) AS ts,
list(event = 1 ORDER BY time) AS evs
FROM d GROUP BY "group")),
'colors': ['#2ca02c', '#d62728'],
'ci': true,
'legend': 'arm'
}]
})) AS chart;
Styling
| Field | Default | What it sets |
|---|---|---|
line_width | 2 | Curve stroke width |
censoring | true | Draw the censoring tick marks |
censoring_size | 4 | Half-height of those ticks, in pixels |
ci / ci_alpha | false / 0.2 | The Greenwood band and its opacity |
pvalue_text | — | A string drawn in the upper-right corner |
WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/survival.tsv'))
SELECT kuva_render(to_json({
'x_axis': {'name': 'time (months)'},
'y_axis': {'name': 'survival probability'},
'legend': {'position': 'outside_right_top'},
'series': [{
'type': 'survival',
'groups': (SELECT list({'label': "group",
'times': ts,
'events': evs} ORDER BY "group")
FROM (SELECT "group",
list(time ORDER BY time) AS ts,
list(event = 1 ORDER BY time) AS evs
FROM d GROUP BY "group")),
'censoring': false,
'line_width': 3,
'legend': 'arm'
}]
})) AS chart;
Fields
| Field | Type | What it sets |
|---|---|---|
groups | group[] | Required. One entry per arm: {label, times, events, color?}. |
times | number[] | Each subject's follow-up time. |
events | boolean[] | true = the event occurred, false = censored. |
colors | string[] | Per-group colours, matched by position. |
line_width | number | Curve stroke width (default 2). |
ci / ci_alpha | boolean / number | The Greenwood 95 % band and its opacity. |
censoring / censoring_size | boolean / number | The censoring ticks. |
pvalue_text | string | Free text drawn in the corner — kuva does not compute it. |
risk_table | boolean | Draw a number-at-risk table below the plot. |
median_lines | boolean | Draw dashed median-survival reference lines. |
logrank_pvalue | boolean | Compute and annotate the log-rank p-value from the raw data; overrides pvalue_text. |
legend | string | Legend title; one entry per group. |
Notes
groupsmust not be empty, and within each grouptimesandeventsmust be the same length.- Event times are numeric — months, days, cycles — whatever one x unit means.
pvalue_textis a string: kuva does not run the test for you. Compute it in SQL and pass the formatted result, so the number on the chart is traceable.logrank_pvalue: trueis the one exception — it computes the test fromtimes/eventsand wins overpvalue_text.risk_tableandmedian_linesonly read the data you already pass; they add no new fields.- A censored subject contributes a tick, not a drop; if the ticks are hidden, say so in the caption.
colorsis matched by position, so it has to line up with the order the groups come out of the query.
See also
- kuva — Survival curve — the plotting library's own reference for this chart.
- Forest — pooled effect estimates instead of time-to-event curves.
- ROC — another step-function statistical curve.