ggsurvplot: Drawing Survival Curves Using ggplot2

Description Usage Arguments Details Value FURTHER ARGUMENTS Plot title and axis labels Legend title, labels and position Axis limits, breaks and scales Confidence interval P-value Median survival Censor points Survival tables Survival plot height Number of censored subjects barplot Other graphical parameters Author(s) Examples

View source: R/ggsurvplot.R

Description

ggsurvplot() is a generic function to plot survival curves. Wrapper around the ggsurvplot_xx() family functions. Plot one or a list of survfit objects as generated by the survfit.formula() and surv_fit functions:

See the documentation for each function to learn how to control that aspect of the ggsurvplot(). ggsurvplot() accepts further arguments to be passed to the ggsurvplot_xx() functions. Has options to:

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
ggsurvplot(fit, data = NULL, fun = NULL, color = NULL, palette = NULL,
  linetype = 1, conf.int = FALSE, pval = FALSE, pval.method = FALSE,
  test.for.trend = FALSE, surv.median.line = "none", risk.table = FALSE,
  cumevents = FALSE, cumcensor = FALSE, tables.height = 0.25,
  group.by = NULL, facet.by = NULL, add.all = FALSE, combine = FALSE,
  ggtheme = theme_survminer(), tables.theme = ggtheme, ...)

## S3 method for class 'ggsurvplot'
print(x, surv.plot.height = NULL,
  risk.table.height = NULL, ncensor.plot.height = NULL, newpage = TRUE,
  ...)

Arguments

fit

allowed values include:

  • a survfit object

  • a list of survfit objects. Passed to ggsurvplot_list()

  • a data frame containing survival curves summary. Passed to ggsurvplot_df().

data

a dataset used to fit survival curves. If not supplied then data will be extracted from 'fit' object.

fun

an arbitrary function defining a transformation of the survival curve. Often used transformations can be specified with a character argument: "event" plots cumulative events (f(y) = 1-y), "cumhaz" plots the cumulative hazard function (f(y) = -log(y)), and "pct" for survival probability in percentage.

color

color to be used for the survival curves.

  • If the number of strata/group (n.strata) = 1, the expected value is the color name. For example color = "blue".

  • If n.strata > 1, the expected value is the grouping variable name. By default, survival curves are colored by strata using the argument color = "strata", but you can also color survival curves by any other grouping variables used to fit the survival curves. In this case, it's possible to specify a custom color palette by using the argument palette.

palette

the color palette to be used. Allowed values include "hue" for the default hue color scale; "grey" for grey color palettes; brewer palettes e.g. "RdBu", "Blues", ...; or custom color palette e.g. c("blue", "red"). See details section for more information. Can be also a numeric vector of length(groups); in this case a basic color palette is created using the function palette.

linetype

line types. Allowed values includes i) "strata" for changing linetypes by strata (i.e. groups); ii) a numeric vector (e.g., c(1, 2)) or a character vector c("solid", "dashed").

conf.int

logical value. If TRUE, plots confidence interval.

pval

logical value, a numeric or a string. If logical and TRUE, the p-value is added on the plot. If numeric, than the computet p-value is substituted with the one passed with this parameter. If character, then the customized string appears on the plot. See examples - Example 3.

pval.method

whether to add a text with the test name used for calculating the pvalue, that corresponds to survival curves' comparison - used only when pval=TRUE

test.for.trend

logical value. Default is FALSE. If TRUE, returns the test for trend p-values. Tests for trend are designed to detect ordered differences in survival curves. That is, for at least one group. The test for trend can be only performed when the number of groups is > 2.

surv.median.line

character vector for drawing a horizontal/vertical line at median survival. Allowed values include one of c("none", "hv", "h", "v"). v: vertical, h:horizontal.

risk.table

Allowed values include:

  • TRUE or FALSE specifying whether to show or not the risk table. Default is FALSE.

  • "absolute" or "percentage". Shows the absolute number and the percentage of subjects at risk by time, respectively.

  • "abs_pct" to show both absolute number and percentage.

  • "nrisk_cumcensor" and "nrisk_cumevents". Show the number at risk and, the cumulative number of censoring and events, respectively.

cumevents

logical value specifying whether to show or not the table of the cumulative number of events. Default is FALSE.

cumcensor

logical value specifying whether to show or not the table of the cumulative number of censoring. Default is FALSE.

tables.height

numeric value (in [0 - 1]) specifying the general height of all tables under the main survival plot.

group.by

a character vector containing the name of grouping variables. Should be of length <= 2. Alias of the ggsurvplot_group_by() function.

facet.by

a character vector containing the name of grouping variables to facet the survival curves into multiple panels. Should be of length <= 2. Alias of the ggsurvplot_facet() function.

add.all

a logical value. If TRUE, add the survival curve of pooled patients (null model) onto the main plot. Alias of the ggsurvplot_add_all() function.

combine

a logical value. If TRUE, combine a list survfit objects on the same plot. Alias of the ggsurvplot_combine() function.

ggtheme

function, ggplot2 theme name. Default value is theme_survminer. Allowed values include ggplot2 official themes: see theme.

tables.theme

function, ggplot2 theme name. Default value is theme_survminer. Allowed values include ggplot2 official themes: see theme.

