Merge branch 'main' into 277_refactor_pkct01@main

Signed-off-by: Emily de la Rua <59304861+edelarua@users.noreply.github.com>

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: tern
 Title: Create Common TLGs Used in Clinical Trials
-Version: 0.8.5.9019
-Date: 2023-08-31
+Version: 0.9.0.9000
+Date: 2023-09-01
 Authors@R: c(
     person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")),
     person("Daniel", "Sabanés Bové", , "daniel.sabanes_bove@roche.com", role = "aut"),
@@ -135,6 +135,7 @@ Collate:
     'prune_occurrences.R'
     'response_biomarkers_subgroups.R'
     'response_subgroups.R'
+    'riskdiff.R'
     'rtables_access.R'
     'score_occurrences.R'
     'split_cols_by_groups.R'

NAMESPACE

@@ -36,6 +36,7 @@ export(a_odds_ratio)
 export(a_proportion)
 export(a_proportion_diff)
 export(a_summary)
+export(add_riskdiff)
 export(add_rowcounts)
 export(aesi_label)
 export(analyze_num_patients)
@@ -255,6 +256,7 @@ export(stack_grobs)
 export(stat_mean_ci)
 export(stat_mean_pval)
 export(stat_median_ci)
+export(stat_propdiff_ci)
 export(strata_normal_quantile)
 export(summarize_ancova)
 export(summarize_change)

NEWS.md

@@ -1,8 +1,13 @@
-# tern 0.8.5.9019
+# tern 0.9.0.9000
+
+# tern 0.9.0
+### New Features
+* Added `stat_propdiff_ci` function to calculate proportion/risk difference and CI.
+* Added risk difference column functionality via the `riskdiff` argument to functions `count_occurrences`, `count_occurrences_by_grade`, `count_patients_with_event`, `count_patients_with_flags`, `analyze_num_patients`, and `summarize_num_patients`.
 
 ### Enhancements
-* Refactored `a_summary` to no longer use helper function `create_afun_summary`. 
-* Refactored `summarize_vars` and `compare_vars` to use refactored `a_summary`.
+* Refactored the function `a_summary` to no longer use the helper function `create_afun_summary`.
+* Refactored functions `summarize_vars` and `compare_vars` to use the refactored `a_summary` function.
 * Created new internal helper functions `ungroup_stats` to ungroup statistics calculated for factor variables, and `a_summary_internal` to perform calculations for `a_summary`.
 * Added `imputation_rule` function to apply imputation rule to data.
 * Updated `analyze_vars_in_cols` to use caching, allow implementation of imputation rule via the `imp_rule` argument, and allow user to specify cell alignment via the `.aligns` argument.

R/argument_convention.R

@@ -6,6 +6,8 @@
 #' @param ... additional arguments for the lower level functions.
 #' @param .aligns (`character`)\cr alignment for table contents (not including labels). When `NULL`, `"center"`
 #'   is applied. See [formatters::list_valid_aligns()] for a list of all currently supported alignments.
+#' @param .all_col_counts (`vector` of `integer`)\cr each value represents a global count for a column. Values are
+#'   taken from `alt_counts_df` if specified (see [rtables::build_table()]).
 #' @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 (`integer`)\cr column-wise N (column count) for the full column being analyzed that is typically
@@ -52,6 +54,9 @@
 #' @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 riskdiff (`flag`)\cr whether a risk difference column is present. When set to `TRUE`, [add_riskdiff()] must be
+#'   used as `split_fun` in the prior column split of the table layout, specifying which columns should be compared.
+#'   See [stat_propdiff_ci()] for details on risk difference calculation.
 #' @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

R/count_occurrences.R

@@ -169,13 +169,16 @@ count_occurrences <- function(lyt,
                               vars,
                               var_labels = vars,
                               show_labels = "hidden",
+                              riskdiff = FALSE,
                               nested = TRUE,
                               ...,
                               table_names = vars,
                               .stats = "count_fraction",
                               .formats = NULL,
                               .labels = NULL,
                               .indent_mods = NULL) {
+  checkmate::assert_flag(riskdiff)
+
   afun <- make_afun(
     a_count_occurrences,
     .stats = .stats,
@@ -185,14 +188,25 @@ count_occurrences <- function(lyt,
     .ungroup_stats = .stats
   )
 
+  extra_args <- if (isFALSE(riskdiff)) {
+    list(...)
+  } else {
+    list(
+      afun = list("s_count_occurrences" = afun),
+      .stats = .stats,
+      .indent_mods = .indent_mods,
+      s_args = list(...)
+    )
+  }
+
   analyze(
     lyt = lyt,
     vars = vars,
-    afun = afun,
+    afun = ifelse(isFALSE(riskdiff), afun, afun_riskdiff),
     var_labels = var_labels,
     show_labels = show_labels,
     table_names = table_names,
     nested = nested,
-    extra_args = list(...)
+    extra_args = extra_args
   )
 }

R/count_occurrences_by_grade.R

@@ -268,13 +268,16 @@ count_occurrences_by_grade <- function(lyt,
                                        var,
                                        var_labels = var,
                                        show_labels = "default",
+                                       riskdiff = FALSE,
                                        nested = TRUE,
                                        ...,
                                        table_names = var,
                                        .stats = NULL,
                                        .formats = NULL,
                                        .indent_mods = NULL,
                                        .labels = NULL) {
+  checkmate::assert_flag(riskdiff)
+
   afun <- make_afun(
     a_count_occurrences_by_grade,
     .stats = .stats,
@@ -283,15 +286,26 @@ count_occurrences_by_grade <- function(lyt,
     .ungroup_stats = "count_fraction"
   )
 
+  extra_args <- if (isFALSE(riskdiff)) {
+    list(...)
+  } else {
+    list(
+      afun = list("s_count_occurrences_by_grade" = afun),
+      .stats = .stats,
+      .indent_mods = .indent_mods,
+      s_args = list(...)
+    )
+  }
+
   analyze(
     lyt = lyt,
     vars = var,
     var_labels = var_labels,
     show_labels = show_labels,
-    afun = afun,
+    afun = ifelse(isFALSE(riskdiff), afun, afun_riskdiff),
     table_names = table_names,
     nested = nested,
-    extra_args = list(...)
+    extra_args = extra_args
   )
 }
 

R/count_patients_with_event.R

@@ -144,13 +144,16 @@ a_count_patients_with_event <- make_afun(
 #' @export
 count_patients_with_event <- function(lyt,
                                       vars,
+                                      riskdiff = FALSE,
                                       nested = TRUE,
                                       ...,
                                       table_names = vars,
                                       .stats = "count_fraction",
                                       .formats = NULL,
                                       .labels = NULL,
                                       .indent_mods = NULL) {
+  checkmate::assert_flag(riskdiff)
+
   afun <- make_afun(
     a_count_patients_with_event,
     .stats = .stats,
@@ -159,12 +162,23 @@ count_patients_with_event <- function(lyt,
     .indent_mods = .indent_mods
   )
 
+  extra_args <- if (isFALSE(riskdiff)) {
+    list(...)
+  } else {
+    list(
+      afun = list("s_count_patients_with_event" = afun),
+      .stats = .stats,
+      .indent_mods = .indent_mods,
+      s_args = list(...)
+    )
+  }
+
   analyze(
     lyt,
     vars,
-    afun = afun,
+    afun = ifelse(isFALSE(riskdiff), afun, afun_riskdiff),
     nested = nested,
-    extra_args = list(...),
+    extra_args = extra_args,
     show_labels = ifelse(length(vars) > 1, "visible", "hidden"),
     table_names = table_names
   )

R/count_patients_with_flags.R

@@ -157,12 +157,15 @@ count_patients_with_flags <- function(lyt,
                                       var,
                                       var_labels = var,
                                       show_labels = "hidden",
+                                      riskdiff = FALSE,
                                       nested = TRUE,
                                       ...,
                                       table_names = paste0("tbl_flags_", var),
                                       .stats = "count_fraction",
                                       .formats = NULL,
                                       .indent_mods = NULL) {
+  checkmate::assert_flag(riskdiff)
+
   afun <- make_afun(
     a_count_patients_with_flags,
     .stats = .stats,
@@ -171,15 +174,26 @@ count_patients_with_flags <- function(lyt,
     .ungroup_stats = .stats
   )
 
+  extra_args <- if (isFALSE(riskdiff)) {
+    list(...)
+  } else {
+    list(
+      afun = list("s_count_patients_with_flags" = afun),
+      .stats = .stats,
+      .indent_mods = .indent_mods,
+      s_args = list(...)
+    )
+  }
+
   lyt <- analyze(
     lyt = lyt,
     vars = var,
     var_labels = var_labels,
     show_labels = show_labels,
-    afun = afun,
+    afun = ifelse(isFALSE(riskdiff), afun, afun_riskdiff),
     table_names = table_names,
     nested = nested,
-    extra_args = list(...)
+    extra_args = extra_args
   )
 
   lyt

R/prop_diff_test.R

@@ -212,8 +212,7 @@ prop_cmh <- function(ary) {
 
 #' @describeIn h_prop_diff_test performs the Chi-Squared test with Schouten correction.
 #'
-#' @seealso For information on the Schouten correction (Schouten, 1980),
-#'   visit \url{https://onlinelibrary.wiley.com/doi/abs/10.1002/bimj.4710220305}.
+#' @seealso Schouten correction is based upon \insertCite{Schouten1980-kd;textual}{tern}.
 #'
 #'
 #' @keywords internal