Skip to contents

Plot Method for Kaplan-Meier Curves

Source: R/plot.kmcurve_fast.R
plot.kmcurve_fast.Rd

Draws the Kaplan-Meier curves of a kmcurve_fast object. With rmst = TRUE the area under each curve up to tau is shaded to visualize the restricted mean survival time. With hr = TRUE a second panel shows the smoothed time-varying hazard ratio together with the constant Cox proportional-hazards estimate and, optionally, the average hazard ratio, in the style of stylized nonproportional-hazards figures. For a single-group object only one survival curve is drawn; hr = TRUE is ignored because a hazard ratio requires two groups. With risk_table = TRUE the numbers at risk are printed below the survival panel.

Usage

# S3 method for class 'kmcurve_fast'
plot(
  x,
  hr = FALSE,
  rmst = FALSE,
  tau = NULL,
  bw = NULL,
  n_grid = 200L,
  conf.int = TRUE,
  hr_max = NULL,
  cox_line = TRUE,
  ahr_line = FALSE,
  mark_time = TRUE,
  conf.level = 0.95,
  conf.type = "log",
  col_control = "#1b9e77",
  col_treat = "#d95f02",
  col_hr = "#3060c0",
  col_cox = "black",
  col_ahr = "grey40",
  lty_control = 1,
  lty_treat = 1,
  lty_hr = 1,
  lwd_control = 2,
  lwd_treat = 2,
  lwd_hr = 2,
  base_size = 1,
  legend_pos = "topright",
  xlab = "Time",
  ylab = "Survival probability",
  main_km = "Kaplan-Meier",
  main_hr = "Hazard ratio",
  group_labels = NULL,
  risk_table = FALSE,
  risk_times = NULL,
  conf.style = c("lines", "band"),
  ...
)

Arguments

x

A kmcurve_fast object from kmcurve_fast.

hr

Logical. If TRUE, add a hazard-ratio panel to the right.

rmst

Logical. If TRUE, shade the area under each curve up to tau and annotate the restricted mean survival time difference.

tau

Upper limit used for the restricted mean survival time and the average hazard ratio. Defaults to the smaller of the two groups' largest observed times.

bw

Kernel bandwidth for the smoothed hazard ratio. Defaults to a value derived from the spread of the event times.

n_grid

Number of grid points for the smoothed hazard ratio.

conf.int

Logical. If TRUE, add pointwise confidence limits to the survival curves, drawn as set by conf.style.

hr_max

Upper limit of the hazard-ratio axis. Defaults to a value derived from the estimated hazard ratio.

cox_line

Logical. If TRUE, add the constant Cox hazard ratio as a horizontal line in the hazard-ratio panel.

ahr_line

Logical. If TRUE, add the average hazard ratio as a horizontal line in the hazard-ratio panel.

mark_time

Logical. If TRUE, mark censoring times on the curves.

conf.level

Confidence level for the survival confidence limits.

conf.type

Type of survival confidence limits: one of "plain", "log" (default), or "log-log", matching survfit_fast.

col_control, col_treat, col_hr, col_cox, col_ahr

Colors for the control curve, the treatment curve, the smoothed hazard ratio, the Cox line, and the average-hazard-ratio line.

lty_control, lty_treat

Line types for the control and treatment curves.

lty_hr

Line type for the smoothed hazard ratio.

lwd_control, lwd_treat

Line widths for the control and treatment curves.

lwd_hr

Line width for the lines in the hazard-ratio panel.

base_size

Relative size of all text.

legend_pos

Keyword giving the legend position in both panels, passed to legend (for example "topright" or "bottomleft").

xlab, ylab

Axis labels for the survival panel.

main_km, main_hr

Panel titles.

group_labels

Optional length-two character vector of legend labels for the control and treatment groups. They also label the rows of the number-at-risk table, which are otherwise labeled Control and Treatment (or by the group label for a single group).

risk_table

Logical. If TRUE, print the numbers at risk below the survival panel. Defaults to FALSE.

risk_times

Times at which the numbers at risk are given. Defaults to the tick marks of the time axis.

conf.style

How the pointwise confidence limits are drawn when conf.int = TRUE: "lines" (default) as dashed step functions, or "band" as a shaded band.

...

Further arguments, currently ignored.

Value

The input x, invisibly.

Details

The smoothed hazard ratio is obtained by kernel smoothing the Nelson-Aalen increments of each group. For group j the kernel hazard estimate is the sum over event times of (1 / bw) K((t - t_i) / bw) (d_i / Y_i), with an Epanechnikov kernel K, and the hazard ratio is the treatment estimate divided by the control estimate. The bandwidth bw controls the width of the averaging window and materially affects the result, so it is exposed as an argument. To limit boundary bias the hazard ratio is drawn over an interior time window, and points where the control hazard estimate is effectively zero are dropped.

The constant Cox hazard ratio is taken from coxph_fast, the average hazard ratio from ahr_fast, and the restricted mean survival time difference from rmst_fast.

The number at risk at a time is the number of subjects whose observed time is at or after it, as reported by summary() of a survival::survfit() object. The table has one row per group, in the colors of the curves, at the tick marks of the time axis or at risk_times; the bottom margin (and, for long group labels, the left margin) is enlarged to hold it. The curves themselves are available as a data frame from as.data.frame.kmcurve_fast.

See also

kmcurve_fast, print.kmcurve_fast, as.data.frame.kmcurve_fast