cox_regression_inter: Cox regression helper function for interactions

In tern: Create Common TLGs Used in Clinical Trials

Cox regression helper function for interactions

Description

Test and estimate the effect of a treatment in interaction with a covariate. The effect is estimated as the HR of the tested treatment for a given level of the covariate, in comparison to the treatment control.

Usage

h_coxreg_inter_effect(x, effect, covar, mod, label, control, ...)

## S3 method for class 'numeric'
h_coxreg_inter_effect(x, effect, covar, mod, label, control, at, ...)

## S3 method for class 'factor'
h_coxreg_inter_effect(x, effect, covar, mod, label, control, data, ...)

## S3 method for class 'character'
h_coxreg_inter_effect(x, effect, covar, mod, label, control, data, ...)

h_coxreg_extract_interaction(effect, covar, mod, data, at, control)

h_coxreg_inter_estimations(
  variable,
  given,
  lvl_var,
  lvl_given,
  mod,
  conf_level = 0.95
)

Arguments

x	(numeric or factor) the values of the covariate to be tested.
effect	(string) the name of the effect to be tested and estimated.
covar	(string) the name of the covariate in the model.
mod	(coxph) a fitted Cox regression model (see survival::coxph()).
label	(string) the label to be returned as term_label.
control	(list) a list of controls as returned by control_coxreg().
...	see methods.
at	(list) a list with items named after the covariate, every item is a vector of levels at which the interaction should be estimated.
data	(data.frame) the data frame on which the model was fit.
variable, given	(string) the name of variables in interaction. We seek the estimation of the levels of variable given the levels of given.
lvl_var, lvl_given	(character) corresponding levels as given by levels().
conf_level	(proportion) confidence level of the interval.

Details

Given the cox regression investigating the effect of Arm (A, B, C; reference A) and Sex (F, M; reference Female) and the model being abbreviated: y ~ Arm + Sex + Arm:Sex. The cox regression estimates the coefficients along with a variance-covariance matrix for:

• b1 (arm b), b2 (arm c)

• b3 (sex m)

• b4 (arm b: sex m), b5 (arm c: sex m)

The estimation of the Hazard Ratio for arm C/sex M is given in reference to arm A/Sex M by exp(b2 + b3 + b5)/ exp(b3) = exp(b2 + b5). The interaction coefficient is deduced by b2 + b5 while the standard error is obtained as $sqrt(Var b2 + Var b5 + 2 * covariance (b2,b5))$.

Value

• h_coxreg_inter_effect() returns a data.frame of covariate interaction effects consisting of the following variables: effect, term, term_label, level, n, hr, lcl, ucl, pval, and pval_inter.

• h_coxreg_extract_interaction() returns the result of an interaction test and the estimated values. If no interaction, h_coxreg_univar_extract() is applied instead.

• h_coxreg_inter_estimations() returns a list of matrices (one per level of variable) with rows corresponding to the combinations of variable and given, with columns:

  • coef_hat: Estimation of the coefficient.

  • coef_se: Standard error of the estimation.

  • hr: Hazard ratio.

  • ⁠lcl, ucl⁠: Lower/upper confidence limit of the hazard ratio.

Functions

• h_coxreg_inter_effect(): S3 generic helper function to determine interaction effect.

• h_coxreg_inter_effect(numeric): Method for numeric class. Estimates the interaction with a numeric covariate.

• h_coxreg_inter_effect(factor): Method for factor class. Estimate the interaction with a factor covariate.

• h_coxreg_inter_effect(character): Method for character class. Estimate the interaction with a character covariate. This makes an automatic conversion to factor and then forwards to the method for factors.

• h_coxreg_extract_interaction(): A higher level function to get the results of the interaction test and the estimated values.

• h_coxreg_inter_estimations(): Hazard ratio estimation in interactions.

Note

• Automatic conversion of character to factor does not guarantee results can be generated correctly. It is therefore better to always pre-process the dataset such that factors are manually created from character variables before passing the dataset to rtables::build_table().

Examples

library(survival)

set.seed(1, kind = "Mersenne-Twister")

# Testing dataset [survival::bladder].
dta_bladder <- with(
  data = bladder[bladder$enum < 5, ],
  data.frame(
    time = stop,
    status = event,
    armcd = as.factor(rx),
    covar1 = as.factor(enum),
    covar2 = factor(
      sample(as.factor(enum)),
      levels = 1:4,
      labels = c("F", "F", "M", "M")
    )
  )
)
labels <- c("armcd" = "ARM", "covar1" = "A Covariate Label", "covar2" = "Sex (F/M)")
formatters::var_labels(dta_bladder)[names(labels)] <- labels
dta_bladder$age <- sample(20:60, size = nrow(dta_bladder), replace = TRUE)

plot(
  survfit(Surv(time, status) ~ armcd + covar1, data = dta_bladder),
  lty = 2:4,
  xlab = "Months",
  col = c("blue1", "blue2", "blue3", "blue4", "red1", "red2", "red3", "red4")
)

mod <- coxph(Surv(time, status) ~ armcd * covar1, data = dta_bladder)
h_coxreg_extract_interaction(
  mod = mod, effect = "armcd", covar = "covar1", data = dta_bladder,
  control = control_coxreg()
)

mod <- coxph(Surv(time, status) ~ armcd * covar1, data = dta_bladder)
result <- h_coxreg_inter_estimations(
  variable = "armcd", given = "covar1",
  lvl_var = levels(dta_bladder$armcd),
  lvl_given = levels(dta_bladder$covar1),
  mod = mod, conf_level = .95
)
result

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