Replace strat with strata

NEWS.md

@@ -11,6 +11,8 @@
 
 ### Miscellaneous
 * Added function `expect_snapshot_ggplot` to test setup file to process plot snapshot tests and allow plot dimensions to be set.
+* Began deprecation of the named element `strat`, to be renamed to `strata`, within the `variables` argument to `h_rsp_to_logistic_variables`, `h_logistic_mult_cont_df`, `h_odds_ratio_subgroups_df`, `h_coxreg_mult_cont_df`, `h_coxph_subgroups_df`, `h_tbl_coxph_pairwise`, `extract_rsp_biomarkers`, `extract_rsp_subgroups`, `extract_survival_biomarkers`, and `extract_survival_subgroups`.
+* Began deprecation of the `strat` argument to `s_coxph_pairwise` and replaced it with the `strata` argument.
 
 # tern 0.9.3
 

R/h_response_biomarkers_subgroups.R

@@ -39,21 +39,29 @@ NULL
 #'   variables = list(
 #'     rsp = "RSP",
 #'     covariates = c("A", "B"),
-#'     strat = "D"
+#'     strata = "D"
 #'   ),
 #'   biomarker = "AGE"
 #' )
 #'
 #' @export
 h_rsp_to_logistic_variables <- function(variables, biomarker) {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `h_rsp_to_logistic_variables() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
   checkmate::assert_list(variables)
   checkmate::assert_string(variables$rsp)
   checkmate::assert_string(biomarker)
   list(
     response = variables$rsp,
     arm = biomarker,
     covariates = variables$covariates,
-    strata = variables$strat
+    strata = variables$strata
   )
 }
 
@@ -62,7 +70,7 @@ h_rsp_to_logistic_variables <- function(variables, biomarker) {
 #'   biomarkers in a given single data set.
 #'   `variables` corresponds to names of variables found in `data`, passed as a named list and requires elements
 #'   `rsp` and `biomarkers` (vector of continuous biomarker variables) and optionally `covariates`
-#'   and `strat`.
+#'   and `strata`.
 #'
 #' @return
 #' * `h_logistic_mult_cont_df()` returns a `data.frame` containing estimates and statistics for the selected biomarkers.
@@ -86,7 +94,7 @@ h_rsp_to_logistic_variables <- function(variables, biomarker) {
 #'     rsp = "rsp",
 #'     biomarkers = c("BMRKR1", "AGE"),
 #'     covariates = "SEX",
-#'     strat = "STRATA1"
+#'     strata = "STRATA1"
 #'   ),
 #'   data = adrs_f[NULL, ]
 #' )
@@ -95,6 +103,14 @@ h_rsp_to_logistic_variables <- function(variables, biomarker) {
 h_logistic_mult_cont_df <- function(variables,
                                     data,
                                     control = control_logistic()) {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `h_logistic_mult_cont_df() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
   assert_df_with_variables(data, variables)
 
   checkmate::assert_character(variables$biomarkers, min.len = 1, any.missing = FALSE)

R/h_response_subgroups.R

@@ -277,7 +277,7 @@ h_odds_ratio_df <- function(rsp, arm, strata_data = NULL, conf_level = 0.95, met
 #' @describeIn h_response_subgroups summarizes estimates of the odds ratio between a treatment and a control
 #'   arm across subgroups in a data frame. `variables` corresponds to the names of variables found in
 #'   `data`, passed as a named list and requires elements `rsp`, `arm` and optionally `subgroups`
-#'   and `strat`. `groups_lists` optionally specifies groupings for `subgroups` variables.
+#'   and `strata`. `groups_lists` optionally specifies groupings for `subgroups` variables.
 #'
 #' @return
 #' * `h_odds_ratio_subgroups_df()` returns a `data.frame` with columns `arm`, `n_tot`, `or`, `lcl`, `ucl`,
@@ -296,7 +296,7 @@ h_odds_ratio_df <- function(rsp, arm, strata_data = NULL, conf_level = 0.95, met
 #'     rsp = "rsp",
 #'     arm = "ARM",
 #'     subgroups = c("SEX", "BMRKR2"),
-#'     strat = c("STRATA1", "STRATA2")
+#'     strata = c("STRATA1", "STRATA2")
 #'   ),
 #'   data = adrs_f
 #' )
@@ -325,18 +325,27 @@ h_odds_ratio_subgroups_df <- function(variables,
                                       conf_level = 0.95,
                                       method = NULL,
                                       label_all = "All Patients") {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `h_odds_ratio_subgroups_df() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
+
   checkmate::assert_character(variables$rsp)
   checkmate::assert_character(variables$arm)
   checkmate::assert_character(variables$subgroups, null.ok = TRUE)
-  checkmate::assert_character(variables$strat, null.ok = TRUE)
+  checkmate::assert_character(variables$strata, null.ok = TRUE)
   assert_df_with_factors(data, list(val = variables$arm), min.levels = 2, max.levels = 2)
   assert_df_with_variables(data, variables)
   checkmate::assert_string(label_all)
 
-  strata_data <- if (is.null(variables$strat)) {
+  strata_data <- if (is.null(variables$strata)) {
     NULL
   } else {
-    data[, variables$strat, drop = FALSE]
+    data[, variables$strata, drop = FALSE]
   }
 
   # Add All Patients.
@@ -358,10 +367,10 @@ h_odds_ratio_subgroups_df <- function(variables,
     l_data <- h_split_by_subgroups(data, variables$subgroups, groups_lists = groups_lists)
 
     l_result <- lapply(l_data, function(grp) {
-      grp_strata_data <- if (is.null(variables$strat)) {
+      grp_strata_data <- if (is.null(variables$strata)) {
         NULL
       } else {
-        grp$df[, variables$strat, drop = FALSE]
+        grp$df[, variables$strata, drop = FALSE]
       }
 
       result <- h_odds_ratio_df(

R/h_survival_biomarkers_subgroups.R

@@ -71,7 +71,7 @@ h_surv_to_coxreg_variables <- function(variables, biomarker) {
 #'   times, as well as hazard ratio estimates, confidence intervals and p-values, for multiple biomarkers
 #'   in a given single data set.
 #'   `variables` corresponds to names of variables found in `data`, passed as a named list and requires elements
-#'   `tte`, `is_event`, `biomarkers` (vector of continuous biomarker variables) and optionally `subgroups` and `strat`.
+#'   `tte`, `is_event`, `biomarkers` (vector of continuous biomarker variables) and optionally `subgroups` and `strata`.
 #'
 #' @return
 #' * `h_coxreg_mult_cont_df()` returns a `data.frame` containing estimates and statistics for the selected biomarkers.
@@ -107,6 +107,15 @@ h_surv_to_coxreg_variables <- function(variables, biomarker) {
 h_coxreg_mult_cont_df <- function(variables,
                                   data,
                                   control = control_coxreg()) {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `h_coxreg_mult_cont_df() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
+
   assert_df_with_variables(data, variables)
   checkmate::assert_list(control, names = "named")
   checkmate::assert_character(variables$biomarkers, min.len = 1, any.missing = FALSE)

R/h_survival_duration_subgroups.R

@@ -220,7 +220,7 @@ h_coxph_df <- function(tte, is_event, arm, strata_data = NULL, control = control
       .in_ref_col = FALSE,
       .var = "tte",
       is_event = "is_event",
-      strat = strata_vars,
+      strata = strata_vars,
       control = control
     )
 
@@ -277,7 +277,7 @@ h_coxph_df <- function(tte, is_event, arm, strata_data = NULL, control = control
 #' @describeIn h_survival_duration_subgroups summarizes estimates of the treatment hazard ratio
 #'   across subgroups in a data frame. `variables` corresponds to the names of variables found in
 #'   `data`, passed as a named list and requires elements `tte`, `is_event`, `arm` and
-#'   optionally `subgroups` and `strat`. `groups_lists` optionally specifies
+#'   optionally `subgroups` and `strata`. `groups_lists` optionally specifies
 #'   groupings for `subgroups` variables.
 #'
 #' @return
@@ -321,7 +321,7 @@ h_coxph_df <- function(tte, is_event, arm, strata_data = NULL, control = control
 #'     is_event = "is_event",
 #'     arm = "ARM",
 #'     subgroups = c("SEX", "BMRKR2"),
-#'     strat = c("STRATA1", "STRATA2")
+#'     strata = c("STRATA1", "STRATA2")
 #'   ),
 #'   data = adtte_f
 #' )
@@ -332,11 +332,20 @@ h_coxph_subgroups_df <- function(variables,
                                  groups_lists = list(),
                                  control = control_coxph(),
                                  label_all = "All Patients") {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `h_coxph_subgroups_df() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
+
   checkmate::assert_character(variables$tte)
   checkmate::assert_character(variables$is_event)
   checkmate::assert_character(variables$arm)
   checkmate::assert_character(variables$subgroups, null.ok = TRUE)
-  checkmate::assert_character(variables$strat, null.ok = TRUE)
+  checkmate::assert_character(variables$strata, null.ok = TRUE)
   assert_df_with_factors(data, list(val = variables$arm), min.levels = 2, max.levels = 2)
   assert_df_with_variables(data, variables)
   checkmate::assert_string(label_all)
@@ -346,7 +355,7 @@ h_coxph_subgroups_df <- function(variables,
     tte = data[[variables$tte]],
     is_event = data[[variables$is_event]],
     arm = data[[variables$arm]],
-    strata_data = if (is.null(variables$strat)) NULL else data[variables$strat],
+    strata_data = if (is.null(variables$strata)) NULL else data[variables$strata],
     control = control
   )
   result_all$subgroup <- label_all
@@ -365,7 +374,7 @@ h_coxph_subgroups_df <- function(variables,
         tte = grp$df[[variables$tte]],
         is_event = grp$df[[variables$is_event]],
         arm = grp$df[[variables$arm]],
-        strata_data = if (is.null(variables$strat)) NULL else grp$df[variables$strat],
+        strata_data = if (is.null(variables$strata)) NULL else grp$df[variables$strata],
         control = control
       )
       result_labels <- grp$df_labels[rep(1, times = nrow(result)), ]

R/kaplan_meier_plot.R

@@ -13,7 +13,7 @@
 #'   * `tte` (`numeric`)\cr variable indicating time-to-event duration values.
 #'   * `is_event` (`logical`)\cr event variable. `TRUE` if event, `FALSE` if time to event is censored.
 #'   * `arm` (`factor`)\cr the treatment group variable.
-#'   * `strat` (`character` or `NULL`)\cr variable names indicating stratification factors.
+#'   * `strata` (`character` or `NULL`)\cr variable names indicating stratification factors.
 #' @param control_surv (`list`)\cr parameters for comparison details, specified by using
 #'   the helper function [control_surv_timepoint()]. Some possible parameter options are:
 #'   * `conf_level` (`proportion`)\cr confidence level of the interval for survival rate.
@@ -152,13 +152,13 @@
 #'
 #' # Change widths/sizes of surv_med and coxph annotation tables.
 #' g_km(
-#'   df = df, variables = c(variables, list(strat = "SEX")),
+#'   df = df, variables = c(variables, list(strata = "SEX")),
 #'   annot_coxph = TRUE,
 #'   width_annots = list(surv_med = grid::unit(2, "in"), coxph = grid::unit(3, "in"))
 #' )
 #'
 #' g_km(
-#'   df = df, variables = c(variables, list(strat = "SEX")),
+#'   df = df, variables = c(variables, list(strata = "SEX")),
 #'   font_size = 15,
 #'   annot_coxph = TRUE,
 #'   control_coxph = control_coxph(pval_method = "wald", ties = "exact", conf_level = 0.99),
@@ -167,7 +167,7 @@
 #'
 #' # Change position of the treatment group annotation table.
 #' g_km(
-#'   df = df, variables = c(variables, list(strat = "SEX")),
+#'   df = df, variables = c(variables, list(strata = "SEX")),
 #'   font_size = 15,
 #'   annot_coxph = TRUE,
 #'   control_coxph = control_coxph(pval_method = "wald", ties = "exact", conf_level = 0.99),
@@ -1359,6 +1359,15 @@ h_tbl_coxph_pairwise <- function(df,
                                  ref_group_coxph = NULL,
                                  control_coxph_pw = control_coxph(),
                                  annot_coxph_ref_lbls = FALSE) {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `h_tbl_coxph_pairwise() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
+
   assert_df_with_variables(df, variables)
   checkmate::assert_choice(ref_group_coxph, levels(df[[variables$arm]]), null.ok = TRUE)
   checkmate::assert_flag(annot_coxph_ref_lbls)
@@ -1376,7 +1385,7 @@ h_tbl_coxph_pairwise <- function(df,
       .in_ref_col = FALSE,
       .var = variables$tte,
       is_event = variables$is_event,
-      strat = variables$strat,
+      strata = variables$strata,
       control = control_coxph_pw
     )
     res_df <- data.frame(

R/prop_diff.R

@@ -494,7 +494,7 @@ prop_diff_cmh <- function(rsp,
 
   # first dimension: FALSE, TRUE
   # 2nd dimension: CONTROL, TX
-  # 3rd dimension: levels of strat
+  # 3rd dimension: levels of strata
   # rsp as factor rsp to handle edge case of no FALSE (or TRUE) rsp records
   t_tbl <- table(
     factor(rsp, levels = c("FALSE", "TRUE")),

R/prop_diff_test.R

@@ -117,15 +117,15 @@ a_test_proportion_diff <- make_afun(
 #' dta <- data.frame(
 #'   rsp = sample(c(TRUE, FALSE), 100, TRUE),
 #'   grp = factor(rep(c("A", "B"), each = 50)),
-#'   strat = factor(rep(c("V", "W", "X", "Y", "Z"), each = 20))
+#'   strata = factor(rep(c("V", "W", "X", "Y", "Z"), each = 20))
 #' )
 #'
 #' # With `rtables` pipelines.
 #' l <- basic_table() %>%
 #'   split_cols_by(var = "grp", ref_group = "B") %>%
 #'   test_proportion_diff(
 #'     vars = "rsp",
-#'     method = "cmh", variables = list(strata = "strat")
+#'     method = "cmh", variables = list(strata = "strata")
 #'   )
 #'
 #' build_table(l, df = dta)

R/response_biomarkers_subgroups.R

@@ -110,7 +110,7 @@ tabulate_rsp_biomarkers <- function(df,
 #' for multiple biomarkers across population subgroups in a single data frame.
 #' `variables` corresponds to the names of variables found in `data`, passed as a
 #' named list and requires elements `rsp` and `biomarkers` (vector of continuous
-#' biomarker variables) and optionally `covariates`, `subgroups` and `strat`.
+#' biomarker variables) and optionally `covariates`, `subgroups` and `strata`.
 #' `groups_lists` optionally specifies groupings for `subgroups` variables.
 #'
 #' @inheritParams argument_convention
@@ -163,7 +163,7 @@ tabulate_rsp_biomarkers <- function(df,
 #'     biomarkers = c("BMRKR1", "AGE"),
 #'     covariates = "SEX",
 #'     subgroups = "BMRKR2",
-#'     strat = "STRATA1"
+#'     strata = "STRATA1"
 #'   ),
 #'   data = adrs_f,
 #'   groups_lists = list(
@@ -185,6 +185,15 @@ extract_rsp_biomarkers <- function(variables,
                                    groups_lists = list(),
                                    control = control_logistic(),
                                    label_all = "All Patients") {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `extract_rsp_biomarkers() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
+
   assert_list_of_variables(variables)
   checkmate::assert_string(variables$rsp)
   checkmate::assert_character(variables$subgroups, null.ok = TRUE)

R/response_subgroups.R

@@ -39,7 +39,7 @@
 #'
 #' # Stratified analysis.
 #' df_strat <- extract_rsp_subgroups(
-#'   variables = list(rsp = "rsp", arm = "ARM", subgroups = c("SEX", "BMRKR2"), strat = "STRATA1"),
+#'   variables = list(rsp = "rsp", arm = "ARM", subgroups = c("SEX", "BMRKR2"), strata = "STRATA1"),
 #'   data = adrs_f
 #' )
 #' df_strat
@@ -69,7 +69,7 @@ NULL
 #' Prepares response rates and odds ratios for population subgroups in data frames. Simple wrapper
 #' for [h_odds_ratio_subgroups_df()] and [h_proportion_subgroups_df()]. Result is a list of two
 #' `data.frames`: `prop` and `or`. `variables` corresponds to the names of variables found in `data`,
-#' passed as a named `list` and requires elements `rsp`, `arm` and optionally `subgroups` and `strat`.
+#' passed as a named `list` and requires elements `rsp`, `arm` and optionally `subgroups` and `strata`.
 #' `groups_lists` optionally specifies groupings for `subgroups` variables.
 #'
 #' @inheritParams argument_convention
@@ -91,6 +91,15 @@ extract_rsp_subgroups <- function(variables,
                                   conf_level = 0.95,
                                   method = NULL,
                                   label_all = "All Patients") {
+  if ("strat" %in% names(variables)) {
+    warning(
+      "Warning: the `strat` element name of the `variables` list argument to `extract_rsp_subgroups() ",
+      "was deprecated in tern 0.9.3.\n  ",
+      "Please use the name `strata` instead of `strat` in the `variables` argument."
+    )
+    variables[["strata"]] <- variables[["strat"]]
+  }
+
   df_prop <- h_proportion_subgroups_df(
     variables,
     data,