Add nested argument to all analyze wrapper functions

NEWS.md

@@ -6,6 +6,7 @@
 * Added `ylim` argument to `g_km` to allow the user to set custom limits for the y-axis.
 * Added assertion to `g_km` which checks whether there is one arm present in the data when `annot_coxph` is true.
 * Added `flag_labels` argument to `s_count_patients_with_flags` to enable more label handling options in `count_patients_by_flags`. 
+* Added the `nested` argument to `analyze` wrapper functions `count_abnormal`, `count_abnormal_by_baseline`, `count_abnormal_by_marked`, `count_abnormal_by_worst_grade`, `count_abnormal_lab_worsen_by_baseline`, `count_cumulative`, `count_missed_doses`, `count_occurrences`, `count_occurrences_by_grade`, `count_patients_with_event`, `count_patients_with_flags`, `count_values`, `estimate_multinomial_response`, `estimate_proportion`, `estimate_incidence_rate`, `estimate_odds_ratio`, `estimate_proportion_diff`, `test_proportion_diff`, `summarize_ancova`, `summarize_change`, `summarize_glm_count`, `analyze_num_patients`, `coxph_pairwise`, `surv_time`, and `surv_timepoint`.
 
 ### Miscellaneous
 * Started deprecation cycle for `summarize_vars` and `control_summarize_vars`. Renamed into `analyze_vars` and `control_analyze_vars` to reflect underlying `rtables` machinery while keeping backward compatibility with aliases.

R/abnormal.R

@@ -3,7 +3,7 @@
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Primary analysis variable `.var` indicates the abnormal range result (`character` or `factor`)
 #' and additional analysis variables are `id` (`character` or `factor`) and `baseline` (`character` or
 #' `factor`). For each direction specified in `abnormal` (e.g. high or low) count patients in the
 #' numerator and denominator as follows:
 #'   * `num` : The number of patients with this abnormality recorded while on treatment.
@@ -15,8 +15,8 @@
 #'   for example, `abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH"))`.
 #'
 #' @note
 #' * `count_abnormal()` only works with a single variable containing multiple abnormal levels.
 #' * `df` should be filtered to include only post-baseline records.
 #' * the denominator includes patients that might have other abnormal levels at baseline,
 #'   and patients with missing baseline. Patients with these abnormalities at
 #'   baseline can be optionally excluded from numerator and denominator.
@@ -44,7 +44,7 @@
 #'   stringsAsFactors = FALSE
 #' )
 #'
 #' # Select only post-baseline records.
 #' df <- df %>%
 #'   filter(ONTRTFL == "Y")
 #' @keywords internal
@@ -103,7 +103,7 @@
 )
 
 #' @describeIn abnormal Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_abnormal()` returns a layout object suitable for passing to further layouting functions,
@@ -125,7 +125,7 @@
 #'   stringsAsFactors = FALSE
 #' )
 #'
 #' # Select only post-baseline records.
 #' df2 <- df2 %>%
 #'   filter(ONTRTFL == "Y")
 #'
