Skip to contents

Create teal_module and teal_modules objects

Source: R/modules.R
teal_modules.Rd

[Stable] Create a nested tab structure to embed modules in a teal application.

Usage 

module(
  label = "module",
  server = function(id, data, ...) moduleServer(id, function(input, output, session)
    NULL),
  ui = function(id, ...) tags$p(paste0("This module has no UI (id: ", id, " )")),
  filters,
  datanames = "all",
  server_args = NULL,
  ui_args = NULL,
  transformers = list()
)

modules(..., label = "root")

# S3 method for class 'teal_module'
format(
  x,
  indent = 0,
  is_last = FALSE,
  parent_prefix = "",
  what = c("datasets", "properties", "ui_args", "server_args", "transformers"),
  ...
)

# S3 method for class 'teal_modules'
format(x, indent = 0, is_root = TRUE, is_last = FALSE, parent_prefix = "", ...)

# S3 method for class 'teal_module'
print(x, ...)

# S3 method for class 'teal_modules'
print(x, ...)

set_datanames(modules, datanames)

Arguments

label

(character(1)) Label shown in the navigation item for the module or module group. For modules() defaults to "root". See Details.

server

(function) shiny module with following arguments:

  • id - teal will set proper shiny namespace for this module (see shiny::moduleServer()).

  • input, output, session - (optional; not recommended) When provided, then shiny::callModule() will be used to call a module. From shiny 1.5.0, the recommended way is to use shiny::moduleServer() instead which doesn't require these arguments.

  • data (optional) When provided, the module will be called with teal_data object (i.e. a list of reactive (filtered) data specified in the filters argument) as the value of this argument.

  • datasets (optional) When provided, the module will be called with FilteredData object as the value of this argument. (See teal.slice::FilteredData).

  • reporter (optional) When provided, the module will be called with Reporter object as the value of this argument. (See teal.reporter::Reporter).

  • filter_panel_api (optional) When provided, the module will be called with FilterPanelAPI object as the value of this argument. (See teal.slice::FilterPanelAPI).

  • ... (optional) When provided, server_args elements will be passed to the module named argument or to the ....

ui

(function) shiny UI module function with following arguments:

  • id - teal will set proper shiny namespace for this module.

  • ... (optional) When provided, ui_args elements will be passed to the module named argument or to the ....

filters

(character) Deprecated. Use datanames instead.

datanames

(character) Names of the datasets relevant to the item. There are 2 reserved values that have specific behaviors:

  • The keyword "all" includes all datasets available in the data passed to the teal application.

  • NULL hides the sidebar panel completely.

  • If transformers are specified, their datanames are automatically added to this datanames argument.

server_args

(named list) with additional arguments passed on to the server function.

ui_args

(named list) with additional arguments passed on to the UI function.

transformers

(list of teal_data_module) that will be applied to transform the data. Each transform module UI will appear in the teal's sidebar panel. Transformers' datanames are added to the datanames. See teal_transform_module().

...

  • For modules(): (teal_module or teal_modules) Objects to wrap into a tab.

  • For format() and print(): Arguments passed to other methods.

x

(teal_module or teal_modules) Object to format/print.

indent

(integer(1)) Indention level; each nested element is indented one level more.

is_last

(logical(1)) Whether this is the last item in its parent's children list. Affects the tree branch character used (L- vs |-)

parent_prefix

(character(1)) The prefix inherited from parent nodes, used to maintain the tree structure in nested levels

what

(character) Specifies which metadata to display. Possible values: "datasets", "properties", "ui_args", "server_args", "transformers"

is_root

(logical(1)) Whether this is the root node of the tree. Only used in format.teal_modules(). Determines whether to show "TEAL ROOT" header

modules

(teal_module or teal_modules)

Value

module() returns an object of class teal_module.

modules() returns a teal_modules object which contains following fields:

  • label: taken from the label argument.

  • children: a list containing objects passed in .... List elements are named after their label attribute converted to a valid shiny id.

Details

module() creates an instance of a teal_module that can be placed in a teal application. modules() shapes the structure of a the application by organizing teal_module within the navigation panel. It wraps teal_module and teal_modules objects in a teal_modules object, which results in a nested structure corresponding to the nested tabs in the final application.

Note that for modules() label comes after ..., so it must be passed as a named argument, otherwise it will be captured by ....

The labels "global_filters" and "Report previewer" are reserved because they are used by the mapping argument of teal_slices() 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

  • 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.

datanames with transformers

When transformers are specified, their datanames are added to the module’s datanames, which changes the behavior as follows:

  • If module(datanames) is NULL and the transformers have defined datanames, the sidebar will appear showing the transformers' datasets, instead of being hidden.

  • If module(datanames) is set to specific values and any transformer has datanames = "all", the module may receive extra datasets that could be unnecessary

Examples 

library(shiny)

