kmplot_by: kmplot_by

In raredd/rawr: rawr miscellaneous

kmplot_by

Description

This function helps create stratified kmplots quickly with panel labels, survival curve test(s), and/or Cox regression summaries for each plot.

data should have at least three variables: strata, *_time, and *_ind where * is event. For example, to use progression-free survival, data should have columns "pfs_time" and "pfs_ind" (in this case the user should use event = 'pfs') and optionally the strata column unless only the null model (strata = "1" is needed (default).

Alternatively, the time argument may be used instead of following the above; in this case, time and event must be variable names in data. However, the method described above is more efficient and preferred.

Usage

kmplot_by(
  strata = "1",
  event = NULL,
  data = NULL,
  by = NULL,
  time = NULL,
  single = TRUE,
  lr_test = TRUE,
  main = NULL,
  ylab = NULL,
  sub = NULL,
  strata_lab = NULL,
  fig_lab = NULL,
  col.surv = NULL,
  map.col = FALSE,
  legend = FALSE,
  add = FALSE,
  plot = TRUE,
  args.survfit = list(),
  stratify = NULL,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

strata, event, time, by	character strings of the strata, event (pfs, os, ttp, etc.; see details), time (optional), and stratification variables; additionally, vectors for each are allowed
data	a data frame
single	logical; if TRUE, each level of by will be drawn in a separate window
lr_test	logical or numeric; if TRUE, a log-rank test will be performed and the results added to the top-right corner of the plot; if numeric, the value is passed as rho controlling the type of test performed; see survdiff
main	title of plot(s)
ylab	y-axis label
sub	sub-title displayed in upper left corner; should be a character vector with length equal to the number of panels (i.e., the number of unique values of by or length one if by was not given)
strata_lab	at-risk table strata labels; should be a character vector with length equal to the number of strata; TRUE (or equivalently missing) is the default, and FALSE trims the labels; see examples
fig_lab	figure panel labels; should be a character vector with length equal to the number of panels (i.e., the number of unique values of by or length one if by was not given)
col.surv	color for individual survival curves or for all curves in a plot if by is given and map.col = TRUE; if col.surv is a named vector which matches the at risk labels, then colors are mapped to the corresponding strata; see kmplot
map.col	logical; if TRUE, col.surv will be the color of all curves in each plot (only used when by is non-missing)
legend	logical, a vector of x/y coordinates, or a keyword (see legend); if TRUE, the default position is "bottomleft"
add	logical; if FALSE (default), resets graphical parameters to settings before kmplot_by was called; set to TRUE for adding to existing plots
plot	logical; if FALSE, no plot is created but a list with survfits is returned
args.survfit	a named list of optional arguments passed to survfit.formula; relevant arguments include type (default is "kaplan-meier"), error ("greenwood"), conf.int (0.95), "conf.type" ("log"), and "se.fit" (TRUE)
stratify	(dev) strata variables
panel.first, panel.last, ...	additional arguments passed to kmplot or graphical parameters subsequently passed to par

Value

Invisibly returns a list of survfit object(s) used to generate plot(s). If by was used, there will be a list element for each unique value.

See Also

kmplot; survdiff; kmplot_data_; lr_text; lr_pval; points.kmplot

Examples

library('survival')
kmplot_by(time = 'time', event = 'status', data = colon)
with(colon, kmplot_by('All', time = time, event = status))


## create *_ind, *_time variables, see details
colon2 <- within(colon[duplicated(colon$id), ], {
  pfs_time <- time
  pfs_ind  <- status
  sex <- factor(sex, 0:1, c('Female','Male'))
})

kmplot_by('rx', 'pfs', data = colon2, col.surv = 1:3,
  strata_lab = FALSE, median = TRUE)
kmplot_by('rx', 'pfs', data = colon2, col.surv = 1:3,
  strata_lab = FALSE, median = TRUE, args.survfit = list(conf.int = 0.90))


## these are equivalent (with minor differences in aesthetics)
kmplot_by(time = 'pfs_time', event = 'pfs_ind', data = colon2)
kmplot_by('1', 'pfs', colon2)


## return value is a list of survfit objects
l <- kmplot_by('sex', 'pfs', colon2, 'rx', plot = FALSE)
str(lapply(l, kmplot))
str(lapply(l, kmplot_by))


## multiple variables can be combined
kmplot_by('rx + sex', 'pfs', colon2, strata_lab = FALSE, lty.surv = 1:6)


## if "by" is given, default is to plot separately
kmplot_by('rx', 'pfs', colon2, by = 'sex', col.surv = 1:3,
  strata_lab = c('Observation', 'Trt', 'Trt + 5-FU'))

## if "by" is given, use map.col to map colors to plots
kmplot_by( 'rx', 'pfs', colon2, by = 'rx', map.col = TRUE, single = FALSE)
kmplot_by('sex', 'pfs', colon2, by = 'rx', map.col = TRUE, single = FALSE)
kmplot_by('sex', 'pfs', colon2, by = 'age > 60', map.col = TRUE, single = FALSE)

## to ensure colors are mapped to the same strata across plots (eg, if
## all sub plots do not have the same groups), use a _named_ vector
kmplot_by('rx', 'pfs', colon2, by = 'rx', xlim = c(0, 3000),
          col.surv = c(Lev = 'brown', Obs = 'blue', 'Lev+5FU' = 'purple'))


## if single = FALSE, uses n2mfrow function to set par('mfrow')
kmplot_by('rx', 'pfs', colon2, by = 'sex', col.surv = 1:3, single = FALSE,
  strata_lab = c('Observe', 'Trt', 'Trt + 5-FU'), main = levels(colon2$sex))


## if par('mfrow') is anything other than c(1,1), uses current setting
par(mfrow = c(2,2))
kmplot_by('rx', 'pfs', colon2, by = 'sex', col.surv = 1:3, single = FALSE,
  strata_lab = c('Observation','Trt','Trt + 5-FU'), add = TRUE)
kmplot_by('1', 'pfs', colon2, by = 'sex', col.surv = 1:3, single = FALSE,
  strata_lab = FALSE, fig = c('C', 'D'), lr_test = FALSE)


## use add = TRUE to add to a figure region without using the by argument
par(mfrow = c(1, 2))
mar <- c(8, 6, 3, 2) ## to align axes
kmplot_by( 'rx', 'pfs', colon2, strata_lab = FALSE, add = TRUE, mar = mar)
kmplot_by('sex', 'pfs', colon2, strata_lab = FALSE, add = TRUE, mar = mar)

raredd/rawr documentation built on April 29, 2024, 10:29 a.m.