Skip to main content

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_text renders the string you give it, so the test has to be run in SQL (or elsewhere) and the formatted result passed in.
  • logrank_pvalue: true runs the log-rank test on the raw data and annotates the result (e.g. log-rank p = 0.023), overriding pvalue_text. Two groups use the exact Mantel–Haenszel statistic; three or more use the Σ (O−E)²/E approximation.

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:

FieldWhat it adds
risk_tableA number-at-risk table below the plot: one row per group, counts at each x-axis tick. Space is reserved automatically.
median_linesMedian-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_pvalueThe 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​

FieldDefaultWhat it sets
line_width2Curve stroke width
censoringtrueDraw the censoring tick marks
censoring_size4Half-height of those ticks, in pixels
ci / ci_alphafalse / 0.2The 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​

FieldTypeWhat it sets
groupsgroup[]Required. One entry per arm: {label, times, events, color?}.
timesnumber[]Each subject's follow-up time.
eventsboolean[]true = the event occurred, false = censored.
colorsstring[]Per-group colours, matched by position.
line_widthnumberCurve stroke width (default 2).
ci / ci_alphaboolean / numberThe Greenwood 95 % band and its opacity.
censoring / censoring_sizeboolean / numberThe censoring ticks.
pvalue_textstringFree text drawn in the corner — kuva does not compute it.
risk_tablebooleanDraw a number-at-risk table below the plot.
median_linesbooleanDraw dashed median-survival reference lines.
logrank_pvaluebooleanCompute and annotate the log-rank p-value from the raw data; overrides pvalue_text.
legendstringLegend title; one entry per group.

Notes​

  • groups must not be empty, and within each group times and events must be the same length.
  • Event times are numeric — months, days, cycles — whatever one x unit means.
  • pvalue_text is 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: true is the one exception — it computes the test from times / events and wins over pvalue_text.
  • risk_table and median_lines only 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.
  • colors is 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.