module_1 <- module(
  label = "a module",
  server = function(id, data) {
    moduleServer(
      id,
      module = function(input, output, session) {
        output$data <- renderDataTable(data()[["iris"]])
      }
    )
  },
  ui = function(id) {
    ns <- NS(id)
    tagList(dataTableOutput(ns("data")))
  },
  datanames = "all"
)

module_2 <- module(
  label = "another module",
  server = function(id) {
    moduleServer(
      id,
      module = function(input, output, session) {
        output$text <- renderText("Another Module")
      }
    )
  },
  ui = function(id) {
    ns <- NS(id)
    tagList(textOutput(ns("text")))
  },
  datanames = NULL
)

modules <- modules(
  label = "modules",
  modules(
    label = "nested modules",
    module_1
  ),
  module_2
)

app <- init(
  data = teal_data(iris = iris),
  modules = modules
)

if (interactive()) {
  shinyApp(app$ui, app$server)
}
mod <- module(
  label = "My Custom Module",
  server = function(id, data, ...) {},
  ui = function(id, ...) {},
  datanames = c("ADSL", "ADTTE"),
  transformers = list(),
  ui_args = list(a = 1, b = "b"),
  server_args = list(x = 5, y = list(p = 1))
)
cat(format(mod))
#> |- My Custom Module
#> |  |- Datasets         : ADSL, ADTTE
#> |  |- Properties:
#> |  |  |- Bookmarkable  : FALSE
#> |  |  L- Reportable    : FALSE
#> |  |- UI Arguments     : a (numeric)
#> |  |                     b (character)
#> |  |- Server Arguments : x (numeric)
#> |  |                     y (list)
#> |  L- Transformers     : 
custom_module <- function(
    label = "label", ui_args = NULL, server_args = NULL,
    datanames = "all", transformers = list(), bk = FALSE) {
  ans <- module(
    label,
    server = function(id, data, ...) {},
    ui = function(id, ...) {
    },
    datanames = datanames,
    transformers = transformers,
    ui_args = ui_args,
    server_args = server_args
  )
  attr(ans, "teal_bookmarkable") <- bk
  ans
}

dummy_transformer <- teal_transform_module(
  label = "Dummy Transform",
  ui = function(id) div("(does nothing)"),
  server = function(id, data) {
    moduleServer(id, function(input, output, session) data)
  }
)

plot_transformer <- teal_transform_module(
  label = "Plot Settings",
  ui = function(id) div("(does nothing)"),
  server = function(id, data) {
    moduleServer(id, function(input, output, session) data)
  }
)

complete_modules <- modules(
  custom_module(
    label = "Data Overview",
    datanames = c("ADSL", "ADAE", "ADVS"),
    ui_args = list(
      view_type = "table",
      page_size = 10,
      filters = c("ARM", "SEX", "RACE")
    ),
    server_args = list(
      cache = TRUE,
      debounce = 1000
    ),
    transformers = list(dummy_transformer),
    bk = TRUE
  ),
  modules(
    label = "Nested 1",
    custom_module(
      label = "Interactive Plots",
      datanames = c("ADSL", "ADVS"),
      ui_args = list(
        plot_type = c("scatter", "box", "line"),
        height = 600,
        width = 800,
        color_scheme = "viridis"
      ),
      server_args = list(
        render_type = "svg",
        cache_plots = TRUE
      ),
      transformers = list(dummy_transformer, plot_transformer),
      bk = TRUE
    ),
    modules(
      label = "Nested 2",
      custom_module(
        label = "Summary Statistics",
        datanames = "ADSL",
        ui_args = list(
          stats = c("mean", "median", "sd", "range"),
          grouping = c("ARM", "SEX")
        )
      ),
      modules(
        label = "Labeled nested modules",
        custom_module(
          label = "Subgroup Analysis",
          datanames = c("ADSL", "ADAE"),
          ui_args = list(
            subgroups = c("AGE", "SEX", "RACE"),
            analysis_type = "stratified"
          ),
          bk = TRUE
        )
      ),
      modules(custom_module(label = "Subgroup Analysis in non-labled modules"))
    )
  ),
  custom_module("Non-nested module")
)

