Skip to contents

Kaplan-Meier survival curves with a number-at-risk table

Source: R/km.R
km.Rd

A right-continuous step curve per stratum, censoring ticks, an optional pointwise confidence band, and the number-at-risk table underneath. The table is on by default because a survival curve without one hides how much of its tail rests on a handful of patients, which is where readers over-read it.

Usage

km(
  data,
  groups = NULL,
  group_colors = NULL,
  risk_times = NULL,
  risk_counts = NULL,
  p_label = NULL,
  show_ci = TRUE,
  show_censors = TRUE,
  show_risk_table = TRUE,
  show_legend = TRUE,
  y_from_zero = TRUE,
  line_width = 2,
  x_label = "months",
  y_label = "overall survival",
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL
)

Arguments

data

Either a survival::survfit object, or a data frame with numeric time and surv columns and optional lower, upper and group columns. Within a stratum, rows must be in ascending time order.

groups

Character vector fixing the stratum order and colour assignment. Defaults to order of appearance.

group_colors

One hex colour per stratum. NULL uses the component's categorical palette.

risk_times

Numeric vector of times for the at-risk table, also used as the x-axis ticks. NULL picks an even grid across the follow-up.

risk_counts

Integer matrix, strata x risk_times. Computed from a survfit object automatically; required alongside risk_times when you pass a data frame and want the table.

p_label

Optional annotation drawn inside the panel, e.g. "log-rank p = 0.02". Not computed here: pass what your test returned.

show_ci, show_censors, show_risk_table, show_legend

Toggle the confidence band, censoring ticks, at-risk table and legend.

y_from_zero

Start the y axis at zero. Opt-out rather than automatic: zooming y exaggerates separation between curves.

line_width

Curve stroke width in pixels.

x_label, y_label

Axis titles.

theme

Optional named list of theme overrides.

width, height

Widget dimensions (any valid CSS size).

element_id

Optional explicit DOM id.

Value

An htmlwidget object.

Details

The widget draws, it does not estimate. Pass a survfit object and the estimates are read off it; pass a data frame and they are used as given. Both routes mean the numbers on screen are the ones your model produced, so a figure rendered here and the same figure rendered by plot() cannot disagree about where a curve steps.

Examples

df <- data.frame(
  time = c(0, 5, 12, 0, 7, 15),
  surv = c(1, 0.9, 0.7, 1, 0.8, 0.5),
  group = rep(c("treated", "control"), each = 3)
)
km(df)