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(),
  ...,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

a_survival_subgroups(
  df,
  labelstr = "",
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

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.
...	additional arguments for the lower level functions.
.stat_names	(character) names of the statistics that are passed directly to name single statistics (.stats). This option is visible when producing rtables::as_result_df() with make_ard = TRUE.
.formats	(named character or list) formats for the statistics. See Details in analyze_vars for more information on the "auto" setting.
.labels	(named character) labels for the statistics (without indent).
.indent_mods	(named integer) indent modifiers for the labels. Defaults to 0, which corresponds to the unmodified default behavior. Can be negative.
labelstr	(string) label of the level of the parent split currently being summarized (must be present as second argument in Content Row Functions). See rtables::summarize_row_groups() for more information.
.stats	(character) statistics to select for the table.

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 15, 2025, 1:31 a.m.