cat(format(complete_modules))
#> TEAL ROOT
#>   |- Data Overview
#>   |  |- Datasets         : ADSL, ADAE, ADVS
#>   |  |- Properties:
#>   |  |  |- Bookmarkable  : TRUE
#>   |  |  L- Reportable    : FALSE
#>   |  |- UI Arguments     : view_type (character)
#>   |  |                     page_size (numeric)
#>   |  |                     filters (character)
#>   |  |- Server Arguments : cache (logical)
#>   |  |                     debounce (numeric)
#>   |  L- Transformers     : Dummy Transform
#>   |- Nested 1
#>   |  |- Interactive Plots
#>   |  |  |- Datasets         : ADSL, ADVS
#>   |  |  |- Properties:
#>   |  |  |  |- Bookmarkable  : TRUE
#>   |  |  |  L- Reportable    : FALSE
#>   |  |  |- UI Arguments     : plot_type (character)
#>   |  |  |                     height (numeric)
#>   |  |  |                     width (numeric)
#>   |  |  |                     color_scheme (character)
#>   |  |  |- Server Arguments : render_type (character)
#>   |  |  |                     cache_plots (logical)
#>   |  |  L- Transformers     : Dummy Transform, Plot Settings
#>   |  L- Nested 2
#>   |     |- Summary Statistics
#>   |     |  |- Datasets         : ADSL
#>   |     |  |- Properties:
#>   |     |  |  |- Bookmarkable  : FALSE
#>   |     |  |  L- Reportable    : FALSE
#>   |     |  |- UI Arguments     : stats (character)
#>   |     |  |                     grouping (character)
#>   |     |  |- Server Arguments : 
#>   |     |  L- Transformers     : 
#>   |     |- Labeled nested modules
#>   |     |  L- Subgroup Analysis
#>   |     |     |- Datasets         : ADSL, ADAE
#>   |     |     |- Properties:
#>   |     |     |  |- Bookmarkable  : TRUE
#>   |     |     |  L- Reportable    : FALSE
#>   |     |     |- UI Arguments     : subgroups (character)
#>   |     |     |                     analysis_type (character)
#>   |     |     |- Server Arguments : 
#>   |     |     L- Transformers     : 
#>   |     L- root
#>   |        L- Subgroup Analysis in non-labled modules
#>   |           |- Datasets         : all
#>   |           |- Properties:
#>   |           |  |- Bookmarkable  : FALSE
#>   |           |  L- Reportable    : FALSE
#>   |           |- UI Arguments     : 
#>   |           |- Server Arguments : 
#>   |           L- Transformers     : 
#>   L- Non-nested module
#>      |- Datasets         : all
#>      |- Properties:
#>      |  |- Bookmarkable  : FALSE
#>      |  L- Reportable    : FALSE
#>      |- UI Arguments     : 
#>      |- Server Arguments : 
#>      L- Transformers     : 
cat(format(complete_modules, what = c("ui_args", "server_args", "transformers")))
#> TEAL ROOT
#>   |- Data Overview
#>   |  |- UI Arguments     : view_type (character)
#>   |  |                     page_size (numeric)
#>   |  |                     filters (character)
#>   |  |- Server Arguments : cache (logical)
#>   |  |                     debounce (numeric)
#>   |  L- Transformers     : Dummy Transform
#>   |- Nested 1
#>   |  |- Interactive Plots
#>   |  |  |- UI Arguments     : plot_type (character)
#>   |  |  |                     height (numeric)
#>   |  |  |                     width (numeric)
#>   |  |  |                     color_scheme (character)
#>   |  |  |- Server Arguments : render_type (character)
#>   |  |  |                     cache_plots (logical)
#>   |  |  L- Transformers     : Dummy Transform, Plot Settings
#>   |  L- Nested 2
#>   |     |- Summary Statistics
#>   |     |  |- UI Arguments     : stats (character)
#>   |     |  |                     grouping (character)
#>   |     |  |- Server Arguments : 
#>   |     |  L- Transformers     : 
#>   |     |- Labeled nested modules
#>   |     |  L- Subgroup Analysis
#>   |     |     |- UI Arguments     : subgroups (character)
#>   |     |     |                     analysis_type (character)
#>   |     |     |- Server Arguments : 
#>   |     |     L- Transformers     : 
#>   |     L- root
#>   |        L- Subgroup Analysis in non-labled modules
#>   |           |- UI Arguments     : 
#>   |           |- Server Arguments : 
#>   |           L- Transformers     : 
#>   L- Non-nested module
#>      |- UI Arguments     : 
#>      |- Server Arguments : 
#>      L- Transformers     : 
# change the module's datanames
set_datanames(module(datanames = "all"), "a")
#> |- module
#> |  |- Datasets         : a
#> |  |- Properties:
#> |  |  |- Bookmarkable  : FALSE
#> |  |  L- Reportable    : FALSE
#> |  |- UI Arguments     : 
#> |  |- Server Arguments : 
#> |  L- Transformers     : 

# change modules' datanames
set_datanames(
  modules(
    module(datanames = "all"),
    module(datanames = "a")
  ),
  "b"
)
#> Warning: Not possible to modify datanames of the module module. set_datanames() can only change datanames if it was set to "all".
#> TEAL ROOT
#>   |- module
#>   |  |- Datasets         : b
#>   |  |- Properties:
#>   |  |  |- Bookmarkable  : FALSE
#>   |  |  L- Reportable    : FALSE
#>   |  |- UI Arguments     : 
#>   |  |- Server Arguments : 
#>   |  L- Transformers     : 
#>   L- module
#>      |- Datasets         : a
#>      |- Properties:
#>      |  |- Bookmarkable  : FALSE
#>      |  L- Reportable    : FALSE
#>      |- UI Arguments     : 
#>      |- Server Arguments : 
#>      L- Transformers     :