Merge branch 'main' into workflow-updates

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: tern
 Title: Create Common TLGs Used in Clinical Trials
-Version: 0.8.1.9003
-Date: 2023-04-02
+Version: 0.8.1.9006
+Date: 2023-04-19
 Authors@R: c(
     person("Joe", "Zhu", , "[email protected]", role = c("aut", "cre")),
     person("Daniel", "Sabanés Bové", , "[email protected]", role = "aut"),

NEWS.md

@@ -1,4 +1,4 @@
-# tern 0.8.1.9003
+# tern 0.8.1.9006
 
 ### Bug Fixes
 * Fixed missing label for `TRTEDTM` in `tern` datasets.
@@ -7,6 +7,7 @@
 * Implemented the `lubridate` package for date variables in `tern` datasets.
 * Organization of `.gitignore` and `.Rbuildignore`.
 * Removed deprecated `footnotes` functions and all related files.
+* Added `section_div` and `na_level` (`na_str`) to `summarize_vars`.
 
 # tern 0.8.0
 

R/argument_convention.R

@@ -49,11 +49,13 @@
 #'   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 label visibility: one of "default", "visible" and "hidden".
+#' @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 for label.
+#' @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.

R/df_explicit_na.R

@@ -38,13 +38,34 @@
 #'   stringsAsFactors = FALSE
 #' )
 #'
+#' # Example 1
 #' # Encode missing values in all character or factor columns.
 #' df_explicit_na(my_data)
 #' # Also convert logical columns to factor columns.
 #' df_explicit_na(my_data, logical_as_factor = TRUE)
 #' # Encode missing values in a subset of columns.
 #' df_explicit_na(my_data, omit_columns = c("x", "y"))
 #'
+#' # Example 2
+#' # Here we purposefully convert all `M` values to `NA` in the `SEX` variable.
+#' # After running `df_explicit_na` the `NA` values are encoded as `<Missing>` but they are not
+#' # included when generating `rtables`.
+#' adsl <- tern_ex_adsl
+#' adsl$SEX[adsl$SEX == "M"] <- NA
+#' adsl <- df_explicit_na(adsl)
+#'
+#' # If you want the `Na` values to be displayed in the table use the `na_level` argument.
+#' adsl <- tern_ex_adsl
+#' adsl$SEX[adsl$SEX == "M"] <- NA
+#' adsl <- df_explicit_na(adsl, na_level = "Missing Values")
+#'
+#' # Example 3
+#' # Numeric variables that have missing values are not altered. This means that any `NA` value in
+#' # a numeric variable will not be included in the summary statistics, nor will they be included
+#' # in the denominator value for calculating the percent values.
+#' adsl <- tern_ex_adsl
+#' adsl$AGE[adsl$AGE < 30] <- NA
+#' adsl <- df_explicit_na(adsl)
 df_explicit_na <- function(data,
                            omit_columns = NULL,
                            char_as_factor = TRUE,

R/summarize_variables.R

@@ -711,10 +711,12 @@ create_afun_summary <- function(.stats, .formats, .labels, .indent_mods) {
 summarize_vars <- function(lyt,
                            vars,
                            var_labels = vars,
+                           na_level = NA_character_,
                            nested = TRUE,
                            ...,
                            show_labels = "default",
                            table_names = vars,
+                           section_div = NA_character_,
                            .stats = c("n", "mean_sd", "median", "range", "count_fraction"),
                            .formats = NULL,
                            .labels = NULL,
@@ -726,10 +728,12 @@ summarize_vars <- function(lyt,
     vars = vars,
     var_labels = var_labels,
     afun = afun,
+    na_str = na_level,
     nested = nested,
     extra_args = list(...),
     inclNAs = TRUE,
     show_labels = show_labels,
-    table_names = table_names
+    table_names = table_names,
+    section_div = section_div
   )
 }