teal module: Cross-table — tm_t_crosstable • teal.modules.general

Generates a simple cross-table of two variables from a dataset with custom options for showing percentages and sub-totals.

Usage

tm_t_crosstable(
  label = "Cross Table",
  x = teal.picks::picks(teal.picks::datasets(), teal.picks::variables(choices =
    teal.picks::is_categorical(min.len = 2, max.len = 10), selected = 1L, multiple =
    TRUE, ordered = TRUE)),
  y,
  show_percentage = TRUE,
  show_total = TRUE,
  remove_zero_columns = FALSE,
  pre_output = NULL,
  post_output = NULL,
  basic_table_args = teal.widgets::basic_table_args(),
  transformators = list(),
  decorators = list()
)

Arguments

label

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

x

(picks or list of picks) Object with all available choices with pre-selected option for variable X - row values. In case of picks use teal.picks::variables(..., ordered = TRUE) if table elements should be rendered according to selection order.

y

(picks or list of multiple picks) Object with all available choices with pre-selected option for variable Y - column values.

picks must not allow multiple selection in this case.

show_percentage

(logical(1)) Indicates whether to show percentages (relevant only when x is a factor). Defaults to TRUE.

show_total

(logical(1)) Indicates whether to show total column. Defaults to TRUE.

remove_zero_columns

(logical(1)) Indicates whether to remove columns that contain only zeros from the output table. Defaults to FALSE.

pre_output

(shiny.tag) optional, text or UI element to be displayed before the module's output, providing context or a title. with text placed before the output to put the output into context. For example a title.

post_output

(shiny.tag) optional, text or UI element to be displayed after the module's output, adding context or further instructions. Elements like shiny::helpText() are useful.

basic_table_args

(basic_table_args) object created by teal.widgets::basic_table_args() with settings for the module table. The argument is merged with options variable teal.basic_table_args and default module setup.

For more details see the vignette: vignette("custom-basic-table-arguments", package = "teal.widgets")

transformators

(list of teal_transform_module) that will be applied to transform module's data input. To learn more check vignette("transform-input-data", package = "teal").

decorators

(named list of lists of teal_transform_module) optional, decorator for tables or plots included in the module output reported. The decorators are applied to the respective output objects.

Value

Object of class teal_module to be used in teal applications.

Note

For more examples, please see the vignette "Using cross table" via vignette("using-cross-table", package = "teal.modules.general").

Table Settings

The module provides several table settings that can be adjusted:

Show column percentage: Shows column percentages when enabled
Show total column: Shows a total column when enabled
Remove zero-only columns: Removes columns that contain only zeros from the output table

Decorating Module

This module generates the following objects, which can be modified in place using decorators:

table (ElementaryTable - output of rtables::build_table)

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. See code snippet below:

tm_t_crosstable(
   ..., # arguments for module
   decorators = list(
     table = teal_transform_module(...) # applied to the `table` output
   )
)

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.

Reporting

This module returns an object of class teal_module, that contains a server function. Since the server function returns a teal_report object, this makes this module reportable, which means that the reporting functionality will be turned on automatically by the teal framework.

For more information on reporting in teal, see the vignettes:

vignette("reportable-shiny-application", package = "teal.reporter")
vignette("adding-support-for-reporting-to-custom-modules", package = "teal")

Examples in Shinylive

example-1: Open in Shinylive
example-2: Open in Shinylive

Examples

# general data example
data <- teal_data()
data <- within(data, {
  mtcars <- mtcars
  for (v in c("cyl", "vs", "am", "gear")) {
    mtcars[[v]] <- as.factor(mtcars[[v]])
  }
  mtcars[["primary_key"]] <- seq_len(nrow(mtcars))
})
join_keys(data) <- join_keys(join_key("mtcars", "mtcars", "primary_key"))

app <- init(
  data = data,
  modules = modules(
    tm_t_crosstable(
      label = "Cross Table",
      x = teal.picks::picks(
        datasets("mtcars"),
        teal.picks::variables(
          choices = variable_choices(data[["mtcars"]], c("cyl", "vs", "am", "gear")),
          selected = c("cyl", "gear"),
          multiple = TRUE,
          ordered = TRUE,
          fixed = FALSE
        ),
        teal.picks::values()
      ),
      y = teal.picks::picks(
        datasets("mtcars"),
        teal.picks::variables(
          choices = variable_choices(data[["mtcars"]], c("cyl", "vs", "am", "gear")),
          selected = "vs",
          multiple = FALSE,
          fixed = FALSE
        ),
        teal.picks::values()
      )
    )
  )
)
#> Warning: variables has eager choices (character) while datasets has dynamic choices. It is not guaranteed that explicitly defined choices will be a subset of data selected in a previous element.
#> Initializing tm_t_crosstable
#> Warning: variables has eager choices (character) while datasets has dynamic choices. It is not guaranteed that explicitly defined choices will be a subset of data selected in a previous element.
if (interactive()) {
  shinyApp(app$ui, app$server)
}

# CDISC data example
data <- teal_data()
data <- within(data, {
  ADSL <- teal.data::rADSL
})
join_keys(data) <- default_cdisc_join_keys[names(data)]

app <- init(
  data = data,
  modules = modules(
    tm_t_crosstable(
      label = "Cross Table",
      x = teal.picks::picks(
        datasets("ADSL"),
        teal.picks::variables(
          choices = variable_choices(data[["ADSL"]], subset = function(data) {
            idx <- !vapply(data, inherits, logical(1), c("Date", "POSIXct", "POSIXlt"))
            return(names(data)[idx])
          }),
          selected = "COUNTRY",
          multiple = TRUE,
          ordered = TRUE,
          fixed = FALSE
        ),
        teal.picks::values()
      ),
      y = teal.picks::picks(
        datasets("ADSL"),
        teal.picks::variables(
          choices = variable_choices(data[["ADSL"]], subset = function(data) {
            idx <- vapply(data, is.factor, logical(1))
            return(names(data)[idx])
          }),
          selected = "SEX",
          multiple = FALSE,
          fixed = FALSE
        ),
        teal.picks::values()
      )
    )
  )
)
#> Warning: variables has eager choices (character) while datasets has dynamic choices. It is not guaranteed that explicitly defined choices will be a subset of data selected in a previous element.
#> Initializing tm_t_crosstable
#> Warning: variables has eager choices (character) while datasets has dynamic choices. It is not guaranteed that explicitly defined choices will be a subset of data selected in a previous element.
if (interactive()) {
  shinyApp(app$ui, app$server)
}