@@ -140,6 +140,7 @@
 #' @export
 count_abnormal <- function(lyt,
                            var,
+                           nested = TRUE,
                            ...,
                            table_names = var,
                            .stats = NULL,
@@ -161,6 +162,7 @@
     lyt = lyt,
     vars = var,
     afun = afun,
+    nested = nested,
     table_names = table_names,
     extra_args = list(...),
     show_labels = "hidden"

R/abnormal_by_baseline.R

@@ -2,7 +2,7 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Primary analysis variable `.var` indicates the abnormal range result (`character` or `factor`), and additional
 #' analysis variables are `id` (`character` or `factor`) and `baseline` (`character` or `factor`). For each
 #' direction specified in `abnormal` (e.g. high or low) we condition on baseline range result and count
 #' patients in the numerator and denominator as follows:
@@ -20,8 +20,8 @@
 #' @param abnormal (`character`)\cr identifying the abnormal range level(s) in `.var`.
 #'
 #' @note
 #' * `df` should be filtered to include only post-baseline records.
 #' * If the baseline variable or analysis variable contains `NA`, it is expected that `NA` has been
 #'   conveyed to `na_level` appropriately beforehand with [df_explicit_na()] or [explicit_na()].
 #'
 #' @seealso Relevant description function [d_count_abnormal_by_baseline()].
@@ -57,7 +57,7 @@
 
 #' @describeIn abnormal_by_baseline Statistics function for a single `abnormal` level.
 #'
 #' @param na_level (`string`)\cr the explicit `na_level` argument you used in the pre-processing steps (maybe with
 #'   [df_explicit_na()]). The default is `"<Missing>"`.
 #'
 #' @return
@@ -87,7 +87,7 @@
   assert_valid_factor(df[[.var]], any.missing = FALSE)
   assert_valid_factor(df[[variables$baseline]], any.missing = FALSE)
 
   # Keep only records with valid analysis value.
   df <- df[df[[.var]] != na_level, ]
 
   anl <- data.frame(
@@ -103,7 +103,7 @@
   total_denom <- length(unique(anl$id))
   total_num <- length(unique(anl$id[anl$var == abnormal]))
 
   # Baseline NA records are counted only in total rows.
   anl <- anl[anl$baseline != na_level, ]
 
   # Abnormal:
@@ -142,7 +142,7 @@
 )
 
 #' @describeIn abnormal_by_baseline Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_abnormal_by_baseline()` returns a layout object suitable for passing to further layouting functions,
@@ -166,7 +166,7 @@
 #' df2 <- data.frame(
 #'   ID = as.character(c(1, 2, 3, 4)),
 #'   RANGE = factor(c("NORMAL", "LOW", "HIGH", "HIGH")),
 #'   BLRANGE = factor(c("LOW", "HIGH", "HIGH", "NORMAL"))
 #' )
 #'
 #' basic_table() %>%
@@ -183,6 +183,7 @@
 count_abnormal_by_baseline <- function(lyt,
                                        var,
                                        abnormal,
+                                       nested = TRUE,
                                        ...,
                                        table_names = abnormal,
                                        .stats = NULL,
@@ -206,6 +207,7 @@
       vars = var,
       var_labels = names(abn),
       afun = afun,
+      nested = nested,
       table_names = table_names[i],
       extra_args = c(list(abnormal = abn), list(...)),
       show_labels = "visible"

R/abnormal_by_marked.R

@@ -3,7 +3,7 @@
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Primary analysis variable `.var` indicates whether single, replicated or last marked laboratory
 #' abnormality was observed (`factor`). Additional analysis variables are `id` (`character` or `factor`)
 #' and `direction` (`factor`) indicating the direction of the abnormality. Denominator is number of
 #' patients with at least one valid measurement during the analysis.
 #'   * For `Single, not last` and `Last or replicated`: Numerator is number of patients
@@ -17,7 +17,7 @@
 #'
 #' @note `Single, not last` and `Last or replicated` levels are mutually exclusive. If a patient has
 #'   abnormalities that meet both the `Single, not last` and `Last or replicated` criteria, then the
 #'   patient will be counted only under the `Last or replicated` category.
 #'
 #' @name abnormal_by_marked
 NULL
@@ -35,11 +35,11 @@
 #'   USUBJID = as.character(c(rep(1, 5), rep(2, 5), rep(1, 5), rep(2, 5))),
 #'   ARMCD = factor(c(rep("ARM A", 5), rep("ARM B", 5), rep("ARM A", 5), rep("ARM B", 5))),
 #'   ANRIND = factor(c(
 #'     "NORMAL", "HIGH", "HIGH", "HIGH HIGH", "HIGH",
 #'     "HIGH", "HIGH", "HIGH HIGH", "NORMAL", "HIGH HIGH", "NORMAL", "LOW", "LOW", "LOW LOW", "LOW",
 #'     "LOW", "LOW", "LOW LOW", "NORMAL", "LOW LOW"
 #'   )),
 #'   ONTRTFL = rep(c("", "Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y"), 2),
 #'   PARAMCD = factor(c(rep("CRP", 10), rep("ALT", 10))),
 #'   AVALCAT1 = factor(rep(c("", "", "", "SINGLE", "REPLICATED", "", "", "LAST", "", "SINGLE"), 2)),
 #'   stringsAsFactors = FALSE
@@ -55,7 +55,7 @@
 #'     levels = c("Low", "High")
 #'   ))
 #'
 #' # Select only post-baseline records.
 #' df <- df %>% filter(ONTRTFL == "Y")
 #' df_crp <- df %>%
 #'   filter(PARAMCD == "CRP") %>%
@@ -91,7 +91,7 @@
   subj <- first_row$full_parent_df[[1]][[variables[["id"]]]]
   subj_cur_col <- subj[first_row$cur_col_subset[[1]]]
   # Some subjects may have a record for high and low directions but
   # should be counted only once.
   denom <- length(unique(subj_cur_col))
 
   if (denom != 0) {
@@ -101,7 +101,7 @@
     subjects_single <- unique(
       df[df[[.var]] %in% category[["single"]], variables$id, drop = TRUE]
     )
     # Subjects who have both single and last/replicated abnormalities are counted in only the last/replicated group.
     subjects_single <- setdiff(subjects_single, subjects_last_replicated)
     n_single <- length(subjects_single)
     n_last_replicated <- length(subjects_last_replicated)
@@ -136,7 +136,7 @@
 )
 
 #' @describeIn abnormal_by_marked Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_abnormal_by_marked()` returns a layout object suitable for passing to further layouting functions,
@@ -196,6 +196,7 @@
 #' @export
 count_abnormal_by_marked <- function(lyt,
                                      var,
+                                     nested = TRUE,
                                      ...,
                                      .stats = NULL,
                                      .formats = NULL,
@@ -216,6 +217,7 @@
     lyt = lyt,
     vars = var,
     afun = afun,
+    nested = nested,
     show_labels = "hidden",
     extra_args = c(list(...))
   )

R/abnormal_by_worst_grade.R

@@ -2,7 +2,7 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Primary analysis variable `.var` indicates the toxicity grade (`factor`), and additional
 #' analysis variables are `id` (`character` or `factor`), `param` (`factor`) and `grade_dir` (`factor`).
 #' The pre-processing steps are crucial when using this function.
 #' For a certain direction (e.g. high or low) this function counts
@@ -15,12 +15,12 @@
 #'
 #' @details The pre-processing steps are crucial when using this function. From the standard lab grade variable
 #'   `ATOXGR`, derive the following two variables:
 #'   * A grade direction variable (e.g. `GRADE_DIR`) is required in order to obtain
 #'     the correct denominators when building the layout as it is used to define row splitting.
 #'   * A toxicity grade variable (e.g. `GRADE_ANL`) where all negative values from
 #'     `ATOXGR` are replaced by their absolute values.
 #'
 #' @note Prior to tabulation, `df` must be filtered to include only post-baseline records with worst grade flags.
 #'
 #' @name abnormal_by_worst_grade
 NULL
@@ -36,7 +36,7 @@
 #' library(forcats)
 #' adlb <- tern_ex_adlb
 #'
 #' # Data is modified in order to have some parameters with grades only in one direction
 #' # and simulate the real data.
 #' adlb$ATOXGR[adlb$PARAMCD == "ALT" & adlb$ATOXGR %in% c("1", "2", "3", "4")] <- "-1"
 #' adlb$ANRIND[adlb$PARAMCD == "ALT" & adlb$ANRIND == "HIGH"] <- "LOW"
@@ -104,7 +104,7 @@
   subj <- first_row$full_parent_df[[1]][[variables[["id"]]]]
   subj_cur_col <- subj[first_row$cur_col_subset[[1]]]
   # Some subjects may have a record for high and low directions but
   # should be counted only once.
   denom <- length(unique(subj_cur_col))
 
   for (lvl in x_lvls) {
@@ -114,7 +114,7 @@
       df_lvl <- df[df[[.var]] != 0, ]
     }
     num <- length(unique(df_lvl[["USUBJID"]]))
     fraction <- ifelse(denom == 0, 0, num / denom)
     result[[lvl]] <- formatters::with_label(c(count = num, fraction = fraction), lvl)
   }
 
@@ -136,7 +136,7 @@
 )
 
 #' @describeIn abnormal_by_worst_grade Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_abnormal_by_worst_grade()` returns a layout object suitable for passing to further layouting functions,
@@ -164,6 +164,7 @@
 #' @export
 count_abnormal_by_worst_grade <- function(lyt,
                                           var,
+                                          nested = TRUE,
                                           ...,
                                           .stats = NULL,
                                           .formats = NULL,
@@ -181,6 +182,7 @@
     lyt = lyt,
     vars = var,
     afun = afun,
+    nested = nested,
     extra_args = list(...),
     show_labels = "hidden"
   )

R/abnormal_by_worst_grade_worsen.R

@@ -21,15 +21,15 @@
 #' @param worst_flag_low (named `vector`)\cr Worst low post-baseline lab grade flag variable
 #' @param worst_flag_high (named `vector`)\cr Worst high post-baseline lab grade flag variable
 #' @param direction_var (`string`)\cr Direction variable specifying the direction of the shift table of interest.
 #'   Only lab records flagged by `L`, `H` or `B` are included in the shift table.
 #'   * `L`: low direction only
 #'   * `H`: high direction only
 #'   * `B`: both low and high directions
 #'
 #' @return `h_adlb_worsen()` returns the `adlb` `data.frame` containing only the
 #'   worst labs specified according to `worst_flag_low` or `worst_flag_high` for the
 #'   direction specified according to `direction_var`. For instance, for a lab that is
 #'   needed for the low direction only, only records flagged by `worst_flag_low` are
 #'   selected. For a lab that is needed for both low and high directions, the worst
 #'   low records are selected for the low direction, and the worst high record are selected
 #'   for the high direction.
