ard_survival_survfit: ARD Survival Estimates

In cardx: Extra Analysis Results Data Utilities

ARD Survival Estimates

Description

Analysis results data for survival quantiles and x-year survival estimates, extracted from a survival::survfit() model.

Usage

ard_survival_survfit(x, ...)

## S3 method for class 'survfit'
ard_survival_survfit(x, times = NULL, probs = NULL, type = NULL, ...)

## S3 method for class 'data.frame'
ard_survival_survfit(
  x,
  y,
  variables = NULL,
  times = NULL,
  probs = NULL,
  type = NULL,
  method.args = list(conf.int = 0.95, conf.type = "log"),
  ...
)

Arguments

x	(survfit or data.frame) an object of class survfit created with survival::survfit() or a data frame. See below for details.
...	These dots are for future extensions and must be empty.
times	(numeric) a vector of times for which to return survival probabilities.
probs	(numeric) a vector of probabilities with values in (0,1) specifying the survival quantiles to return.
type	(string or NULL) type of statistic to report. Available for Kaplan-Meier time estimates only, otherwise type is ignored. Default is NULL. Must be one of the following: type transformation "survival" x "risk" 1 - x "cumhaz" -log(x)
y	(Surv or string) an object of class Surv created using survival::Surv(). This object will be passed as the left-hand side of the formula constructed and passed to survival::survfit(). This object can also be passed as a string.
variables	(tidy-select) stratification variables to be passed as the right-hand side of the formula constructed and passed to survival::survfit(). Default is NULL for an unstratified model, e.g. Surv() ~ 1.
method.args	(named list) named list of arguments that will be passed to survival::survfit().

Details

• Only one of either the times or probs parameters can be specified.

• Times should be provided using the same scale as the time variable used to fit the provided survival fit model.

Value

an ARD data frame of class 'card'

Formula Specification

When passing a survival::survfit() object to ard_survival_survfit(), the survfit() call must use an evaluated formula and not a stored formula. Including a proper formula in the call allows the function to accurately identify all variables included in the estimation. See below for examples:

library(cardx)
library(survival)

# include formula in `survfit()` call
survfit(Surv(time, status) ~ sex, lung) |> ard_survival_survfit(time = 500)

# you can also pass a data frame to `ard_survival_survfit()` as well.
lung |>
  ard_survival_survfit(y = Surv(time, status), variables = "sex", time = 500)

You cannot, however, pass a stored formula, e.g. survfit(my_formula, lung), but you can use stored formulas with rlang::inject(survfit(!!my_formula, lung)).

Variable Classes

When the survfit method is called, the class of the stratifying variables will be returned as a factor.

When the data frame method is called, the original classes are retained in the resulting ARD.

Examples

library(survival)
library(ggsurvfit)

survfit(Surv_CNSR(AVAL, CNSR) ~ TRTA, data = cards::ADTTE) |>
  ard_survival_survfit(times = c(60, 180))

survfit(Surv_CNSR(AVAL, CNSR) ~ TRTA, data = cards::ADTTE, conf.int = 0.90) |>
  ard_survival_survfit(probs = c(0.25, 0.5, 0.75))

cards::ADTTE |>
  ard_survival_survfit(y = Surv_CNSR(AVAL, CNSR), variables = c("TRTA", "SEX"), times = 90)

# Competing Risks Example ---------------------------
set.seed(1)
ADTTE_MS <- cards::ADTTE %>%
  dplyr::mutate(
    CNSR = dplyr::case_when(
      CNSR == 0 ~ "censor",
      runif(dplyr::n()) < 0.5 ~ "death from cancer",
      TRUE ~ "death other causes"
    ) %>% factor()
  )

survfit(Surv(AVAL, CNSR) ~ TRTA, data = ADTTE_MS) %>%
  ard_survival_survfit(times = c(60, 180))

cardx documentation built on July 3, 2025, 5:08 p.m.