This module fits Cox univariable or multi-variable models, consistent with the TLG Catalog
templates for Cox regression tables COXT01
and COXT02
, respectively. See the TLG Catalog entries
for COXT01
here
and COXT02
here.
Usage
tm_t_coxreg(
label,
dataname,
parentname = ifelse(inherits(arm_var, "data_extract_spec"),
teal.transform::datanames_input(arm_var), "ADSL"),
arm_var,
arm_ref_comp = NULL,
paramcd,
cov_var,
strata_var,
aval_var = teal.transform::choices_selected(teal.transform::variable_choices(dataname,
"AVAL"), "AVAL", fixed = TRUE),
cnsr_var = teal.transform::choices_selected(teal.transform::variable_choices(dataname,
"CNSR"), "CNSR", fixed = TRUE),
multivariate = TRUE,
na_level = default_na_str(),
conf_level = teal.transform::choices_selected(c(0.95, 0.9, 0.8), 0.95, keep_order =
TRUE),
pre_output = NULL,
post_output = NULL,
basic_table_args = teal.widgets::basic_table_args()
)
Arguments
- label
(
character
)
menu item label of the module in the teal app.- dataname
(
character
)
analysis data used in teal module.- parentname
(
character
)
parent analysis data used in teal module, usually this refers toADSL
.- arm_var
(
teal.transform::choices_selected()
)
object with all available choices and preselected option for variable names that can be used asarm_var
. It defines the grouping variable in the results table.- arm_ref_comp
(
list
) optional,
if specified it must be a named list with each element corresponding to an arm variable inADSL
and the element must be another list (possibly with delayedteal.transform::variable_choices()
or delayedteal.transform::value_choices()
with the elements namedref
andcomp
that the defined the default reference and comparison arms when the arm variable is changed.- paramcd
(
teal.transform::choices_selected()
)
object with all available choices and preselected option for the parameter code variable fromdataname
.- cov_var
(
teal.transform::choices_selected()
)
object with all available choices and preselected option for the covariates variables.- strata_var
(
teal.transform::choices_selected()
)
names of the variables for stratified analysis.- aval_var
(
teal.transform::choices_selected()
)
object with all available choices and pre-selected option for the analysis variable.- cnsr_var
(
teal.transform::choices_selected()
)
object with all available choices and preselected option for the censoring variable.- multivariate
(
logical
)
ifFALSE
, the univariable approach is used instead of the multi-variable model.- na_level
(
string
)
used to replace allNA
or empty values in character or factor variables in the data. Defaults to"<Missing>"
. To set a defaultna_level
to apply in all modules, runset_default_na_str("new_default")
.- conf_level
(
teal.transform::choices_selected()
)
object with all available choices and pre-selected option for the confidence level, each within range of (0, 1).- pre_output
(
shiny.tag
) optional,
with text placed before the output to put the output into context. For example a title.- post_output
(
shiny.tag
) optional,
with text placed after the output to put the output into context. For example theshiny::helpText()
elements are useful.- basic_table_args
(
basic_table_args
) optional
object created byteal.widgets::basic_table_args()
with settings for the module table. The argument is merged with optionteal.basic_table_args
and with default module arguments (hard coded in the module body). For more details, see the vignette:vignette("custom-basic-table-arguments", package = "teal.widgets")
.
Details
The Cox Proportional Hazards (PH) model is the most commonly used method 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.
This modules expects that the analysis data has the following variables:
AVAL
: time to eventCNSR
: 1 if record inAVAL
is censored, 0 otherwisePARAMCD
: variable used to filter for endpoint (e.g. OS). After filtering forPARAMCD
one observation per patient is expected
The arm variables and stratification/covariate variables are taken from the ADSL
data.
Note
The likelihood ratio test is not supported for models that include strata - the Wald test will be substituted in these cases.
Multi-variable is the default choice for backward compatibility.
See also
The TLG Catalog where additional example apps implementing this module can be found.
Examples
## First example
## =============
## The example below is based on the usual approach involving creation of
## a random CDISC dataset and then running the application.
arm_ref_comp <- list(
ACTARMCD = list(
ref = "ARM B",
comp = c("ARM A", "ARM C")
),
ARM = list(
ref = "B: Placebo",
comp = c("A: Drug X", "C: Combination")
)
)
data <- teal_data()
data <- within(data, {
ADSL <- tmc_ex_adsl
ADTTE <- tmc_ex_adtte
})
join_keys(data) <- default_cdisc_join_keys[names(data)]
ADSL <- data[["ADSL"]]
ADTTE <- data[["ADTTE"]]
app <- init(
data = data,
modules = modules(
tm_t_coxreg(
label = "Cox Reg.",
dataname = "ADTTE",
arm_var = choices_selected(c("ARM", "ARMCD", "ACTARMCD"), "ARM"),
arm_ref_comp = arm_ref_comp,
paramcd = choices_selected(
value_choices(ADTTE, "PARAMCD", "PARAM"), "OS"
),
strata_var = choices_selected(
c("COUNTRY", "STRATA1", "STRATA2"), "STRATA1"
),
cov_var = choices_selected(
c("AGE", "BMRKR1", "BMRKR2", "REGION1"), "AGE"
),
multivariate = TRUE
)
)
)
#> Initializing tm_t_coxreg
#> Initializing reporter_previewer_module
if (interactive()) {
shinyApp(app$ui, app$server)
}
## Second example
## ==============
## This time, a synthetic pair of ADTTE/ADSL data is fabricated for Cox regression
## where ties and pval_method matter.
library(dplyr)
data <- teal_data()
data <- within(data, {
ADTTE <- data.frame(
STUDYID = "LUNG",
AVAL = c(4, 3, 1, 1, 2, 2, 3, 1, 2),
CNSR = c(1, 1, 1, 0, 1, 1, 0, 0, 0),
ARMCD = factor(
c(0, 1, 1, 1, 1, 0, 0, 0, 0),
labels = c("ARM A", "ARM B")
),
SEX = factor(
c(0, 0, 0, 0, 1, 1, 1, 1, 1),
labels = c("F", "M")
),
INST = factor(c("A", "A", "B", "B", "A", "B", "A", "B", "A")),
stringsAsFactors = FALSE
)
ADTTE <- rbind(ADTTE, ADTTE, ADTTE, ADTTE)
ADTTE <- as_tibble(ADTTE)
set.seed(1)
ADTTE$INST <- sample(ADTTE$INST)
ADTTE$AGE <- sample(seq(5, 75, 5), size = nrow(ADTTE), replace = TRUE)
ADTTE$USUBJID <- paste("sub", 1:nrow(ADTTE), ADTTE$INST, sep = "-")
ADTTE$PARAM <- ADTTE$PARAMCD <- "OS"
ADSL <- subset(
ADTTE,
select = c("USUBJID", "STUDYID", "ARMCD", "SEX", "INST", "AGE")
)
})
join_keys(data) <- default_cdisc_join_keys[names(data)]
ADSL <- data[["ADSL"]]
ADTTE <- data[["ADTTE"]]
## `teal` application
## ----------------
## Note that the R code exported by `Show R Code` does not include the data
## pre-processing. You will need to create the dataset as above before
## running the exported R code.
arm_ref_comp <- list(ARMCD = list(ref = "ARM A", comp = c("ARM B")))
app <- init(
data = data,
modules = modules(
tm_t_coxreg(
label = "Cox Reg.",
dataname = "ADTTE",
arm_var = choices_selected(c("ARMCD"), "ARMCD"),
arm_ref_comp = arm_ref_comp,
paramcd = choices_selected(
value_choices(ADTTE, "PARAMCD", "PARAM"), "OS"
),
strata_var = choices_selected(c("INST"), NULL),
cov_var = choices_selected(c("SEX", "AGE"), "SEX"),
multivariate = TRUE
)
)
)
#> Initializing tm_t_coxreg
#> Initializing reporter_previewer_module
if (interactive()) {
shinyApp(app$ui, app$server)
}