Datanames in vignettes (#1434)

closing #1380 and insightsengineering/teal.data#338

- removes `set_datanames`
- mentions dot-prefix to exclude dataset

NAMESPACE

@@ -28,7 +28,6 @@ export(modules)
 export(new_tdata)
 export(report_card_template)
 export(reporter_previewer_module)
-export(set_datanames)
 export(show_rcode_modal)
 export(srv_teal)
 export(srv_teal_with_splash)

NEWS.md

@@ -6,7 +6,6 @@
 * Introduced `teal_transform_module` to provide a way to interactively modify data delivered to `teal_module`'s `server` and to decorate module outputs. #1228 #1384
 * Introduced a new argument `once = FALSE` in `teal_data_module` to possibly reload data during a run time.
 * Possibility to download lockfile to restore app session for reproducibility. #479
-* Introduced a function `set_datanames()` to change a `datanames` of the `teal_module`.
 * Datasets which name starts with `.` are ignored when `module`'s `datanames` is set as `"all"`.
 * Added warning when reserved `datanames`, such as `all` and `.raw_data` are being used. 
 

R/init.R

@@ -12,7 +12,6 @@
 #'
 #' @param data (`teal_data` or `teal_data_module`)
 #'   For constructing the data object, refer to [teal.data::teal_data()] and [teal_data_module()].
-#'   If `datanames` are not set for the `teal_data` object, defaults from the `teal_data` environment will be used.
 #' @param modules (`list` or `teal_modules` or `teal_module`)
 #'   Nested list of `teal_modules` or `teal_module` objects or a single
 #'   `teal_modules` or `teal_module` object. These are the specific output modules which

R/modules.R

@@ -21,19 +21,18 @@ setOldClass("teal_modules")
 #' and the report previewer module [reporter_previewer_module()], respectively.
 #'
 #' # Restricting datasets used by `teal_module`:
+#'
 #' The `datanames` argument controls which datasets are used by the module’s server. These datasets,
 #' passed via server's `data` argument, are the only ones shown in the module's tab.
 #'
 #' When `datanames` is set to `"all"`, all datasets in the data object are treated as relevant.
 #' However, this may include unnecessary datasets, such as:
 #' -	Proxy variables for column modifications
-#' -	Temporary datasets used to create final versions
+#' -	Temporary datasets used to create final ones
 #' -	Connection objects
 #'
-#' To exclude irrelevant datasets, use the [set_datanames()] function to change `datanames` from
-#' `"all"` to specific names. Trying to modify non-`"all"` values with [set_datanames()] will result
-#' in a warning. Datasets with names starting with . are ignored globally unless explicitly listed
-#' in `datanames`.
+#' Datasets which name is prefixed in `teal_data` by the dot (`.`) are not displayed in the `teal` application.
+#' Please see the _"Hidden datasets"_ section in `vignette("including-data-in-teal-applications").
 #'
 #' # `datanames` with `transformators`
 #' When transformators are specified, their `datanames` are added to the module’s `datanames`, which
@@ -591,39 +590,6 @@ print.teal_modules <- function(x, ...) {
   invisible(x)
 }
 
-#' @param modules (`teal_module` or `teal_modules`)
-#' @rdname teal_modules
-#' @examples
-#' # change the module's datanames
-#' set_datanames(module(datanames = "all"), "a")
-#'
-#' # change modules' datanames
-#' set_datanames(
-#'   modules(
-#'     module(datanames = "all"),
-#'     module(datanames = "a")
-#'   ),
-#'   "b"
-#' )
-#' @export
-set_datanames <- function(modules, datanames) {
-  checkmate::assert_multi_class(modules, c("teal_modules", "teal_module"))
-  if (inherits(modules, "teal_modules")) {
-    modules$children <- lapply(modules$children, set_datanames, datanames)
-  } else {
-    if (identical(modules$datanames, "all")) {
-      modules$datanames <- datanames
-    } else {
-      warning(
-        "Not possible to modify datanames of the module ", modules$label,
-        ". set_datanames() can only change datanames if it was set to \"all\".",
-        call. = FALSE
-      )
-    }
-  }
-  modules
-}
-
 # utilities ----
 ## subset or modify modules ----
 

vignettes/creating-custom-modules.Rmd

@@ -211,6 +211,7 @@ Let's review what we've done so far:
 The `teal::module()` function allows you to encapsulate your UI and server logic into a `teal` module, making it reusable and ready to integrate into any `teal` application.
 
 By setting `datanames = "all"`, you give the module access to all datasets specified in the `teal_data` object.
+Datasets which names start with `.` won't be included (see [Hidden datasets](including-data-in-teal-applications.html#hidden-datasets) section).
 
 ```r
 # Custom histogram module creation

vignettes/including-data-in-teal-applications.Rmd

@@ -233,6 +233,32 @@ For a detailed explanation of verification, see [this `teal.data` vignette](http
 
 <br>
 
+##### Hidden datasets
+
+Objects which name starts with a dot (.) are hidden in teal_data and the whole teal application. This can be used to pass auxiliary objects in the `teal_data` instance, without exposing them to the app user. For example:
+
+- Proxy variables for column modifications
+- Temporary datasets used to create final ones
+- Connection objects
+
+```{r}
+my_data <- teal_data()
+my_data <- within(my_data, {
+  .data1 <- data.frame(id = 1:10, x = 11:20)
+  .data2 <- data.frame(id = 1:10, y = 11:20)
+  data <- merge(.data1, .data2)
+})
+
+ls(my_data)
+names(my_data)
+
+app <- init(data = my_data, modules = example_module())
+
+if (interactive()) {
+  shinyApp(app$ui, app$server)
+}
+```
+
 ## Further reading
 
 For a complete guide to the `teal_data` class, please refer to the [`teal.data` package](https://insightsengineering.github.io/teal.data/latest-tag/).