diff --git a/NEWS.md b/NEWS.md index 779c90c47a..6803262b52 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,11 @@ # tern 0.9.4.9000 +### Enhancements +* Added examples and tests for `label_all` parameter to `extract_survival_biomarkers` and `extract_survival_subgroups`. + +### Miscellaneous +* Began deprecation of the unused `label_all` parameter to `tabulate_survival_biomarkers` and `tabulate_survival_subgroups`, with redirection to the same parameter in their associated `extract_*` functions. + # tern 0.9.4 ### New Features diff --git a/R/survival_biomarkers_subgroups.R b/R/survival_biomarkers_subgroups.R index 6ad185b539..3a6eec6691 100644 --- a/R/survival_biomarkers_subgroups.R +++ b/R/survival_biomarkers_subgroups.R @@ -53,6 +53,7 @@ #' covariates = "SEX", #' subgroups = "BMRKR2" #' ), +#' label_all = "Total Patients", #' data = adtte_f #' ) #' df @@ -162,6 +163,9 @@ extract_survival_biomarkers <- function(variables, #' @describeIn survival_biomarkers_subgroups Table-creating function which creates a table #' summarizing biomarker effects on survival by subgroup. #' +#' @param label_all `r lifecycle::badge("deprecated")`\cr please assign the `label_all` parameter within the +#' [extract_survival_biomarkers()] function when creating `df`. +#' #' @return An `rtables` table summarizing biomarker effects on survival by subgroup. #' #' @note In contrast to [tabulate_survival_subgroups()] this tabulation function does @@ -192,16 +196,26 @@ tabulate_survival_biomarkers <- function(df, vars = c("n_tot", "n_tot_events", "median", "hr", "ci", "pval"), groups_lists = list(), control = control_coxreg(), - label_all = "All Patients", + label_all = lifecycle::deprecated(), time_unit = NULL, na_str = default_na_str(), .indent_mods = 0L) { + if (lifecycle::is_present(label_all)) { + lifecycle::deprecate_warn( + "0.9.5", "tabulate_survival_biomarkers(label_all)", + details = paste( + "Please assign the `label_all` parameter within the", + "`extract_survival_biomarkers()` function when creating `df`." + ) + ) + } + checkmate::assert_data_frame(df) checkmate::assert_character(df$biomarker) checkmate::assert_character(df$biomarker_label) checkmate::assert_subset(vars, get_stats("tabulate_survival_biomarkers")) - extra_args <- list(groups_lists = groups_lists, control = control, label_all = label_all) + extra_args <- list(groups_lists = groups_lists, control = control) df_subs <- split(df, f = df$biomarker) tabs <- lapply(df_subs, FUN = function(df_sub) { diff --git a/R/survival_duration_subgroups.R b/R/survival_duration_subgroups.R index 3e64606842..0faf9b1ae3 100644 --- a/R/survival_duration_subgroups.R +++ b/R/survival_duration_subgroups.R @@ -28,7 +28,6 @@ #' #' @examples #' library(dplyr) -#' library(forcats) #' #' adtte <- tern_ex_adtte #' @@ -43,7 +42,7 @@ #' ) %>% #' mutate( #' # Reorder levels of ARM to display reference arm before treatment arm. -#' ARM = droplevels(fct_relevel(ARM, "B: Placebo")), +#' ARM = droplevels(forcats::fct_relevel(ARM, "B: Placebo")), #' SEX = droplevels(SEX), #' AVALU = as.character(AVALU), #' is_event = CNSR == 0 @@ -62,6 +61,7 @@ #' is_event = "is_event", #' arm = "ARM", subgroups = c("SEX", "BMRKR2") #' ), +#' label_all = "Total Patients", #' data = adtte_f #' ) #' df @@ -199,6 +199,10 @@ a_survival_subgroups <- function(.formats = list( # nolint start #' summarizing survival by subgroup. This function is a wrapper for [rtables::analyze_colvars()] #' and [rtables::summarize_row_groups()]. #' +#' @param label_all `r lifecycle::badge("deprecated")`\cr please assign the `label_all` parameter within the +#' [extract_survival_subgroups()] function when creating `df`. +#' +#' #' @return An `rtables` table summarizing survival by subgroup. #' #' @examples @@ -220,13 +224,21 @@ tabulate_survival_subgroups <- function(lyt, df, vars = c("n_tot_events", "n_events", "median", "hr", "ci"), groups_lists = list(), - label_all = "All Patients", + label_all = lifecycle::deprecated(), time_unit = NULL, na_str = default_na_str()) { + if (lifecycle::is_present(label_all)) { + lifecycle::deprecate_warn( + "0.9.5", "tabulate_survival_subgroups(label_all)", + details = + "Please assign the `label_all` parameter within the `extract_survival_subgroups()` function when creating `df`." + ) + } + conf_level <- df$hr$conf_level[1] method <- df$hr$pval_label[1] - extra_args <- list(groups_lists = groups_lists, conf_level = conf_level, method = method, label_all = label_all) + extra_args <- list(groups_lists = groups_lists, conf_level = conf_level, method = method) afun_lst <- a_survival_subgroups(na_str = na_str) colvars <- d_survival_subgroups_colvars( diff --git a/man/survival_biomarkers_subgroups.Rd b/man/survival_biomarkers_subgroups.Rd index 51168ca639..430a924c6e 100644 --- a/man/survival_biomarkers_subgroups.Rd +++ b/man/survival_biomarkers_subgroups.Rd @@ -10,7 +10,7 @@ tabulate_survival_biomarkers( vars = c("n_tot", "n_tot_events", "median", "hr", "ci", "pval"), groups_lists = list(), control = control_coxreg(), - label_all = "All Patients", + label_all = lifecycle::deprecated(), time_unit = NULL, na_str = default_na_str(), .indent_mods = 0L @@ -37,7 +37,8 @@ levels that belong to it in the character vectors that are elements of the list. \item{control}{(\code{list})\cr a list of parameters as returned by the helper function \code{\link[=control_coxreg]{control_coxreg()}}.} -\item{label_all}{(\code{string})\cr label for the total population analysis.} +\item{label_all}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}\cr please assign the \code{label_all} parameter within the +\code{\link[=extract_survival_biomarkers]{extract_survival_biomarkers()}} function when creating \code{df}.} \item{time_unit}{(\code{string})\cr label with unit of median survival time. Default \code{NULL} skips displaying unit.} @@ -101,6 +102,7 @@ df <- extract_survival_biomarkers( covariates = "SEX", subgroups = "BMRKR2" ), + label_all = "Total Patients", data = adtte_f ) df diff --git a/man/survival_duration_subgroups.Rd b/man/survival_duration_subgroups.Rd index 7d65bfdbf0..63f4aeded5 100644 --- a/man/survival_duration_subgroups.Rd +++ b/man/survival_duration_subgroups.Rd @@ -11,7 +11,7 @@ tabulate_survival_subgroups( df, vars = c("n_tot_events", "n_events", "median", "hr", "ci"), groups_lists = list(), - label_all = "All Patients", + label_all = lifecycle::deprecated(), time_unit = NULL, na_str = default_na_str() ) @@ -47,7 +47,8 @@ are required. 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.} -\item{label_all}{(\code{string})\cr label for the total population analysis.} +\item{label_all}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}\cr please assign the \code{label_all} parameter within the +\code{\link[=extract_survival_subgroups]{extract_survival_subgroups()}} function when creating \code{df}.} \item{time_unit}{(\code{string})\cr label with unit of median survival time. Default \code{NULL} skips displaying unit.} @@ -84,7 +85,6 @@ and \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. }} \examples{ library(dplyr) -library(forcats) adtte <- tern_ex_adtte @@ -99,7 +99,7 @@ adtte_f <- adtte \%>\% ) \%>\% mutate( # Reorder levels of ARM to display reference arm before treatment arm. - ARM = droplevels(fct_relevel(ARM, "B: Placebo")), + ARM = droplevels(forcats::fct_relevel(ARM, "B: Placebo")), SEX = droplevels(SEX), AVALU = as.character(AVALU), is_event = CNSR == 0 @@ -118,6 +118,7 @@ df <- extract_survival_subgroups( is_event = "is_event", arm = "ARM", subgroups = c("SEX", "BMRKR2") ), + label_all = "Total Patients", data = adtte_f ) df diff --git a/tests/testthat/_snaps/survival_biomarkers_subgroups.md b/tests/testthat/_snaps/survival_biomarkers_subgroups.md index d9873da11c..04618f96ab 100644 --- a/tests/testthat/_snaps/survival_biomarkers_subgroups.md +++ b/tests/testthat/_snaps/survival_biomarkers_subgroups.md @@ -148,3 +148,29 @@ MEDIUM 68 42 859.0 0.97 (0.89, 1.06) 0.5218 HIGH 62 47 727.8 1.06 (0.96, 1.17) 0.2239 +# label_all argument to extract_survival_subgroups works as expected + + Code + res + Output + Total n Total Events Median (DAYS) Hazard Ratio 95% Wald CI p-value (Wald) + —————————————————————————————————————————————————————————————————————————————————————————————————————————————————————— + Age + Full Analysis Set 200 141 753.5 1.01 (0.99, 1.04) 0.3432 + Sex + F 110 79 685.2 1.00 (0.96, 1.03) 0.8808 + M 90 62 888.5 1.02 (0.99, 1.05) 0.1974 + Continuous Level Biomarker 2 + LOW 70 52 735.5 1.01 (0.97, 1.06) 0.5584 + MEDIUM 68 42 859.0 1.03 (0.98, 1.09) 0.2532 + HIGH 62 47 727.8 1.00 (0.96, 1.03) 0.8292 + Continuous Level Biomarker 1 + Full Analysis Set 200 141 753.5 1.00 (0.95, 1.05) 0.9590 + Sex + F 110 79 685.2 1.01 (0.96, 1.07) 0.6215 + M 90 62 888.5 0.98 (0.90, 1.07) 0.6939 + Continuous Level Biomarker 2 + LOW 70 52 735.5 1.00 (0.92, 1.08) 0.9833 + MEDIUM 68 42 859.0 0.97 (0.89, 1.06) 0.5218 + HIGH 62 47 727.8 1.06 (0.96, 1.17) 0.2239 + diff --git a/tests/testthat/_snaps/survival_duration_subgroups.md b/tests/testthat/_snaps/survival_duration_subgroups.md index aed810bfbb..f8628484a1 100644 --- a/tests/testthat/_snaps/survival_duration_subgroups.md +++ b/tests/testthat/_snaps/survival_duration_subgroups.md @@ -223,3 +223,20 @@ MEDIUM 31 14 731.8 17 964.2 (0.36, 1.61) HIGH 34 22 654.8 12 1016.3 0.67 (0.33, 1.36) +# label_all argument to extract_survival_subgroups works as expected + + Code + res + Output + B: Placebo A: Drug X + Baseline Risk Factors Total Events Events Median (DAYS) Events Median (DAYS) Hazard Ratio 95% Wald CI + ——————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————— + Full Analysis Set 101 57 727.8 44 974.6 0.71 (0.48, 1.06) + Sex + F 55 31 599.2 24 1016.3 0.56 (0.32, 0.96) + M 46 26 888.5 20 974.6 0.91 (0.50, 1.65) + Continuous Level Biomarker 2 + LOW 36 21 735.5 15 974.6 0.76 (0.39, 1.51) + MEDIUM 31 14 731.8 17 964.2 0.77 (0.36, 1.61) + HIGH 34 22 654.8 12 1016.3 0.67 (0.33, 1.36) + diff --git a/tests/testthat/test-survival_biomarkers_subgroups.R b/tests/testthat/test-survival_biomarkers_subgroups.R index e27a209d06..95bfc27e7b 100644 --- a/tests/testthat/test-survival_biomarkers_subgroups.R +++ b/tests/testthat/test-survival_biomarkers_subgroups.R @@ -152,3 +152,28 @@ testthat::test_that("tabulate_survival_biomarkers na_str argument works as expec res <- testthat::expect_silent(result) testthat::expect_snapshot(res) }) + +testthat::test_that("label_all argument to extract_survival_subgroups works as expected", { + adtte_f <- adtte_local + + df <- extract_survival_biomarkers( + variables = list( + tte = "AVAL", + is_event = "is_event", + biomarkers = c("AGE", "BMRKR1"), + subgroups = c("SEX", "BMRKR2") + ), + data = adtte_f, + label_all = "Full Analysis Set" + ) + + lifecycle::expect_deprecated( + result <- tabulate_survival_biomarkers( + df, + time_unit = as.character(adtte_f$AVALU[1]), label_all = "Full Analysis Set" + ) + ) + + res <- testthat::expect_silent(result) + testthat::expect_snapshot(res) +}) diff --git a/tests/testthat/test-survival_duration_subgroups.R b/tests/testthat/test-survival_duration_subgroups.R index feb3728e4d..cb893927fb 100644 --- a/tests/testthat/test-survival_duration_subgroups.R +++ b/tests/testthat/test-survival_duration_subgroups.R @@ -229,3 +229,21 @@ testthat::test_that("tabulate_survival_subgroups na_str argument works as expect res <- testthat::expect_silent(result) testthat::expect_snapshot(res) }) + +testthat::test_that("label_all argument to extract_survival_subgroups works as expected", { + adtte <- adtte_local + + df <- extract_survival_subgroups( + variables = list(tte = "AVAL", is_event = "is_event", arm = "ARM", subgroups = c("SEX", "BMRKR2")), + data = adtte, + label_all = "Full Analysis Set" + ) + + lifecycle::expect_deprecated( + result <- basic_table() %>% + tabulate_survival_subgroups(df, time_unit = adtte$AVALU[1], label_all = "Full Analysis Set") + ) + + res <- testthat::expect_silent(result) + testthat::expect_snapshot(res) +})