ggSurvGraph: Kaplan-Meier Survival Graphs
In nutterb/Bluegrass: Assorted Tools and Gimmicks for My Own Personal Use

Description Usage Arguments Details Internal Data Author(s) Examples

View source: R/ggSurvGraph.R

Creates a graph of one or more survival curves with vertical bars to represent confidence intervals. Uses the ggplot system instead of base graphics.

1 2	ggSurvGraph(object, times, cum.inc = FALSE, conf.bar = TRUE, offset.scale = 1, n.risk = FALSE, n.event = FALSE, gg_expr)

`object`	A fitted survival object, such as a survfit model or a data frame containing the information for the graph. If a data frame, the columns must be named time, surv, lower, upper, n.risk, n.event, group. (see details for more information).
`times`	Vector of times at which confidence bars should be drawn. Defaults to all event times.
`cum.inc`	If `TRUE`, a cumulative incidence plot is drawn instead of a survival plot.
`conf.bar`	If `TRUE`, vertical bars denoting the confidence limits are drawn.
`offset.scale`	the scale of time units to offset the bars from the specified interval. For example, if a bar should be placed at 25 months, and scale=.5, the bars will be placed at 24.5 and 25.5 months. If scale=1, the bars will be placed at 24 months and 26 months. Additional groups are placed further out on the same scale
`n.risk`	A logical indicating whether the number of subjects at risk should be printed at the bottom of the graph. Defaults to `FALSE` for no printing.
`n.event`	A logical indicating whether the cumulative number of events should be printed at the bottom of the graph. Defaults to `FALSE` for no printing.
`gg_expr`	A list of expressions to be added to the initial `ggplot` command.

The function plots the Kaplan-Meier survival curves of the provided object or data. It then places vertical bars the length of the confidence interval at that point at the distances specified by span.

ggSurvGraph operates my creating a data frame of values to be plotted, even if a survfit object is passed to the function. Thus, SurvGraph does not utilize the options in plot.survfit. Those accustomed to plotting Kaplan-Meier curves with plot.survfit will not necessarily get the same results with ggSurvGraph.

When a data frame is passed to ggSurvGraph the columns of data must have the named elements: time, surv, lower, upper, n.risk, n.event [,strata], where

When a data frame is passed to SurvGraph the columns of data must have the named elements: time, surv, lower, upper, n.risk, n.event [,strata], where

`time`	denotes the survival time
`surv`	denotes the probability of survival at `time`
`lower`	denotes the lower confidence limit for `surv`
`upper`	denotes the upper confidence limit for `surv`
`n.risk`	denotes the number at risk at `time`
`n.event`	denotes the number of events occuring between `time` and the previous `time`.
`strata`	is an optional variable that allows for simultaneous plotting of stratified survival curves. Each observation in the data set should have a group associated with it if `group` is supplied.

SurvGraph is not capable of handling cox models.

Additional layers may be added to the plot using the gg_expr argument. The layers should use the data produced internal to the function. There are two data sets created. survRaw is generated from the output of summary(object) without a times argument. The Kaplan-Meier curve is based on this data frame as it contains the information for the full curve. A second data frame, called survData, is generated from the output of summary(object, times=[times]) and is used to draw the confidence bars.

Contents of survRaw

time The time elapsed since the index time
n.risk The number at risk at time
n.event The number of events between time[t-1] and time[t].
n.censor The number of censored observations between time[t-1] and time[t]
surv The survival proportion at time[t]
lower The lower confidence limit of survival at time[t]
upper The upper confidence limit of survival at time[t]
strata Group assignment
cum.evt The cumulative events at time[t]
next.time The next observed time in the object. This is useful for plotting confidence bands.

The contents survData are identical, except it lacks the next.time variable.

Benjamin Nutter

## Not run:  
  library(survival)
  fit <- survfit(Surv(time, status) ~ x, data=aml)
  ggSurvGraph(fit)
  ggSurvGraph(fit, offset.scale=2, n.risk=TRUE) 
  
  #* changing the linetype:
  #* Because the graph is based on the output from the survfit object,
  #* the aesthetics passed to the plot must be based on the variable names
  #* from that object, not the original data frame.  The linetype and 
  #* colour will be based on the 'strata'.
  ggSurvGraph(fit, n.risk=TRUE,
              gg_expr=list(aes(linetype=strata)))
              
  #* Confidence Bands can be obtained using geom_rect()
  ggSurvGraph(fit, conf.bar=FALSE, times=seq(0, 60, by=12),
              gg_expr=list(geom_rect(aes(xmin=time, xmax=next.time,
                                         ymin=lower, ymax=upper,
                                         fill=strata),
                                     alpha=.25, linetype=0)))

## End(Not run)