1441 Introduce transformators parameter in modules (#1313)

insightsengineering/teal#1441

Included `transformators` parameter in modules. This is passed to
`teal::module` that does assertions and checks on this parameter.

A food for thought: default `decorators` value is `NULL` where default
`transformators` value is `list()`. Maybe we can introduce a check, that
allows `transformators` to be `NULL` on default, and which changes
`NULL` to `list()`.

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

R/argument_convention.R

@@ -204,8 +204,8 @@ NULL
 #' @param worst_flag_var ([teal.transform::choices_selected()])\cr object
 #'   with all available choices and preselected option for variable names that can be used as worst flag variable.
 #' @param decorators `r lifecycle::badge("experimental")`
-#' " (`list` of `teal_transform_module`, named `list` of `teal_transform_module` or" `NULL`) optional,
-#' if not `NULL`, decorator for tables or plots included in the module.
+#' (`list` of `teal_transform_module`, named `list` of `teal_transform_module`) optional,
+#' decorator for tables or plots included in the module output reported.
 #' When a named list of `teal_transform_module`, the decorators are applied to the respective output objects.
 #'
 #' Otherwise, the decorators are applied to all objects, which is equivalent as using the name `default`.

R/tm_a_gee.R

@@ -129,6 +129,7 @@ template_a_gee <- function(output_table,
 #' This module produces an analysis table using Generalized Estimating Equations (GEE).
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_arguments
 #' @inheritParams template_a_gee
 #'
@@ -208,7 +209,8 @@ tm_a_gee <- function(label,
                      pre_output = NULL,
                      post_output = NULL,
                      basic_table_args = teal.widgets::basic_table_args(),
-                     decorators = NULL) {
+                     transformators = list(),
+                     decorators = list()) {
   message("Initializing tm_a_gee (prototype)")
 
   cov_var <- teal.transform::add_no_selected_choices(cov_var, multiple = TRUE)
@@ -227,7 +229,7 @@ tm_a_gee <- function(label,
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(basic_table_args, "basic_table_args")
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "table", null.ok = TRUE)
+  assert_decorators(decorators, "table")
 
   args <- as.list(environment())
 
@@ -257,6 +259,7 @@ tm_a_gee <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_a_mmrm.R

@@ -440,6 +440,7 @@ template_mmrm_plots <- function(fit_name,
 #' This module produces analysis tables and plots for Mixed Model Repeated Measurements.
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_mmrm_tables
 #' @inheritParams template_mmrm_plots
 #' @param method ([teal.transform::choices_selected()])\cr object with
@@ -569,7 +570,8 @@ tm_a_mmrm <- function(label,
                       post_output = NULL,
                       basic_table_args = teal.widgets::basic_table_args(),
                       ggplot2_args = teal.widgets::ggplot2_args(),
-                      decorators = NULL) {
+                      transformators = list(),
+                      decorators = list()) {
   message("Initializing tm_a_mmrm")
   cov_var <- teal.transform::add_no_selected_choices(cov_var, multiple = TRUE)
   checkmate::assert_string(label)
@@ -608,8 +610,7 @@ tm_a_mmrm <- function(label,
       "fixed_effects_table",
       "diagnostic_table",
       "diagnostic_plot"
-    ),
-    null.ok = TRUE
+    )
   )
 
   args <- as.list(environment())
@@ -644,6 +645,7 @@ tm_a_mmrm <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_g_barchart_simple.R

@@ -6,6 +6,7 @@
 #' `x_facet`, and `y_facet` parameters. Any parameters set to `NULL` (default) are ignored.
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_arguments
 #' @param x (`data_extract_spec`)\cr variable on the x-axis.
 #' @param fill (`data_extract_spec`)\cr grouping variable to determine bar colors.
@@ -155,7 +156,8 @@ tm_g_barchart_simple <- function(x = NULL,
                                  pre_output = NULL,
                                  post_output = NULL,
                                  ggplot2_args = teal.widgets::ggplot2_args(),
-                                 decorators = NULL) {
+                                 transformators = list(),
+                                 decorators = list()) {
   message("Initializing tm_g_barchart_simple")
   checkmate::assert_string(label)
   checkmate::assert_list(plot_options, null.ok = TRUE)
@@ -181,7 +183,7 @@ tm_g_barchart_simple <- function(x = NULL,
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, names = "plot", null.ok = TRUE)
+  assert_decorators(decorators, names = "plot")
 
   plot_options <- utils::modifyList(
     list(stacked = FALSE), # default
@@ -210,6 +212,7 @@ tm_g_barchart_simple <- function(x = NULL,
       ggplot2_args = ggplot2_args,
       decorators = decorators
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_g_ci.R

@@ -183,6 +183,7 @@ template_g_ci <- function(dataname,
 #' `CIG01` available [here](https://insightsengineering.github.io/tlg-catalog/stable/graphs/other/cig01.html).
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_g_ci
 #' @param color (`data_extract_spec`)\cr the group variable used to determine the plot colors, shapes, and line types.
 #'
@@ -283,7 +284,8 @@ tm_g_ci <- function(label,
                     pre_output = NULL,
                     post_output = NULL,
                     ggplot2_args = teal.widgets::ggplot2_args(),
-                    decorators = NULL) {
+                    transformators = list(),
+                    decorators = list()) {
   message("Initializing tm_g_ci")
   checkmate::assert_string(label)
   stat <- match.arg(stat)
@@ -309,7 +311,7 @@ tm_g_ci <- function(label,
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "plot", null.ok = TRUE)
+  assert_decorators(decorators, "plot")
 
   args <- as.list(environment())
 
@@ -328,6 +330,7 @@ tm_g_ci <- function(label,
       ggplot2_args = ggplot2_args,
       decorators = decorators
     ),
+    transformators = transformators,
     ui = ui_g_ci,
     ui_args = args,
     datanames = teal.transform::get_extract_datanames(data_extract_list)

R/tm_g_forest_rsp.R

@@ -239,6 +239,7 @@ template_forest_rsp <- function(dataname = "ANL",
 #'
 #' @inheritParams tern::g_forest
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_forest_rsp
 #'
 #' @inherit module_arguments return seealso
@@ -364,7 +365,8 @@ tm_g_forest_rsp <- function(label,
                             pre_output = NULL,
                             post_output = NULL,
                             ggplot2_args = teal.widgets::ggplot2_args(),
-                            decorators = NULL) {
+                            transformators = list(),
+                            decorators = list()) {
   message("Initializing tm_g_forest_rsp")
   checkmate::assert_string(label)
   checkmate::assert_string(dataname)
@@ -391,7 +393,7 @@ tm_g_forest_rsp <- function(label,
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "plot", null.ok = TRUE)
+  assert_decorators(decorators, "plot")
 
   args <- as.list(environment())
 
@@ -424,6 +426,7 @@ tm_g_forest_rsp <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_g_forest_tte.R

@@ -239,6 +239,7 @@ template_forest_tte <- function(dataname = "ANL",
 #'
 #' @inheritParams tern::g_forest
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_forest_tte
 #'
 #' @inherit module_arguments return seealso
@@ -348,7 +349,8 @@ tm_g_forest_tte <- function(label,
                             pre_output = NULL,
                             post_output = NULL,
                             ggplot2_args = teal.widgets::ggplot2_args(),
-                            decorators = NULL) {
+                            transformators = list(),
+                            decorators = list()) {
   message("Initializing tm_g_forest_tte")
   checkmate::assert_string(label)
   checkmate::assert_string(dataname)
@@ -377,7 +379,7 @@ tm_g_forest_tte <- function(label,
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "plot", null.ok = TRUE)
+  assert_decorators(decorators, "plot")
 
   args <- as.list(environment())
 
@@ -410,6 +412,7 @@ tm_g_forest_tte <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_g_ipp.R

@@ -173,6 +173,7 @@ template_g_ipp <- function(dataname = "ANL",
 #' values over time for each patient, using data with ADaM structure.
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_g_ipp
 #' @param arm_var ([teal.transform::choices_selected()])\cr object with
 #'   all available choices and preselected option for variable values that can be used as arm variable.
@@ -303,7 +304,8 @@ tm_g_ipp <- function(label,
                      pre_output = NULL,
                      post_output = NULL,
                      ggplot2_args = teal.widgets::ggplot2_args(),
-                     decorators = NULL) {
+                     transformators = list(),
+                     decorators = list()) {
   if (lifecycle::is_present(base_var)) {
     baseline_var <- base_var
     warning(
@@ -340,7 +342,7 @@ tm_g_ipp <- function(label,
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "plot", null.ok = TRUE)
+  assert_decorators(decorators, "plot")
 
   args <- as.list(environment())
   data_extract_list <- list(
@@ -370,6 +372,7 @@ tm_g_ipp <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_g_km.R

@@ -264,6 +264,7 @@ template_g_km <- function(dataname = "ANL",
 #' This module produces a `ggplot`-style Kaplan-Meier plot for data with ADaM structure.
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_g_km
 #' @param facet_var ([teal.transform::choices_selected()])\cr object with
 #'   all available choices and preselected option for names of variable that can be used for plot faceting.
@@ -373,7 +374,8 @@ tm_g_km <- function(label,
                     plot_width = NULL,
                     pre_output = NULL,
                     post_output = NULL,
-                    decorators = NULL) {
+                    transformators = list(),
+                    decorators = list()) {
   message("Initializing tm_g_km")
 
   checkmate::assert_string(label)
@@ -397,7 +399,7 @@ tm_g_km <- function(label,
   checkmate::assert_class(pre_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "plot", null.ok = TRUE)
+  assert_decorators(decorators, "plot")
 
   args <- as.list(environment())
   data_extract_list <- list(
@@ -430,6 +432,7 @@ tm_g_km <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_g_lineplot.R

@@ -210,6 +210,7 @@ template_g_lineplot <- function(dataname = "ANL",
 #' This module produces a [ggplot2::ggplot()] type line plot, with optional summary table, for standard ADaM data.
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_g_lineplot
 #'
 #' @inherit module_arguments return seealso
@@ -307,7 +308,8 @@ tm_g_lineplot <- function(label,
                           pre_output = NULL,
                           post_output = NULL,
                           ggplot2_args = teal.widgets::ggplot2_args(),
-                          decorators = NULL) {
+                          transformators = list(),
+                          decorators = list()) {
   if (lifecycle::is_present(strata)) {
     warning(
       "The `strata` argument of `tm_g_lineplot()` is deprecated as of teal.modules.clinical 0.9.1. ",
@@ -348,7 +350,7 @@ tm_g_lineplot <- function(label,
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
 
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "plot", null.ok = TRUE)
+  assert_decorators(decorators, "plot")
 
   args <- as.list(environment())
   data_extract_list <- list(
@@ -377,6 +379,7 @@ tm_g_lineplot <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = teal.transform::get_extract_datanames(data_extract_list)
   )
 }

R/tm_g_pp_adverse_events.R

@@ -165,6 +165,7 @@ template_adverse_events <- function(dataname = "ANL",
 #' This module produces an adverse events table and [ggplot2::ggplot()] type plot using ADaM datasets.
 #'
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_adverse_events
 #' @param aeterm ([teal.transform::choices_selected()])\cr object with all
 #'   available choices and preselected option for the `AETERM` variable from `dataname`.
@@ -287,7 +288,8 @@ tm_g_pp_adverse_events <- function(label,
                                    pre_output = NULL,
                                    post_output = NULL,
                                    ggplot2_args = teal.widgets::ggplot2_args(),
-                                   decorators = NULL) {
+                                   transformators = list(),
+                                   decorators = list()) {
   message("Initializing tm_g_pp_adverse_events")
   checkmate::assert_string(label)
   checkmate::assert_string(dataname)
@@ -313,7 +315,7 @@ tm_g_pp_adverse_events <- function(label,
   checkmate::assert_class(post_output, classes = "shiny.tag", null.ok = TRUE)
   checkmate::assert_class(ggplot2_args, "ggplot2_args")
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, names = c("plot", "table"), null.ok = TRUE)
+  assert_decorators(decorators, names = c("plot", "table"))
 
   args <- as.list(environment())
   data_extract_list <- list(
@@ -344,6 +346,7 @@ tm_g_pp_adverse_events <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = c(dataname, parentname)
   )
 }

R/tm_g_pp_patient_timeline.R

@@ -323,6 +323,7 @@ template_patient_timeline <- function(dataname = "ANL",
 #'
 #' @inheritParams tm_g_pp_adverse_events
 #' @inheritParams module_arguments
+#' @inheritParams teal::module
 #' @inheritParams template_patient_timeline
 #' @param dataname_adcm (`character`)\cr name of `ADCM` dataset or equivalent.
 #' @param dataname_adae (`character`)\cr name of `ADAE` dataset or equivalent.
@@ -471,7 +472,8 @@ tm_g_pp_patient_timeline <- function(label,
                                      pre_output = NULL,
                                      post_output = NULL,
                                      ggplot2_args = teal.widgets::ggplot2_args(),
-                                     decorators = NULL) {
+                                     transformators = list(),
+                                     decorators = list()) {
   message("Initializing tm_g_pp_patient_timeline")
   checkmate::assert_string(label)
   checkmate::assert_string(dataname_adcm)
@@ -498,7 +500,7 @@ tm_g_pp_patient_timeline <- function(label,
     lower = plot_width[2], upper = plot_width[3], null.ok = TRUE, .var.name = "plot_width"
   )
   decorators <- normalize_decorators(decorators)
-  assert_decorators(decorators, "plot", null.ok = TRUE)
+  assert_decorators(decorators, "plot")
 
   xor_error_string <- function(x, y) {
     paste(
@@ -559,6 +561,7 @@ tm_g_pp_patient_timeline <- function(label,
         decorators = decorators
       )
     ),
+    transformators = transformators,
     datanames = c(dataname_adcm, dataname_adae, parentname)
   )
 }