@@ -207,7 +207,7 @@
   # remove post-baseline missing
   df <- df[df[[.var]] != "<Missing>", ]
 
   # obtain directionality
   direction <- unique(df[[direction_var]])
 
   if (direction == "Low") {
@@ -254,7 +254,7 @@
     con2 <- which(as.numeric(as.character(df_temp_nm[[.var]])) > as.numeric(as.character(df_temp_nm[[baseline_var]])))
   }
 
   # number of patients satisfy either conditions 1 or 2
   num <- length(unique(df_temp[union(con1, con2), id, drop = TRUE]))
 
   list(fraction = c(by_grade, list("Any" = c(num = num, denom = denom))))
@@ -263,7 +263,7 @@
 #' @describeIn abnormal_by_worst_grade_worsen Statistics function for patients whose worst post-baseline
 #'   lab grades are worse than their baseline grades.
 #'
 #' @param variables (named `list` of `string`)\cr list of additional analysis variables including:
 #'   * `id` (`string`)\cr subject variable name.
 #'   * `baseline_var` (`string`)\cr name of the data column containing baseline toxicity variable.
 #'   * `direction_var` (`string`)\cr see `direction_var` for more details.
@@ -329,7 +329,7 @@
 )
 
 #' @describeIn abnormal_by_worst_grade_worsen Layout-creating function which can take statistics function
 #'   arguments and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_abnormal_lab_worsen_by_baseline()` returns a layout object suitable for passing to further layouting
@@ -356,6 +356,7 @@
 #' @export
 count_abnormal_lab_worsen_by_baseline <- function(lyt, # nolint
                                                   var,
+                                                  nested = TRUE,
                                                   ...,
                                                   table_names = NULL,
                                                   .stats = NULL,
@@ -376,6 +377,7 @@
     lyt = lyt,
     vars = var,
     afun = afun,
+    nested = nested,
     extra_args = list(...),
     show_labels = "hidden"
   )

R/argument_convention.R

@@ -1,10 +1,10 @@
 #' Standard Arguments
 #'
 #' The documentation to this function lists all the arguments in `tern`
 #' that are used repeatedly to express an analysis.
 #'
 #' @param ... additional arguments for the lower level functions.
 #' @param .df_row (`data.frame`)\cr data frame across all of the columns for the given row split.
 #' @param .in_ref_col (`logical`)\cr `TRUE` when working with the reference level, `FALSE` otherwise.
 #' @param .N_col (`count`)\cr row-wise N (row group count) for the group of observations being analyzed
 #'   (i.e. with no column-based subsetting) that is passed by `rtables`.
@@ -31,32 +31,32 @@
 #' @param id (`string`)\cr subject variable name.
 #' @param is_event (`logical`)\cr `TRUE` if event, `FALSE` if time to event is censored.
 #' @param indent_mod `r lifecycle::badge("deprecated")` Please use the `.indent_mods` argument instead.
 #' @param labelstr (`character`)\cr 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.
 #' @param lyt (`layout`)\cr input layout where analyses will be added to.
 #' @param na.rm (`flag`)\cr whether `NA` values should be removed from `x` prior to analysis.
 #' @param na_level (`string`)\cr string used to replace all `NA` or empty values in the output.
-#' @param nested (`flag`)\cr whether this layout instruction be applied within the existing layout structure _if
-#'   possible_ (`TRUE`, the default) or as a new top-level element (`FALSE`). Ignored if it would nest a split
+#' @param nested (`flag`)\cr whether this layout instruction should be applied within the existing layout structure _if
+#'   possible_ (`TRUE`, the default) or as a new top-level element (`FALSE`). Ignored if it would nest a split.
 #'   underneath analyses, which is not allowed.
 #' @param newpage (`flag`)\cr whether the plot should be drawn on a new page.
 #'   Only considered if `draw = TRUE` is used.
 #' @param prune_zero_rows (`flag`)\cr whether to prune all zero rows.
 #' @param rsp (`logical`)\cr whether each subject is a responder or not.
 #' @param show_labels (`string`)\cr label visibility: one of "default", "visible" and "hidden".
 #' @param section_div (`string`)\cr string which should be repeated as a section divider after each group
 #'   defined by this split instruction, or `NA_character_` (the default) for no section divider.
 #' @param table_names (`character`)\cr this can be customized in case that the same `vars` are analyzed multiple times,
 #'   to avoid warnings from `rtables`.
 #' @param tte (`numeric`)\cr contains time-to-event duration values.
 #' @param var_labels (`character`)\cr character for label.
 #' @param variables (named `list` of `string`)\cr list of additional analysis variables.
 #' @param vars (`character`)\cr variable names for the primary analysis variable to be iterated over.
 #' @param var (`string`)\cr single variable name for the primary analysis variable.
 #' @param x (`numeric`)\cr vector of numbers we want to analyze.
 #'
 #' @details Although this function just returns `NULL` it has two uses, for
 #'   the `tern` users it provides a documentation of arguments that are
 #'   commonly and consistently used in the framework. For the developer it adds a
 #'   single reference point to import the `roxygen` argument description with:

R/count_cumulative.R

@@ -129,7 +129,7 @@
 )
 
 #' @describeIn count_cumulative Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_cumulative()` returns a layout object suitable for passing to further layouting functions,
@@ -151,6 +151,7 @@
                              vars,
                              var_labels = vars,
                              show_labels = "visible",
+                             nested = TRUE,
                              ...,
                              table_names = vars,
                              .stats = NULL,
@@ -172,6 +173,7 @@
     table_names = table_names,
     var_labels = var_labels,
     show_labels = show_labels,
+    nested = nested,
     extra_args = list(...)
   )
 }

R/count_missed_doses.R

@@ -80,7 +80,7 @@
 )
 
 #' @describeIn count_missed_doses Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @inheritParams s_count_cumulative
 #'
@@ -112,6 +112,7 @@
                                vars,
                                var_labels = vars,
                                show_labels = "visible",
+                               nested = TRUE,
                                ...,
                                table_names = vars,
                                .stats = NULL,
@@ -133,6 +134,7 @@
     var_labels = var_labels,
     table_names = table_names,
     show_labels = show_labels,
+    nested = nested,
     extra_args = list(...)
   )
 }

R/count_occurrences.R

