survival_duration_subgroups: Tabulate survival duration by subgroup

In tern: Create Common TLGs Used in Clinical Trials

Tabulate survival duration by subgroup

Description

The tabulate_survival_subgroups() function creates a layout element to tabulate survival duration by subgroup, returning statistics including median survival time and hazard ratio for each population subgroup. The table is created from df, a list of data frames returned by extract_survival_subgroups(), with the statistics to include specified via the vars parameter.

A forest plot can be created from the resulting table using the g_forest() function.

Usage

tabulate_survival_subgroups(
  lyt,
  df,
  vars = c("n_tot_events", "n_events", "median", "hr", "ci"),
  groups_lists = list(),
  label_all = lifecycle::deprecated(),
  time_unit = NULL,
  riskdiff = NULL,
  na_str = default_na_str(),
  .formats = c(n = "xx", n_events = "xx", n_tot_events = "xx", median = "xx.x", n_tot =
    "xx", hr = list(format_extreme_values(2L)), ci = list(format_extreme_values_ci(2L)),
    pval = "x.xxxx | (<0.0001)")
)

a_survival_subgroups(
  .formats = list(n = "xx", n_events = "xx", n_tot_events = "xx", median = "xx.x", n_tot
    = "xx", hr = list(format_extreme_values(2L)), ci =
    list(format_extreme_values_ci(2L)), pval = "x.xxxx | (<0.0001)"),
  na_str = default_na_str()
)

Arguments

lyt	(PreDataTableLayouts) layout that analyses will be added to.
df	(list) list of data frames containing all analysis variables. List should be created using extract_survival_subgroups().
vars	(character) the names of statistics to be reported among: n_tot_events: Total number of events per group. n_events: Number of events per group. n_tot: Total number of observations per group. n: Number of observations per group. median: Median survival time. hr: Hazard ratio. ci: Confidence interval of hazard ratio. pval: p-value of the effect. Note, one of the statistics n_tot and n_tot_events, as well as both hr and ci are required.
groups_lists	(named list of list) optionally contains for each subgroups variable a list, which specifies the new group levels via the names and the levels that belong to it in the character vectors that are elements of the list.
label_all	please assign the label_all parameter within the extract_survival_subgroups() function when creating df.
time_unit	(string) label with unit of median survival time. Default NULL skips displaying unit.
riskdiff	(list) if a risk (proportion) difference column should be added, a list of settings to apply within the column. See control_riskdiff() for details. If NULL, no risk difference column will be added. If riskdiff$arm_x and riskdiff$arm_y are NULL, the first level of df$survtime$arm will be used as arm_x and the second level as arm_y.
na_str	(string) string used to replace all NA or empty values in the output.
.formats	(named character or list) formats for the statistics. See Details in analyze_vars for more information on the "auto" setting.

Details

These functions create a layout starting from a data frame which contains the required statistics. Tables typically used as part of forest plot.

Value

An rtables table summarizing survival by subgroup.

• a_survival_subgroups() returns the corresponding list with formatted rtables::CellValue().

Functions

• tabulate_survival_subgroups(): Table-creating function which creates a table summarizing survival by subgroup. This function is a wrapper for rtables::analyze_colvars() and rtables::summarize_row_groups().

• a_survival_subgroups(): Formatted analysis function which is used as afun in tabulate_survival_subgroups().

See Also

extract_survival_subgroups()

Examples

library(dplyr)

adtte <- tern_ex_adtte

# Save variable labels before data processing steps.
adtte_labels <- formatters::var_labels(adtte)

adtte_f <- adtte %>%
  filter(
    PARAMCD == "OS",
    ARM %in% c("B: Placebo", "A: Drug X"),
    SEX %in% c("M", "F")
  ) %>%
  mutate(
    # Reorder levels of ARM to display reference arm before treatment arm.
    ARM = droplevels(forcats::fct_relevel(ARM, "B: Placebo")),
    SEX = droplevels(SEX),
    AVALU = as.character(AVALU),
    is_event = CNSR == 0
  )
labels <- c(
  "ARM" = adtte_labels[["ARM"]],
  "SEX" = adtte_labels[["SEX"]],
  "AVALU" = adtte_labels[["AVALU"]],
  "is_event" = "Event Flag"
)
formatters::var_labels(adtte_f)[names(labels)] <- labels

df <- extract_survival_subgroups(
  variables = list(
    tte = "AVAL",
    is_event = "is_event",
    arm = "ARM", subgroups = c("SEX", "BMRKR2")
  ),
  label_all = "Total Patients",
  data = adtte_f
)
df

df_grouped <- extract_survival_subgroups(
  variables = list(
    tte = "AVAL",
    is_event = "is_event",
    arm = "ARM", subgroups = c("SEX", "BMRKR2")
  ),
  data = adtte_f,
  groups_lists = list(
    BMRKR2 = list(
      "low" = "LOW",
      "low/medium" = c("LOW", "MEDIUM"),
      "low/medium/high" = c("LOW", "MEDIUM", "HIGH")
    )
  )
)
df_grouped

## Table with default columns.
basic_table() %>%
  tabulate_survival_subgroups(df, time_unit = adtte_f$AVALU[1])

## Table with a manually chosen set of columns: adding "pval".
basic_table() %>%
  tabulate_survival_subgroups(
    df = df,
    vars = c("n_tot_events", "n_events", "median", "hr", "ci", "pval"),
    time_unit = adtte_f$AVALU[1]
  )

tern documentation built on April 4, 2025, 12:10 a.m.