...

Futher arguments as described hereafter and other arguments to be passed i) to ggplot2 geom_*() functions such as linetype, size, ii) or to the function ggpar() for customizing the plots. See details section.

x

an object of class ggsurvplot

surv.plot.height

the height of the survival plot on the grid. Default is 0.75. Ignored when risk.table = FALSE.

risk.table.height

the height of the risk table on the grid. Increase the value when you have many strata. Default is 0.25. Ignored when risk.table = FALSE.

ncensor.plot.height

The height of the censor plot. Used when ncensor.plot = TRUE.

newpage

open a new page. See grid.arrange

Details

Value

return an object of class ggsurvplot which is list containing the following components:

FURTHER ARGUMENTS

Customize survival plots and tables. See also ggsurvplot_arguments.

Plot title and axis labels

Legend title, labels and position

Axis limits, breaks and scales

Confidence interval

P-value

Median survival

Censor points

Survival tables

General parameters for all tables. The arguments below, when specified, will be applied to all survival tables at once (risk, cumulative events and cumulative censoring tables).

Specific to the risk table

Specific to the number of cumulative events table (cumevents)

Specific to the number of cumulative censoring table (cumcensor)

Survival plot height

Number of censored subjects barplot

Other graphical parameters

The plot can be easily customized using additional arguments to be passed to the function ggpar().

These arguments include font.title, font.subtitle, font.caption, font.x, font.y, font.tickslab and font.legend, which are vectors of length 3 indicating respectively the size (e.g.: 14), the style (e.g.: "plain", "bold", "italic", "bold.italic") and the color (e.g.: "red") of main title, subtitle, caption, xlab and ylab, axis tick labels and legend, respectively. For example font.x = c(14, "bold", "red").

Use font.x = 14, to change only font size; or use font.x = "bold", to change only font face.

Author(s)

Alboukadel Kassambara, [email protected]

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# Example 1: Survival curves with two groups
#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

# Fit survival curves
#++++++++++++++++++++++++++++++++++++
require("survival")
fit<- survfit(Surv(time, status) ~ sex, data = lung)

# Basic survival curves
ggsurvplot(fit, data = lung)

# Customized survival curves
ggsurvplot(fit, data = lung,
 surv.median.line = "hv", # Add medians survival

 # Change legends: title & labels
 legend.title = "Sex",
 legend.labs = c("Male", "Female"),
 # Add p-value and tervals
 pval = TRUE,

 conf.int = TRUE,
 # Add risk table
 risk.table = TRUE,
 tables.height = 0.2,
 tables.theme = theme_cleantable(),

 # Color palettes. Use custom color: c("#E7B800", "#2E9FDF"),
 # or brewer color (e.g.: "Dark2"), or ggsci color (e.g.: "jco")
 palette = c("#E7B800", "#2E9FDF"),
 ggtheme = theme_bw() # Change ggplot2 theme
)

# Change font size, style and color
#++++++++++++++++++++++++++++++++++++
## Not run: 
# Change font size, style and color at the same time
ggsurvplot(fit, data = lung,  main = "Survival curve",
   font.main = c(16, "bold", "darkblue"),
   font.x = c(14, "bold.italic", "red"),
   font.y = c(14, "bold.italic", "darkred"),
   font.tickslab = c(12, "plain", "darkgreen"))

## End(Not run)



#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# Example 2: Facet ggsurvplot() output by
# a combination of factors
#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

# Fit (complexe) survival curves
#++++++++++++++++++++++++++++++++++++
## Not run: 
require("survival")
fit3 <- survfit( Surv(time, status) ~ sex + rx + adhere,
                data = colon )

# Visualize
#++++++++++++++++++++++++++++++++++++
ggsurv <- ggsurvplot(fit3, data = colon,
  fun = "cumhaz", conf.int = TRUE,
  risk.table = TRUE, risk.table.col="strata",
  ggtheme = theme_bw())

# Faceting survival curves
curv_facet <- ggsurv$plot + facet_grid(rx ~ adhere)
curv_facet

# Faceting risk tables:
# Generate risk table for each facet plot item
ggsurv$table + facet_grid(rx ~ adhere, scales = "free")+
 theme(legend.position = "none")

 # Generate risk table for each facet columns
tbl_facet <- ggsurv$table + facet_grid(.~ adhere, scales = "free")
tbl_facet + theme(legend.position = "none")

# Arrange faceted survival curves and risk tables
g2 <- ggplotGrob(curv_facet)
g3 <- ggplotGrob(tbl_facet)
min_ncol <- min(ncol(g2), ncol(g3))
g <- gridExtra::rbind.gtable(g2[, 1:min_ncol], g3[, 1:min_ncol], size="last")
g$widths <- grid::unit.pmax(g2$widths, g3$widths)
grid::grid.newpage()
grid::grid.draw(g)


## End(Not run)

#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# Example 3: CUSTOMIZED PVALUE
#%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
# Customized p-value
ggsurvplot(fit, data = lung, pval = TRUE)
ggsurvplot(fit, data = lung, pval = 0.03)
ggsurvplot(fit, data = lung, pval = "The hot p-value is: 0.031")

survminer documentation built on Nov. 18, 2017, 4:06 a.m.