@@ -4,13 +4,13 @@
 #'
 #' Functions for analyzing frequencies and fractions of occurrences for patients with occurrence
 #' data. Primary analysis variables are the dictionary terms. All occurrences are counted for total
 #' counts. Multiple occurrences within patient at the lowest term level displayed in the table are
 #' counted only once.
 #'
 #' @inheritParams argument_convention
 #'
 #' @note By default, occurrences which don't appear in a given row split are dropped from the table and
 #'   the occurrences in the table are sorted alphabetically per row split. Therefore, the corresponding layout
 #'   needs to use `split_fun = drop_split_levels` in the `split_rows_by` calls. Use `drop = FALSE` if you would
 #'   like to show all occurrences.
 #'
@@ -32,8 +32,8 @@
 #'
 #' @examples
 #' df <- data.frame(
 #'   USUBJID = as.character(c(1, 1, 2, 4, 4, 4)),
 #'   MHDECOD = c("MH1", "MH2", "MH1", "MH1", "MH1", "MH3")
 #' )
 #'
 #' N_per_col <- 4L
@@ -112,7 +112,7 @@
 #'
 #' @examples
 #' #  We need to ungroup `count_fraction` first so that the `rtables` formatting
 #' # function `format_count_fraction()` can be applied correctly.
 #' afun <- make_afun(a_count_occurrences, .ungroup_stats = c("count", "count_fraction", "fraction"))
 #' afun(
 #'   df,
@@ -129,7 +129,7 @@
 )
 
 #' @describeIn count_occurrences Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_occurrences()` returns a layout object suitable for passing to further layouting functions,
@@ -140,12 +140,12 @@
 #' library(dplyr)
 #' df <- data.frame(
 #'   USUBJID = as.character(c(
 #'     1, 1, 2, 4, 4, 4,
 #'     6, 6, 6, 7, 7, 8
 #'   )),
 #'   MHDECOD = c(
 #'     "MH1", "MH2", "MH1", "MH1", "MH1", "MH3",
 #'     "MH2", "MH2", "MH3", "MH1", "MH2", "MH4"
 #'   ),
 #'   ARM = rep(c("A", "B"), each = 6)
 #' )
@@ -169,6 +169,7 @@
                               vars,
                               var_labels = vars,
                               show_labels = "hidden",
+                              nested = TRUE,
                               ...,
                               table_names = vars,
                               .stats = "count_fraction",
@@ -191,6 +192,7 @@
     var_labels = var_labels,
     show_labels = show_labels,
     table_names = table_names,
+    nested = nested,
     extra_args = list(...)
   )
 }

R/count_occurrences_by_grade.R

@@ -3,13 +3,13 @@
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Functions for analyzing frequencies and fractions of occurrences by grade for patients
 #' with occurrence data. Multiple occurrences within one individual are counted once at the
 #' greatest intensity/highest grade level.
 #'
 #' @inheritParams argument_convention
 #' @param grade_groups (named `list` of `character`)\cr containing groupings of grades.
 #' @param remove_single (`logical`)\cr `TRUE` to not include the elements of one-element grade groups
 #'   in the the output list; in this case only the grade groups names will be included in the output.
 #'
 #' @seealso Relevant helper function [h_append_grade_groups()].
 #'
@@ -121,10 +121,10 @@
 #' library(dplyr)
 #' df <- data.frame(
 #'   USUBJID = as.character(c(1:6, 1)),
 #'   ARM = factor(c("A", "A", "A", "B", "B", "B", "A"), levels = c("A", "B")),
 #'   AETOXGR = factor(c(1, 2, 3, 4, 1, 2, 3), levels = c(1:5)),
 #'   AESEV = factor(
 #'     x = c("MILD", "MODERATE", "SEVERE", "MILD", "MILD", "MODERATE", "SEVERE"),
 #'     levels = c("MILD", "MODERATE", "SEVERE")
 #'   ),
 #'   stringsAsFactors = FALSE
@@ -179,7 +179,7 @@
       grade <- formatters::with_label(factor(grade, levels = lvl_ord, ordered = TRUE), grade_lbl)
     }
 
     df_max <- stats::aggregate(grade ~ id, FUN = max, drop = FALSE)
     l_count <- as.list(table(df_max$grade))
   }
 
@@ -202,7 +202,7 @@
 #'
 #' @examples
 #' #  We need to ungroup `count_fraction` first so that the `rtables` formatting
 #' # function `format_count_fraction()` can be applied correctly.
 #' afun <- make_afun(a_count_occurrences_by_grade, .ungroup_stats = "count_fraction")
 #' afun(
 #'   df,
@@ -219,7 +219,7 @@
 )
 
 #' @describeIn count_occurrences_by_grade Layout-creating function which can take statistics function
 #'   arguments and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @param var_labels (`character`)\cr labels to show in the result table.
 #'
@@ -239,7 +239,7 @@
 #'   ) %>%
 #'   build_table(df, alt_counts_df = df_adsl)
 #'
 #' # Define additional grade groupings.
 #' grade_groups <- list(
 #'   "-Any-" = c("1", "2", "3", "4", "5"),
 #'   "Grade 1-2" = c("1", "2"),
@@ -260,6 +260,7 @@
                                        var,
                                        var_labels = var,
                                        show_labels = "default",
+                                       nested = TRUE,
                                        ...,
                                        table_names = var,
                                        .stats = NULL,
@@ -281,12 +282,13 @@
     show_labels = show_labels,
     afun = afun,
     table_names = table_names,
+    nested = nested,
     extra_args = list(...)
   )
 }
 
 #' @describeIn count_occurrences_by_grade Layout-creating function which can take content function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::summarize_row_groups()].
 #'
 #' @return
 #' * `summarize_occurrences_by_grade()` returns a layout object suitable for passing to further layouting functions,

R/count_patients_with_event.R

@@ -18,9 +18,9 @@
 #' @param .var (`character`)\cr name of the column that contains the unique identifier.
 #' @param filters (`character`)\cr a character vector specifying the column names and flag variables
 #'   to be used for counting the number of unique identifiers satisfying such conditions.
 #'   Multiple column names and flags are accepted in this format
 #'   `c("column_name1" = "flag1", "column_name2" = "flag2")`.
 #'   Note that only equality is being accepted as condition.
 #'
 #' @return
 #' * `s_count_patients_with_event()` returns the count and fraction of unique identifiers with the defined event.
@@ -101,7 +101,7 @@
 )
 
 #' @describeIn count_patients_with_event Layout-creating function which can take statistics function
 #'   arguments and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_patients_with_event()` returns a layout object suitable for passing to further layouting functions,
