ggsurv: Survival curves with ggplot

View source: R/ggplots.R

ggsurvR Documentation

Survival curves with ggplot

Description

Plot Kaplan-Meier or Cox proportional hazards models with at-risk table using ggplot.

Usage

ggsurv(
  s,
  col.surv = 1,
  lty.surv = 1,
  censor = TRUE,
  col.cens = 1,
  mark = 3,
  confin = TRUE,
  confband = FALSE,
  col.band = NA,
  median = FALSE,
  atrisk = TRUE,
  col.atrisk,
  pval,
  basehaz = FALSE,
  ticks,
  median.ticks = TRUE,
  xlab,
  ylab,
  main,
  xlim,
  ylim,
  legend = "right",
  legend.labels,
  grid = FALSE,
  ggdefault = FALSE,
  plot.margin = NULL,
  table.margin = NULL,
  ...
)

Arguments

s

survfit or survfit.cox object

col.surv

color of survival lines; should be one color or match number of strata

lty.surv

line type used for survival line; default is 1 (solid line)

censor

logical; if TRUE, plots censored observations (default)

col.cens

color for censor marks

mark

plotting character for censored observations

confin

logical; plot confidence bounds around survival estimate

confband

logical; plot confidence band; note that this is not a confidence band in the statistical sense; see details

col.band

band colors; if NULL, uses default ggplot colors (default); should be one color or match number of strata

median

logical; if TRUE, plots line corresponding to median survival (inherits col.surv)

atrisk

logical; if TRUE, adds table with number of at-risk observatons at each tick timepoint; color of text inherits from col.surv

col.atrisk

optional color for at risk text, e.g., 'black'

pval

two-element numeric vector corresponding to x- and y-coordinates to plot a p-value; p-value based on log-rank test for significant differences in Kaplan-Meier curves (see survdiff); if NULL, no test is performed (default)

basehaz

logical; if TRUE, returns baseline survival curve of a coxph object; see basehaz

ticks

three-element numeric vector corresponding to the "from," "to," and "by" arguments of seq, respectively; if NULL, ticks will be the default values; if NULL and atrist = TRUE, defaults to seq(0, max(time), length.out = 10)

median.ticks

logical; if TRUE, tick labels will be shown for median survival times (user should provide ticks argument to avoid overlapping labels); if atrisk = TRUE, plot will also provide number at risk at median survival time(s)

xlab

x-axis label

ylab

y-axis label

main

title

xlim

two-element numeric vector of x-axis range; see xlim; if NULL, default is used

ylim

two-element numeric vector of y-axis range; see ylim; if NULL, default is used

legend

legend position (no legend if no strata present); takes values of TRUE, FALSE, "none," "right," "left," "top," "bottom," or two-element numeric vector

legend.labels

labels to use for strata in legend; defaults are made by survfit

grid

logical; if TRUE, grid lines are drawn at major and minor ticks

ggdefault

logical; use default ggplot background; if FALSE, white background is used (default)

plot.margin

numeric; extra "lines" added to left margin of plot; see details

table.margin

numeric; extra "lines" added to left margin of at risk table; see details

...

for backwards compatibility with deprecated arguments

Details

The argument confband = TRUE does not plot a confidence band in the statistical sense, i.e., xx-percent chance of containing entire population of the survival curve which are wider than the point-wise confidence limits. Rather, it refers to a band of color in ggplot objects, specifically the use of a geom_ribbon geometric shape. The band is bounded by the confidence limits calculated in the survfit object which is passed to ggsurv in the initial function call.

Long strata labels can mis-align the at risk numbers and plot ticks. If the arguments plot.margin and table.margin are NULL, the function will make a guess based on the number of characters in the strata labels. If this is not perfect, plot.margin and table.margin can be specified explicitly by providing a single numeric corresponding to the number of "lines" of padding (see unit). Note that the default for ggplot is unit(.25, "lines").

See Also

kmplot; survival:::plot.survfit

Examples

## Not run: 
library('ggplot2')
library('grid')
library('gridExtra')
library('survival')
data(cancer)

cancer <- within(cancer, {
  age.cat <- factor(as.numeric(cut(age, c(-Inf, 50, 60, 70, Inf))))
  meal.cat <- factor(as.numeric(cut(meal.cal, 
    c(-Inf,quantile(meal.cal, c(.25,.5,.75), na.rm = TRUE), Inf))))
  wt.cat <- factor(as.numeric(cut(wt.loss, c(-Inf,quantile(wt.loss, 
    c(.25,.5,.75), na.rm = TRUE),Inf))))
})

## fitting models
# kaplan-meier
kmfit0 <- survfit(Surv(time = time, event = status) ~ 1, data = cancer, 
  conf.type = 'log-log')
kmfit1 <- survfit(Surv(time = time, event = status) ~ sex, data = cancer, 
  conf.type = 'log-log')
  
# cox proportional hazards
coxfit0 <- survfit(coxph(Surv(time = time, event = status) ~ strata(age.cat),
  data = cancer))
coxfit1 <- survfit(coxph(Surv(time = time, event = status) ~ strata(I(age > 45)),
  data = cancer))

ggsurv(kmfit0)

ggsurv(kmfit1, confin = FALSE, lty.surv = 1:2,
  grid = FALSE, pval = c(500, .75))

ggsurv(kmfit1, confin = FALSE, lty.surv = 1:2,
  confband = TRUE, col.band = c('blue','red'),
  legend.labels = c('Male', 'Female'),
  median = TRUE, ticks = c(0, 1000, 200))
  
ggsurv(coxfit0, basehaz = TRUE, col.surv = 1:4)

## this long label mis-aligns the table numbers, so we can use plot.margin
## to adjust; it may be easier to adjust plot.margin instead of table.margin
ggsurv(coxfit0, confin = FALSE, col.atrisk = 'black',
  col.surv = c('red','green','blue','black'),
  legend.labels = c('Less than 50','50-60','60-70','70+'),
  plot.margin = 3)


png('plot.png', height = 600, width = 750)
ggsurv(coxfit1, confin = FALSE, median = TRUE, confband = FALSE,
  legend.labels = c('< 45','> 45'), legend = FALSE,
  col.surv = c('red','green'), mark = '#')
dev.off()

## End(Not run)

raredd/plotr documentation built on Nov. 19, 2023, 4:09 a.m.