Add vignettes on decorators (#843)

Part of insightsengineering/teal#1475 Adds some explanation about decorators functionality of `tmg`, since we will remove/reduce confusing decorators vignette in `teal`. Heavily based on `Customizing Module Output` vignette currently existing in `teal`, with adjustments to show `teal.modules.general` modules. https://github.com/insightsengineering/teal/blob/c70299587cdf8280c75f7320ae09cd3c67c79837/vignettes/customizing-module-output.Rmd --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: vedhav <[email protected]> Co-authored-by: Vedha Viyash <[email protected]>
insightsengineering · Feb 25, 2025 · fbf27a0 · fbf27a0
1 parent 690b32b
commit fbf27a0
Show file tree

Hide file tree

Showing 26 changed files with 650 additions and 89 deletions.
diff --git a/R/tm_a_pca.R b/R/tm_a_pca.R
@@ -20,10 +20,10 @@
 #' @section Decorating Module:
 #'
 #' This module generates the following objects, which can be modified in place using decorators:
-#' - `elbow_plot` (`ggplot2`)
-#' - `circle_plot` (`ggplot2`)
-#' - `biplot` (`ggplot2`)
-#' - `eigenvector_plot` (`ggplot2`)
+#' - `elbow_plot` (`ggplot`)
+#' - `circle_plot` (`ggplot`)
+#' - `biplot` (`ggplot`)
+#' - `eigenvector_plot` (`ggplot`)
 #'
 #' A Decorator is applied to the specific output using a named list of `teal_transform_module` objects.
 #' The name of this list corresponds to the name of the output to which the decorator is applied.
@@ -42,6 +42,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/tm_a_regression.R b/R/tm_a_regression.R
@@ -46,7 +46,7 @@
 #' @section Decorating Module:
 #'
 #' This module generates the following objects, which can be modified in place using decorators:
-#' - `plot` (`ggplot2`)
+#' - `plot` (`ggplot`)
 #'
 #' A Decorator is applied to the specific output using a named list of `teal_transform_module` objects.
 #' The name of this list corresponds to the name of the output to which the decorator is applied.
@@ -62,6 +62,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/tm_g_association.R b/R/tm_g_association.R
@@ -43,6 +43,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/tm_g_bivariate.R b/R/tm_g_bivariate.R
@@ -49,7 +49,7 @@
 #' @section Decorating Module:
 #'
 #' This module generates the following objects, which can be modified in place using decorators:
-#' - `plot` (`ggplot2`)
+#' - `plot` (`ggplot`)
 #'
 #' A Decorator is applied to the specific output using a named list of `teal_transform_module` objects.
 #' The name of this list corresponds to the name of the output to which the decorator is applied.
@@ -65,6 +65,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #'

diff --git a/R/tm_g_distribution.R b/R/tm_g_distribution.R
@@ -29,8 +29,8 @@
 #' @section Decorating Module:
 #'
 #' This module generates the following objects, which can be modified in place using decorators::
-#' - `histogram_plot` (`ggplot2`)
-#' - `qq_plot` (`ggplot2`)
+#' - `histogram_plot` (`ggplot`)
+#' - `qq_plot` (`ggplot`)
 #' - `summary_table` (`datatables` created with [DT::datatable()])
 #' - `test_table` (`datatables` created with [DT::datatable()])
 #'
@@ -51,6 +51,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/tm_g_response.R b/R/tm_g_response.R
@@ -42,7 +42,7 @@
 #' @section Decorating Module:
 #'
 #' This module generates the following objects, which can be modified in place using decorators:
-#' - `plot` (`ggplot2`)
+#' - `plot` (`ggplot`)
 #'
 #' A Decorator is applied to the specific output using a named list of `teal_transform_module` objects.
 #' The name of this list corresponds to the name of the output to which the decorator is applied.
@@ -58,6 +58,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/tm_g_scatterplot.R b/R/tm_g_scatterplot.R
@@ -33,7 +33,7 @@
 #' @section Decorating Module:
 #'
 #' This module generates the following objects, which can be modified in place using decorators:
-#' - `plot` (`ggplot2`)
+#' - `plot` (`ggplot`)
 #'
 #' A Decorator is applied to the specific output using a named list of `teal_transform_module` objects.
 #' The name of this list corresponds to the name of the output to which the decorator is applied.
@@ -49,6 +49,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #'

diff --git a/R/tm_g_scatterplotmatrix.R b/R/tm_g_scatterplotmatrix.R
@@ -37,6 +37,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/tm_missing_data.R b/R/tm_missing_data.R
@@ -22,8 +22,8 @@
 #' This module generates the following objects, which can be modified in place using decorators:
 #' - `summary_plot` (`grob` created with [ggplot2::ggplotGrob()])
 #' - `combination_plot` (`grob` created with [ggplot2::ggplotGrob()])
-#' - `by_subject_plot` (`ggplot2`)
-#' - `table` (`datatable` created with [DT::datatable()])
+#' - `by_subject_plot` (`ggplot`)
+#' - `table` (`datatables` created with [DT::datatable()])
 #'
 #' A Decorator is applied to the specific output using a named list of `teal_transform_module` objects.
 #' The name of this list corresponds to the name of the output to which the decorator is applied.
@@ -42,6 +42,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/tm_outliers.R b/R/tm_outliers.R
@@ -18,10 +18,10 @@
 #' @section Decorating Module:
 #'
 #' This module generates the following objects, which can be modified in place using decorators:
-#' - `box_plot` (`ggplot2`)
-#' - `density_plot` (`ggplot2`)
-#' - `cumulative_plot` (`ggplot2`)
-#' - `table` (`datatable` created with [DT::datatable()])
+#' - `box_plot` (`ggplot`)
+#' - `density_plot` (`ggplot`)
+#' - `cumulative_plot` (`ggplot`)
+#' - `table` (`datatables` created with [DT::datatable()])
 #'
 #' A Decorator is applied to the specific output using a named list of `teal_transform_module` objects.
 #' The name of this list corresponds to the name of the output to which the decorator is applied.
@@ -40,6 +40,9 @@
 #' ```
 #'
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive
@@ -533,12 +536,12 @@ srv_outliers <- function(id, data, reporter, filter_panel_api, outlier_var,
       # this is utils function that converts a %>% NULL %>% b into a %>% b
       remove_pipe_null <- function(x) {
         if (length(x) == 1) {
-          return(x)
-        }
-        if (identical(x[[1]], as.name("%>%")) && is.null(x[[3]])) {
-          return(remove_pipe_null(x[[2]]))
+          x
+        } else if (identical(x[[1]], as.name("%>%")) && is.null(x[[3]])) {
+          remove_pipe_null(x[[2]])
+        } else {
+          as.call(c(x[[1]], lapply(x[-1], remove_pipe_null)))
         }
-        return(as.call(c(x[[1]], lapply(x[-1], remove_pipe_null))))
       }
 
       qenv <- teal.code::eval_code(

diff --git a/R/tm_t_crosstable.R b/R/tm_t_crosstable.R
@@ -43,6 +43,9 @@
 #' )
 #' ```
 #' For additional details and examples of decorators, refer to the vignette
+#' `vignette("decorate-module-output", package = "teal.modules.general")`.
+#'
+#' To learn more please refer to the vignette
 #' `vignette("transform-module-output", package = "teal")` or the [`teal::teal_transform_module()`] documentation.
 #'
 #' @examplesShinylive

diff --git a/R/utils.R b/R/utils.R
@@ -34,11 +34,9 @@
 #' - When the length of `size` is three: the plot points size are dynamically adjusted based on
 #' vector of `value`, `min`, and `max`.
 #' @param decorators `r lifecycle::badge("experimental")`
-#' (`list` of `teal_transform_module`, named `list` of `teal_transform_module`) optional,
+#' (named `list` of lists 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`.
+#' The decorators are applied to the respective output objects.
 #'
 #' See section "Decorating Module" below for more details.
 #'

diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -1,13 +1,17 @@
+ElementaryTable
 Forkers
 Hoffmann
 Prebuilt
 Shinylive
 TLG
 UI
 customizable
+datatables
 facetting
 funder
+ggplot
 pre
+qq
 repo
 reproducibility
 sortable

diff --git a/man/shared_params.Rd b/man/shared_params.Rd
diff --git a/man/tm_a_pca.Rd b/man/tm_a_pca.Rd
diff --git a/man/tm_a_regression.Rd b/man/tm_a_regression.Rd
diff --git a/man/tm_g_association.Rd b/man/tm_g_association.Rd
diff --git a/man/tm_g_bivariate.Rd b/man/tm_g_bivariate.Rd