@@ -144,6 +144,7 @@
 #' @export
 count_patients_with_event <- function(lyt,
                                       vars,
+                                      nested = TRUE,
                                       ...,
                                       table_names = vars,
                                       .stats = "count_fraction",
@@ -162,6 +163,7 @@
     lyt,
     vars,
     afun = afun,
+    nested = nested,
     extra_args = list(...),
     show_labels = ifelse(length(vars) > 1, "visible", "hidden"),
     table_names = table_names

R/count_patients_with_flags.R

@@ -21,7 +21,7 @@
 #' @param flag_labels (`character`)\cr vector of labels to use for flag variables.
 #'
 #' @note If `flag_labels` is not specified, variables labels will be extracted from `df`. If variables are not
 #'   labeled, variable names will be used instead. Alternatively, a named `vector` can be supplied to
 #'   `flag_variables` such that within each name-value pair the name corresponds to the variable name and the value is
 #'   the label to use for this variable.
 #'
@@ -109,7 +109,7 @@
 #'
 #' @examples
 #' #  We need to ungroup `count_fraction` first so that the `rtables` formatting
 #' # function `format_count_fraction()` can be applied correctly.
 #'
 #' # `a_count_patients_with_flags()`
 #'
@@ -132,7 +132,7 @@
 )
 
 #' @describeIn count_patients_with_flags Layout-creating function which can take statistics function
 #'   arguments and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_patients_with_flags()` returns a layout object suitable for passing to further layouting functions,
@@ -157,6 +157,7 @@
                                       var,
                                       var_labels = var,
                                       show_labels = "hidden",
+                                      nested = TRUE,
                                       ...,
                                       table_names = paste0("tbl_flags_", var),
                                       .stats = "count_fraction",
@@ -177,6 +178,7 @@
     show_labels = show_labels,
     afun = afun,
     table_names = table_names,
+    nested = nested,
     extra_args = list(...)
   )
 

R/count_values.R

@@ -105,7 +105,7 @@
 )
 
 #' @describeIn count_values_funs Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `count_values()` returns a layout object suitable for passing to further layouting functions,
@@ -122,6 +122,7 @@
 count_values <- function(lyt,
                          vars,
                          values,
+                         nested = TRUE,
                          ...,
                          table_names = vars,
                          .stats = "count_fraction",
@@ -139,6 +140,7 @@
     lyt,
     vars,
     afun = afun,
+    nested = nested,
     extra_args = c(list(values = values), list(...)),
     show_labels = ifelse(length(vars) > 1, "visible", "hidden"),
     table_names = table_names

R/estimate_multinomial_rsp.R

@@ -3,7 +3,7 @@
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Estimate the proportion along with confidence interval of a proportion
 #' regarding the level of a factor.
 #'
 #' @inheritParams argument_convention
 #'
@@ -108,7 +108,7 @@
 )
 
 #' @describeIn estimate_multinomial_rsp Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()] and
 #'   [rtables::summarize_row_groups()].
 #'
 #' @return
@@ -123,7 +123,7 @@
 #' dta_test <- data.frame(
 #'   USUBJID = paste0("S", 1:12),
 #'   ARM     = factor(rep(LETTERS[1:3], each = 4)),
 #'   AVAL    = c(A = c(1, 1, 1, 1), B = c(0, 0, 1, 1), C = c(0, 0, 0, 0))
 #' ) %>% mutate(
 #'   AVALC = factor(AVAL,
 #'     levels = c(0, 1),
@@ -146,6 +146,7 @@
 #' @export
 estimate_multinomial_response <- function(lyt,
                                           var,
+                                          nested = TRUE,
                                           ...,
                                           show_labels = "hidden",
                                           table_names = var,
@@ -169,6 +170,7 @@
     afun = afun,
     show_labels = show_labels,
     table_names = table_names,
+    nested = nested,
     extra_args = list(...)
   )
 }

R/estimate_proportion.R

@@ -15,11 +15,11 @@
 #'   proportion along with its confidence interval.
 #'
 #' @inheritParams prop_strat_wilson
 #' @param df (`logical` or `data.frame`)\cr if only a logical vector is used,
 #'   it indicates whether each subject is a responder or not. `TRUE` represents
 #'   a successful outcome. If a `data.frame` is provided, also the `strata` variable
 #'   names must be provided in `variables` as a list element with the strata strings.
 #'   In the case of `data.frame`, the logical vector of responses must be indicated as a
 #'   variable name in `.var`.
 #' @param method (`string`)\cr the method used to construct the confidence interval
 #'   for proportion of successful outcomes; one of `waldcc`, `wald`, `clopper-pearson`,
@@ -31,8 +31,8 @@
 #'   given variable.
 #'
 #' @examples
 #' # Case with only logical vector.
 #' rsp_v <- c(1, 0, 1, 0, 1, 1, 0, 0)
 #' s_proportion(rsp_v)
 #'
 #' # Example for Stratified Wilson CI
@@ -138,7 +138,7 @@
 )
 
 #' @describeIn estimate_proportions Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @param ... other arguments are ultimately conveyed to [s_proportion()].
 #'
@@ -151,7 +151,7 @@
 #' dta_test <- data.frame(
 #'   USUBJID = paste0("S", 1:12),
 #'   ARM     = rep(LETTERS[1:3], each = 4),
 #'   AVAL    = c(A = c(1, 1, 1, 1), B = c(0, 0, 1, 1), C = c(0, 0, 0, 0))
 #' )
 #'
 #' basic_table() %>%
