cox_regression: Cox proportional hazards regression
In tern: Create Common TLGs Used in Clinical Trials

cox_regression

R Documentation

Cox proportional hazards regression

Description

Fits a Cox regression model and estimates hazard ratio to describe the effect size in a survival analysis.

Usage

summarize_coxreg(
  lyt,
  variables,
  control = control_coxreg(),
  at = list(),
  multivar = FALSE,
  common_var = "STUDYID",
  .stats = c("n", "hr", "ci", "pval", "pval_inter"),
  .formats = c(n = "xx", hr = "xx.xx", ci = "(xx.xx, xx.xx)", pval =
    "x.xxxx | (<0.0001)", pval_inter = "x.xxxx | (<0.0001)"),
  varlabels = NULL,
  .indent_mods = NULL,
  na_str = "",
  .section_div = NA_character_
)

s_coxreg(model_df, .stats, .which_vars = "all", .var_nms = NULL)

a_coxreg(
  df,
  labelstr,
  eff = FALSE,
  var_main = FALSE,
  multivar = FALSE,
  variables,
  at = list(),
  control = control_coxreg(),
  .spl_context,
  .stats,
  .formats,
  .indent_mods = NULL,
  na_str = "",
  cache_env = NULL
)

Arguments

`lyt`	(`PreDataTableLayouts`) layout that analyses will be added to.
`variables`	(named `list` of `string`) list of additional analysis variables.
`control`	(`list`) a list of parameters as returned by the helper function `control_coxreg()`.
`at`	(`list` of `numeric`) when the candidate covariate is a `numeric`, use `at` to specify the value of the covariate at which the effect should be estimated.
`multivar`	(`flag`) whether multivariate Cox regression should run (defaults to `FALSE`), otherwise univariate Cox regression will run.
`common_var`	(`string`) the name of a factor variable in the dataset which takes the same value for all rows. This should be created during pre-processing if no such variable currently exists.
`.stats`	(`character`) the names of statistics to be reported among: `n`: number of observations (univariate only) `hr`: hazard ratio `ci`: confidence interval `pval`: p-value of the treatment effect `pval_inter`: p-value of the interaction effect between the treatment and the covariate (univariate only)
`.formats`	(named `character` or `list`) formats for the statistics. See Details in `analyze_vars` for more information on the `"auto"` setting.
`varlabels`	(`list`) a named list corresponds to the names of variables found in data, passed as a named list and corresponding to time, event, arm, strata, and covariates terms. If arm is missing from variables, then only Cox model(s) including the covariates will be fitted and the corresponding effect estimates will be tabulated later.
`.indent_mods`	(named `integer`) indent modifiers for the labels. Defaults to 0, which corresponds to the unmodified default behavior. Can be negative.
`na_str`	(`string`) custom string to replace all `NA` values with. Defaults to `""`.
`.section_div`	(`string` or `NA`) string which should be repeated as a section divider between sections. Defaults to `NA` for no section divider. If a vector of two strings are given, the first will be used between treatment and covariate sections and the second between different covariates.
`model_df`	(`data.frame`) contains the resulting model fit from a fit_coxreg function with tidying applied via `broom::tidy()`.
`.which_vars`	(`character`) which rows should statistics be returned for from the given model. Defaults to `"all"`. Other options include `"var_main"` for main effects, `"inter"` for interaction effects, and `"multi_lvl"` for multivariate model covariate level rows. When `.which_vars` is `"all"`, specific variables can be selected by specifying `.var_nms`.
`.var_nms`	(`character`) the `term` value of rows in `df` for which `.stats` should be returned. Typically this is the name of a variable. If using variable labels, `var` should be a vector of both the desired variable name and the variable label in that order to see all `.stats` related to that variable. When `.which_vars` is `"var_main"`, `.var_nms` should be only the variable name.
`df`	(`data.frame`) data set containing all analysis variables.
`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.
`eff`	(`flag`) whether treatment effect should be calculated. Defaults to `FALSE`.
`var_main`	(`flag`) whether main effects should be calculated. Defaults to `FALSE`.
`.spl_context`	(`data.frame`) gives information about ancestor split states that is passed by `rtables`.
`cache_env`	(`environment`) an environment object used to cache the regression model in order to avoid repeatedly fitting the same model for every row in the table. Defaults to `NULL` (no caching).

Details

Cox models are the most commonly used methods to estimate the magnitude of the effect in survival analysis. It assumes proportional hazards: the ratio of the hazards between groups (e.g., two arms) is constant over time. This ratio is referred to as the "hazard ratio" (HR) and is one of the most commonly reported metrics to describe the effect size in survival analysis (NEST Team, 2020).

Value

summarize_coxreg() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add a Cox regression table containing the chosen statistics to the table layout.

s_coxreg() returns the selected statistic for from the Cox regression model for the selected variable(s).

a_coxreg() returns formatted rtables::CellValue().

Functions

summarize_coxreg(): Layout-creating function which creates a Cox regression summary table layout. This function is a wrapper for several rtables layouting functions. This function is a wrapper for rtables::analyze_colvars() and rtables::summarize_row_groups().
s_coxreg(): Statistics function that transforms results tabulated from fit_coxreg_univar() or fit_coxreg_multivar() into a list.
a_coxreg(): Analysis function which is used as afun in rtables::analyze() and cfun in rtables::summarize_row_groups() within summarize_coxreg().

Examples

library(survival)

# Testing dataset [survival::bladder].
set.seed(1, kind = "Mersenne-Twister")
dta_bladder <- with(
  data = bladder[bladder$enum < 5, ],
  tibble::tibble(
    TIME = stop,
    STATUS = event,
    ARM = as.factor(rx),
    COVAR1 = as.factor(enum) %>% formatters::with_label("A Covariate Label"),
    COVAR2 = factor(
      sample(as.factor(enum)),
      levels = 1:4, labels = c("F", "F", "M", "M")
    ) %>% formatters::with_label("Sex (F/M)")
  )
)
dta_bladder$AGE <- sample(20:60, size = nrow(dta_bladder), replace = TRUE)
dta_bladder$STUDYID <- factor("X")

u1_variables <- list(
  time = "TIME", event = "STATUS", arm = "ARM", covariates = c("COVAR1", "COVAR2")
)

u2_variables <- list(time = "TIME", event = "STATUS", covariates = c("COVAR1", "COVAR2"))

m1_variables <- list(
  time = "TIME", event = "STATUS", arm = "ARM", covariates = c("COVAR1", "COVAR2")
)

m2_variables <- list(time = "TIME", event = "STATUS", covariates = c("COVAR1", "COVAR2"))

# summarize_coxreg

result_univar <- basic_table() %>%
  summarize_coxreg(variables = u1_variables) %>%
  build_table(dta_bladder)
result_univar

result_univar_covs <- basic_table() %>%
  summarize_coxreg(
    variables = u2_variables,
  ) %>%
  build_table(dta_bladder)
result_univar_covs

result_multivar <- basic_table() %>%
  summarize_coxreg(
    variables = m1_variables,
    multivar = TRUE,
  ) %>%
  build_table(dta_bladder)
result_multivar

result_multivar_covs <- basic_table() %>%
  summarize_coxreg(
    variables = m2_variables,
    multivar = TRUE,
    varlabels = c("Covariate 1", "Covariate 2") # custom labels
  ) %>%
  build_table(dta_bladder)
result_multivar_covs

# s_coxreg

# Univariate
univar_model <- fit_coxreg_univar(variables = u1_variables, data = dta_bladder)
df1 <- broom::tidy(univar_model)

s_coxreg(model_df = df1, .stats = "hr")

# Univariate with interactions
univar_model_inter <- fit_coxreg_univar(
  variables = u1_variables, control = control_coxreg(interaction = TRUE), data = dta_bladder
)
df1_inter <- broom::tidy(univar_model_inter)

s_coxreg(model_df = df1_inter, .stats = "hr", .which_vars = "inter", .var_nms = "COVAR1")

# Univariate without treatment arm - only "COVAR2" covariate effects
univar_covs_model <- fit_coxreg_univar(variables = u2_variables, data = dta_bladder)
df1_covs <- broom::tidy(univar_covs_model)

s_coxreg(model_df = df1_covs, .stats = "hr", .var_nms = c("COVAR2", "Sex (F/M)"))

# Multivariate.
multivar_model <- fit_coxreg_multivar(variables = m1_variables, data = dta_bladder)
df2 <- broom::tidy(multivar_model)

s_coxreg(model_df = df2, .stats = "pval", .which_vars = "var_main", .var_nms = "COVAR1")
s_coxreg(
  model_df = df2, .stats = "pval", .which_vars = "multi_lvl",
  .var_nms = c("COVAR1", "A Covariate Label")
)

# Multivariate without treatment arm - only "COVAR1" main effect
multivar_covs_model <- fit_coxreg_multivar(variables = m2_variables, data = dta_bladder)
df2_covs <- broom::tidy(multivar_covs_model)

s_coxreg(model_df = df2_covs, .stats = "hr")

a_coxreg(
  df = dta_bladder,
  labelstr = "Label 1",
  variables = u1_variables,
  .spl_context = list(value = "COVAR1"),
  .stats = "n",
  .formats = "xx"
)

a_coxreg(
  df = dta_bladder,
  labelstr = "",
  variables = u1_variables,
  .spl_context = list(value = "COVAR2"),
  .stats = "pval",
  .formats = "xx.xxxx"
)

tern documentation built on Sept. 24, 2024, 9:06 a.m.