Skip to contents

Survival table

Source: R/tbl_survfit.R
tbl_survfit.Rd

Summarizes survival curves from survival::survfit() in a table: the survival probability at given times, or the survival time at given quantiles (probs), with confidence limits. The interface is that of gtsummary::tbl_survfit(), and the survival package must be installed.

x can be a single survfit object, a list of them, or a data frame. With a data frame, a survfit model is fit for each variable in include as the stratifying variable, with y as the outcome, e.g. tbl_survfit(trial, y = Surv(ttdeath, death), include = c(trt, grade), times = 12). Each model may have at most one stratifying variable; a model without one (~ 1) is shown on a single row labelled "Overall".

Usage

tbl_survfit(
  x,
  times = NULL,
  probs = NULL,
  statistic = "{estimate} ({conf.low}, {conf.high})",
  label = NULL,
  label_header = ifelse(!is.null(times), "**Time {time}**",
    "**{style_sigfig(prob, scale=100)}% Percentile**"),
  estimate_fun = ifelse(!is.null(times), label_style_percent(suffix = "%"),
    label_style_sigfig()),
  missing = "—",
  type = NULL,
  y = NULL,
  include = everything(),
  conf.level = 0.95,
  ...
)

Arguments

x

(survfit, list or data.frame)
A survfit object, a list of survfit objects, or a data frame.

times

(numeric)
The times at which to report survival probabilities. One of times and probs must be given.

probs

(numeric)
Probabilities in (0, 1) at which to report survival quantiles, e.g. probs = 0.5 for the median survival time.

statistic

(string)
The statistic shown in each cell, with statistic names in curly braces. Default is "{estimate} ({conf.low}, {conf.high})"; {n.risk} and {std.error} are also available with times.

label

(formula-list)
Labels for the stratifying variables, e.g. list(trt = "Treatment"), or a string that labels every model. The default for each is the label attribute of the variable in the model's data, or the variable name.

label_header

(string)
The column header, with {time} or {prob} standing for the value of the column. Default is "**Time {time}**" with times and "**{style_sigfig(prob, scale=100)}% Percentile**" with probs.

estimate_fun

(function)
Function that formats the estimate and its confidence limits. Default is label_style_percent(suffix = "%") for survival probabilities and label_style_sigfig() for survival times.

missing

(string)
Text shown when an estimate cannot be computed, for example the median survival when fewer than half of the subjects had the event. Default is an em dash.

type

(string)
Transformation of the survival probabilities reported with times, ignored with probs: "survival" (the default, the probability itself), "risk" (1 - x) or "cumhaz" (-log(x)). Not available for multi-state models.

y

(string or expression)
With a data frame, the outcome used in every model, e.g. Surv(ttdeath, death) or "Surv(ttdeath, death)".

include

(selector)
With a data frame, the columns to use as stratifying variables, one model each. Columns named in y are left out. Default is everything().

conf.level

(scalar numeric)
With a data frame, the confidence level of the models. Default is 0.95. The models in a survfit object keep their own level.

...

Not used.

Value

A table of class c("tbl_survfit", "ltsummary"), with the survfit objects in x$inputs$x.

Formula specification

add_p() and add_n() re-fit from the formula and data of the survfit() call, so both must be evaluable where tbl_survfit() is called. A formula written in the call works; with a data frame passed to tbl_survfit() the models are built so that they always are. See tbl_survfit_errors for what to do when they are not.

Multi-state models

For a competing-risks model (a Surv() outcome with a factor status), the table shows the probability of the first state after censoring, with a message naming it. type cannot be used, and add_nevent() is not available.

Why this is not an S3 generic

gtsummary's tbl_survfit() is a generic with survfit, list and data.frame methods. When both packages are attached, a method of the same name in ltsummary would be found by gtsummary's generic as well (see tbl_regression()), so ltsummary exposes one plain function that accepts the three kinds of input.

See also

add_p_survfit, add_n_survfit and add_nevent_survfit for the columns that can be added, and inline_text() for reporting cells in text.

Other survival tables: add_n_survfit, add_nevent_survfit, add_p_survfit, tbl_survfit_errors

Other table builders: tbl_continuous(), tbl_cross(), tbl_custom_summary(), tbl_likert(), tbl_merge(), tbl_regression(), tbl_stack(), tbl_strata(), tbl_strata_nested_stack(), tbl_summary(), tbl_uvregression(), tbl_wide_summary()

Examples

library(survival)

# Example 1 ----------------------------------
# a single survfit object, with a header for each time
tbl_survfit(
  survfit(Surv(ttdeath, death) ~ trt, trial),
  times = c(12, 24),
  label_header = "**{time} Month**"
)


# Example 2 ----------------------------------
# a data frame: one model per variable, the median survival time
tbl_survfit(
  trial,
  y = "Surv(ttdeath, death)",
  include = c(trt, grade),
  probs = 0.5,
  label_header = "**Median Survival**"
)


# Example 3 ----------------------------------
# a list of survfit objects, with a p-value and the counts
list(survfit(Surv(ttdeath, death) ~ 1, trial),
     survfit(Surv(ttdeath, death) ~ trt, trial)) |>
  tbl_survfit(times = c(12, 24)) |>
  add_n() |>
  add_nevent() |>
  add_p()


# Example 4 ----------------------------------
# a competing-risks model: the probability of death from cancer
set.seed(1123)
trial2 <- trial
trial2$death_cr <- factor(ifelse(
  trial2$death == 0, "censor",
  ifelse(runif(nrow(trial2)) < 0.5, "death from cancer", "death other causes")
))
survfit(Surv(ttdeath, death_cr) ~ grade, data = trial2) |>
  tbl_survfit(times = c(12, 24), label = "Tumor Grade")
#> Multi-state model detected. Showing probabilities into state 'death from cancer'.