@@ -162,6 +162,7 @@
 #' @export
 estimate_proportion <- function(lyt,
                                 vars,
+                                nested = TRUE,
                                 ...,
                                 show_labels = "hidden",
                                 table_names = vars,
@@ -180,6 +181,7 @@
     lyt,
     vars,
     afun = afun,
+    nested = nested,
     extra_args = list(...),
     show_labels = show_labels,
     table_names = table_names
@@ -208,8 +210,8 @@
 #'
 #' @examples
 #' rsp <- c(
 #'   TRUE, TRUE, TRUE, TRUE, TRUE,
 #'   FALSE, FALSE, FALSE, FALSE, FALSE
 #' )
 #' prop_wilson(rsp, conf_level = 0.9)
 #'
@@ -232,7 +234,7 @@
 #' @param weights (`numeric` or `NULL`)\cr weights for each level of the strata. If `NULL`, they are
 #'   estimated using the iterative algorithm proposed in \insertCite{Yan2010-jt;textual}{tern} that
 #'   minimizes the weighted squared length of the confidence interval.
 #' @param max_iterations (`count`)\cr maximum number of iterations for the iterative procedure used
 #'   to find estimates of optimal weights.
 #' @param correct (`flag`)\cr include the continuity correction. For further information, see for example
 #'   [stats::prop.test()].
@@ -279,7 +281,7 @@
   tbl <- table(rsp, strata)
   n_strata <- length(unique(strata))
 
   # Checking the weights and maximum number of iterations.
   do_iter <- FALSE
   if (is.null(weights)) {
     weights <- rep(1 / n_strata, n_strata) # Initialization for iterative procedure
@@ -428,7 +430,7 @@
   alpha <- 1 - conf_level
   l_ci <- ifelse(
     x_sum == 0,
     0,
     stats::qbeta(alpha / 2, x_sum + 0.5, n - x_sum + 0.5)
   )
 
@@ -481,7 +483,7 @@
 #' @description `r lifecycle::badge("stable")`
 #'
 #' This function wraps the estimation of stratified percentiles when we assume
 #' the approximation for large numbers. This is necessary only in the case
 #' proportions for each strata are unequal.
 #'
 #' @inheritParams argument_convention
@@ -515,7 +517,7 @@
 #' @description `r lifecycle::badge("stable")`
 #'
 #' This function wraps the iteration procedure that allows you to estimate
 #' the weights for each proportional strata. This assumes to minimize the
 #' weighted squared length of the confidence interval.
 #'
 #' @inheritParams prop_strat_wilson
@@ -524,7 +526,7 @@
 #' @param initial_weights (`numeric`)\cr initial weights used to calculate `strata_qnorm`. This can
 #'   be optimized in the future if we need to estimate better initial weights.
 #' @param n_per_strata (`numeric`)\cr number of elements in each strata.
 #' @param max_iterations (`count`)\cr maximum number of iterations to be tried. Convergence is always checked.
 #' @param tol (`number`)\cr tolerance threshold for convergence.
 #'
 #' @return A `list` of 3 elements: `n_it`, `weights`, and `diff_v`.
@@ -535,7 +537,7 @@
 #' vs <- c(0.011, 0.013, 0.012, 0.014, 0.017, 0.018)
 #' sq <- 0.674
 #' ws <- rep(1 / length(vs), length(vs))
 #' ns <- c(22, 18, 17, 17, 14, 12)
 #'
 #' update_weights_strat_wilson(vs, sq, ws, ns, 100, 0.95, 0.001)
 #'

R/incidence_rate.R

@@ -38,9 +38,9 @@
 #'
 #' df <- data.frame(
 #'   USUBJID = as.character(seq(6)),
 #'   CNSR = c(0, 1, 1, 0, 0, 0),
 #'   AVAL = c(10.1, 20.4, 15.3, 20.8, 18.7, 23.4),
 #'   ARM = factor(c("A", "A", "A", "B", "B", "B"))
 #' ) %>%
 #'   mutate(is_event = CNSR == 0) %>%
 #'   mutate(n_events = as.integer(is_event))
@@ -111,7 +111,7 @@
 )
 
 #' @describeIn incidence_rate Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `estimate_incidence_rate()` returns a layout object suitable for passing to further layouting functions,
@@ -135,6 +135,7 @@
 #' @export
 estimate_incidence_rate <- function(lyt,
                                     vars,
+                                    nested = TRUE,
                                     ...,
                                     show_labels = "hidden",
                                     table_names = vars,
@@ -156,6 +157,7 @@
     show_labels = show_labels,
     table_names = table_names,
     afun = afun,
+    nested = nested,
     extra_args = list(...)
   )
 }

R/odds_ratio.R

@@ -2,7 +2,7 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Compares bivariate responses between two groups in terms of odds ratios
 #' along with a confidence interval.
 #'
 #' @inheritParams argument_convention
@@ -12,9 +12,9 @@
 #'   The Wald confidence interval with the specified confidence level is
 #'   calculated.
 #'
 #' @note For stratified analyses, there is currently no implementation for conditional
 #'   likelihood confidence intervals, therefore the likelihood confidence interval is not
 #'   yet available as an option. Besides, when `rsp` contains only responders or non-responders,
 #'   then the result values will be `NA`, because no odds ratio estimation is possible.
 #'
 #' @seealso Relevant helper function [h_odds_ratio()].
@@ -164,7 +164,7 @@
 )
 
 #' @describeIn odds_ratio Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @param ... arguments passed to `s_odds_ratio()`.
 #'
@@ -188,6 +188,7 @@
 #' @export
 estimate_odds_ratio <- function(lyt,
                                 vars,
+                                nested = TRUE,
                                 ...,
                                 show_labels = "hidden",
                                 table_names = vars,
@@ -207,6 +208,7 @@
     lyt,
     vars,
     afun = afun,
+    nested = nested,
     extra_args = list(...),
     show_labels = show_labels,
     table_names = table_names
@@ -231,14 +233,14 @@
 NULL
 
 #' @describeIn h_odds_ratio Estimates the odds ratio based on [stats::glm()]. Note that there must be
 #'   exactly 2 groups in `data` as specified by the `grp` variable.
 #'
 #' @examples
 #' # Data with 2 groups.
 #' data <- data.frame(
 #'   rsp = as.logical(c(1, 1, 0, 1, 0, 0, 1, 1)),
 #'   grp = letters[c(1, 1, 1, 2, 2, 2, 1, 2)],
 #'   strata = letters[c(1, 2, 1, 2, 2, 2, 1, 2)],
 #'   stringsAsFactors = TRUE
 #' )
 #'
@@ -279,9 +281,9 @@
 #' @examples
 #' # Data with 3 groups.
 #' data <- data.frame(
 #'   rsp = as.logical(c(1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0)),
 #'   grp = letters[c(1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3)],
 #'   strata = LETTERS[c(1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2)],
 #'   stringsAsFactors = TRUE
 #' )
 #'
@@ -299,7 +301,7 @@
   data$grp <- as_factor_keep_attributes(data$grp)
   data$strata <- as_factor_keep_attributes(data$strata)
 
   # Deviation from convention: `survival::strata` must be simply `strata`.
   formula <- stats::as.formula("rsp ~ grp + strata(strata)")
   model_fit <- clogit_with_tryCatch(formula = formula, data = data)
 

R/prop_diff.R

@@ -10,7 +10,7 @@
 NULL
 
 #' @describeIn prop_diff Statistics function estimating the difference
 #'   in terms of responder proportion.
 #'
 #' @inheritParams prop_diff_strat_nc
 #' @param method (`string`)\cr the method used for the confidence interval estimation.
@@ -168,7 +168,7 @@
 )
 
 #' @describeIn prop_diff Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @param ... arguments passed to `s_proportion_diff()`.
 #'
@@ -191,6 +191,7 @@
 #' @export
 estimate_proportion_diff <- function(lyt,
                                      vars,
+                                     nested = TRUE,
                                      ...,
                                      var_labels = vars,
                                      show_labels = "hidden",
@@ -212,6 +213,7 @@
     vars,
     afun = afun,
     var_labels = var_labels,
+    nested = nested,
     extra_args = list(...),
     show_labels = show_labels,
     table_names = table_names
@@ -307,7 +309,7 @@
 
 #' @describeIn h_prop_diff The Wald interval follows the usual textbook
 #'   definition for a single proportion confidence interval using the normal
 #'   approximation. It is possible to include a continuity correction for Wald's
 #'   interval.
 #'
 #' @param correct (`logical`)\cr whether to include the continuity correction. For further
@@ -359,7 +361,7 @@
 #' @examples
 #' # Anderson-Hauck confidence interval
 #' ## "Mid" case: 3/4 respond in group A, 1/2 respond in group B.
 #' rsp <- c(TRUE, FALSE, FALSE, TRUE, TRUE, TRUE)
 #' grp <- factor(c("A", "B", "A", "B", "A", "A"), levels = c("B", "A"))
 #' prop_diff_ha(rsp = rsp, grp = grp, conf_level = 0.90)
 #'
@@ -389,7 +391,7 @@
   )
 }
 
 #' @describeIn h_prop_diff `Newcombe` confidence interval. It is based on
 #'   the Wilson score confidence interval for a single binomial proportion.
 #'
 #' @examples
@@ -524,7 +526,7 @@
 
 #' @describeIn h_prop_diff Calculates the stratified `Newcombe` confidence interval and difference in response
 #'   rates between the experimental treatment group and the control treatment group, adjusted for stratification
 #'   factors. This implementation follows closely the one proposed by \insertCite{Yan2010-jt;textual}{tern}.
 #'   Weights can be estimated from the heuristic proposed in [prop_strat_wilson()] or from `CMH`-derived weights
 #'   (see [prop_diff_cmh()]).
 #'
@@ -582,7 +584,7 @@
   strata_by_grp <- split(strata, f = grp)
 
   # Finding the weights
   weights <- if (identical(weights_method, "cmh")) {
     prop_diff_cmh(rsp = rsp, grp = grp, strata = strata)$weights
   } else if (identical(weights_method, "wilson_h")) {
     prop_strat_wilson(rsp, strata, conf_level = conf_level, correct = correct)$weights

R/prop_diff_test.R

@@ -2,7 +2,7 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Various tests were implemented to test the difference between two proportions.
 #'
 #' @inheritParams argument_convention
 #' @param tbl (`matrix`)\cr matrix with two groups in rows and the binary response (`TRUE`/`FALSE`) in columns.
@@ -107,7 +107,7 @@
 )
 
 #' @describeIn prop_diff_test Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @param ... other arguments are passed to [s_test_proportion_diff()].
 #'
@@ -136,6 +136,7 @@
 #' @export
 test_proportion_diff <- function(lyt,
                                  vars,
+                                 nested = TRUE,
                                  ...,
                                  var_labels = vars,
                                  show_labels = "hidden",
@@ -156,6 +157,7 @@
     vars,
     afun = afun,
     var_labels = var_labels,
+    nested = nested,
     extra_args = list(...),
     show_labels = show_labels,
     table_names = table_names
@@ -164,7 +166,7 @@
 
 #' Helper Functions to Test Proportion Differences
 #'
 #' Helper functions to implement various tests on the difference between two proportions.
 #'
 #' @param tbl (`matrix`)\cr matrix with two groups in rows and the binary response (`TRUE`/`FALSE`) in columns.
 #'

R/summarize_ancova.R

@@ -2,8 +2,8 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
 #' Summarize results of `ANCOVA`. This can be used to analyze multiple endpoints and/or
 #' multiple timepoints within the same response variable `.var`.
 #'
 #' @inheritParams argument_convention
 #'
@@ -16,8 +16,8 @@
 #'
 #' @inheritParams argument_convention
 #' @param .df_row (`data.frame`)\cr data set that includes all the variables that are called in `.var` and `variables`.
 #' @param variables (named `list` of `strings`)\cr list of additional analysis variables, with expected elements:
 #'   * `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple groups will be
 #'     summarized. Specifically, the first level of `arm` variable is taken as the reference group.
 #'   * `covariates` (`character`)\cr a vector that can contain single variable names (such as `"X1"`), and/or
 #'     interaction terms indicated by `"X1 * X2"`.
@@ -94,7 +94,7 @@
 #'     If working with the reference group, this will be empty.
 #'   * `lsmean_diff_ci`: Confidence level for difference in estimated marginal means in comparison
 #'     to the reference group.
 #'   * `pval`: p-value (not adjusted for multiple comparisons).
 #'
 #' @examples
 #' library(dplyr)
@@ -127,7 +127,7 @@
 
   sum_level <- as.character(unique(df[[arm]]))
 
   # Ensure that there is only one element in sum_level.
   checkmate::assert_scalar(sum_level)
 
   sum_fit_level <- sum_fit[sum_fit[[arm]] == sum_level, ]
@@ -214,7 +214,7 @@
 )
 
 #' @describeIn summarize_ancova Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `summarize_ancova()` returns a layout object suitable for passing to further layouting functions,
@@ -244,6 +244,7 @@
 summarize_ancova <- function(lyt,
                              vars,
                              var_labels,
+                             nested = TRUE,
                              ...,
                              show_labels = "visible",
                              table_names = vars,
@@ -270,6 +271,7 @@
     show_labels = show_labels,
     table_names = table_names,
     afun = afun,
+    nested = nested,
     extra_args = list(...)
   )
 }

R/summarize_change.R

@@ -3,7 +3,7 @@
 #' @description `r lifecycle::badge("stable")`
 #'
 #' The primary analysis variable `.var` indicates the numerical change from baseline results,
 #' and additional required secondary analysis variables are `value` and `baseline_flag`.
 #' Depending on the baseline flag, either the absolute baseline values (at baseline)
 #' or the change from baseline values (post-baseline) are then summarized.
 #'
@@ -78,14 +78,14 @@
 )
 
 #' @describeIn summarize_change Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `summarize_change()` 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 formatted rows containing
 #'   the statistics from `s_change_from_baseline()` to the table layout.
 #'
 #' @note To be used after a split on visits in the layout, such that each data subset only contains
 #'   either baseline or post-baseline data.
 #'
 #' @examples
@@ -120,6 +120,7 @@
 #' @export
 summarize_change <- function(lyt,
                              vars,
+                             nested = TRUE,
                              ...,
                              table_names = vars,
                              .stats = c("n", "mean_sd", "median", "range"),
@@ -138,6 +139,7 @@
     lyt,
     vars,
     afun = afun,
+    nested = nested,
     extra_args = list(...),
     table_names = table_names
   )

R/summarize_glm_count.R

@@ -14,7 +14,7 @@
 #'
 #' @description `r lifecycle::badge("experimental")`
 #'
 #' Helper functions that can be used to return the results of various Poisson models.
 #'
 #' @inheritParams argument_convention
 #'
@@ -27,9 +27,9 @@
 #'
 #' @param .df_row (`data.frame`)\cr data set that includes all the variables that are called
 #'   in `.var` and `variables`.
 #' @param variables (named `list` of `strings`)\cr list of additional analysis variables, with
 #'   expected elements:
 #'   * `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple
 #'     groups will be summarized. Specifically, the first level of `arm` variable is taken as the
 #'     reference group.
 #'   * `covariates` (`character`)\cr a vector that can contain single variable names (such as
@@ -133,9 +133,9 @@
 #'
 #' @param .df_row (`data.frame`)\cr data set that includes all the variables that are called
 #'   in `.var` and `variables`.
 #' @param variables (named `list` of `strings`)\cr list of additional analysis variables, with
 #'   expected elements:
 #'   * `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple
 #'     groups will be summarized. Specifically, the first level of `arm` variable is taken as the
 #'     reference group.
 #'   * `covariates` (`character`)\cr a vector that can contain single variable names (such as
@@ -156,7 +156,7 @@
                         distribution,
                         weights) {
   if (distribution == "negbin") {
     stop("negative binomial distribution is not currently available.")
   }
   switch(distribution,
     poisson = h_glm_poisson(.var, .df_row, variables, weights),
@@ -170,7 +170,7 @@
 #' @param .df_row (`data.frame`)\cr data set that includes all the variables that are called in `.var` and `variables`.
 #' @param conf_level (`numeric`)\cr value used to derive the confidence interval for the rate.
 #' @param obj (`glm.fit`)\cr fitted model object used to derive the mean rate estimates in each treatment arm.
 #' @param `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple groups will be
 #'   summarized. Specifically, the first level of `arm` variable is taken as the reference group.
 #'
 #' @return
@@ -246,7 +246,7 @@
   y <- df[[.var]]
   smry_level <- as.character(unique(df[[arm]]))
 
   # ensure there is only 1 value
   checkmate::assert_scalar(smry_level)
 
   results <- h_glm_count(
@@ -347,7 +347,7 @@
 )
 
 #' @describeIn summarize_glm_count Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `summarize_glm_count()` returns a layout object suitable for passing to further layouting functions,
@@ -400,6 +400,7 @@
 summarize_glm_count <- function(lyt,
                                 vars,
                                 var_labels,
+                                nested = TRUE,
                                 ...,
                                 show_labels = "visible",
                                 table_names = vars,
@@ -422,6 +423,7 @@
     show_labels = show_labels,
     table_names = table_names,
     afun = afun,
+    nested = nested,
     extra_args = list(...)
   )
 }

R/summarize_num_patients.R

@@ -15,7 +15,7 @@
 NULL
 
 #' @describeIn summarize_num_patients Statistics function which counts the number of
 #'   unique patients, the corresponding percentage taken with respect to the
 #'   total number of patients, and the number of non-unique patients.
 #'
 #' @return
@@ -26,12 +26,12 @@
 #'
 #' @examples
 #' # Use the statistics function to count number of unique and nonunique patients.
 #' s_num_patients(x = as.character(c(1, 1, 1, 2, 4, NA)), labelstr = "", .N_col = 6L)
 #' s_num_patients(
 #'   x = as.character(c(1, 1, 1, 2, 4, NA)),
 #'   labelstr = "",
 #'   .N_col = 6L,
 #'   count_by = as.character(c(1, 1, 2, 1, 1, 1))
 #' )
 #'
 #' @export
@@ -52,7 +52,7 @@
   }
 
   out <- list(
     unique = formatters::with_label(c(count1, ifelse(count1 == 0 && .N_col == 0, 0, count1 / .N_col)), labelstr),
     nonunique = formatters::with_label(count2, labelstr),
     unique_count = formatters::with_label(count1, ifelse(unique_count_suffix, paste(labelstr, "(n)"), labelstr))
   )
@@ -61,7 +61,7 @@
 }
 
 #' @describeIn summarize_num_patients Statistics function which counts the number of unique patients
 #'   in a column (variable), the corresponding percentage taken with respect to the total number of
 #'   patients, and the number of non-unique patients in the column.
 #'
 #' @param required (`character` or `NULL`)\cr optional name of a variable that is required to be non-missing.
@@ -127,7 +127,7 @@
 )
 
 #' @describeIn summarize_num_patients Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::summarize_row_groups()].
 #'
 #' @return
 #' * `summarize_num_patients()` returns a layout object suitable for passing to further layouting functions,
@@ -171,7 +171,7 @@
 }
 
 #' @describeIn summarize_num_patients Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `analyze_num_patients()` returns a layout object suitable for passing to further layouting functions,
@@ -182,16 +182,16 @@
 #'   work like [rtables::analyze()], while functions that starts with `summarize*`
 #'   are based upon [rtables::summarize_row_groups()]. The latter provides a
 #'   value for each dividing split in the row and column space, but, being it
 #'   bound to the fundamental splits, it is repeated by design in every page
 #'   when pagination is involved.
 #'
 #' @note As opposed to [summarize_num_patients()], this function does not repeat the produced rows.
 #'
 #' @examples
 #' df_tmp <- data.frame(
 #'   USUBJID = as.character(c(1, 2, 1, 4, NA, 6, 6, 8, 9)),
 #'   ARM = c("A", "A", "A", "A", "A", "B", "B", "B", "B"),
 #'   AGE = c(10, 15, 10, 17, 8, 11, 11, 19, 17)
 #' )
 #' tbl <- basic_table() %>%
 #'   split_cols_by("ARM") %>%
@@ -203,6 +203,7 @@
 #' @export
 analyze_num_patients <- function(lyt,
                                  vars,
+                                 nested = TRUE,
                                  .stats = NULL,
                                  .formats = NULL,
                                  .labels = c(
@@ -232,6 +233,7 @@
     afun = afun,
     lyt = lyt,
     vars = vars,
+    nested = nested,
     extra_args = list(...),
     show_labels = show_labels,
     indent_mod = .indent_mods

R/survival_coxph_pairwise.R

@@ -132,7 +132,7 @@
 )
 
 #' @describeIn survival_coxph_pairwise Layout-creating function which can take statistics function arguments
 #'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
 #' @return
 #' * `coxph_pairwise()` returns a layout object suitable for passing to further layouting functions,
@@ -165,6 +165,7 @@
 #' @export
 coxph_pairwise <- function(lyt,
                            vars,
+                           nested = TRUE,
                            ...,
                            var_labels = "CoxPH",
                            show_labels = "visible",
@@ -187,6 +188,7 @@
     show_labels = show_labels,
     table_names = table_names,
     afun = afun,
+    nested = nested,
     extra_args = list(...)
   )
 }