tm_g_distribution: `teal` module: Distribution analysis

Description

Module is designed to explore the distribution of a single variable within a given dataset. It offers several tools, such as histograms, Q-Q plots, and various statistical tests to visually and statistically analyze the variable's distribution.

Usage

tm_g_distribution(
  label = "Distribution Module",
  dist_var = teal.picks::picks(teal.picks::datasets(), teal.picks::variables(is.numeric),
    teal.picks::values()),
  strata_var = NULL,
  group_var = NULL,
  freq = FALSE,
  ggtheme = c("gray", "bw", "linedraw", "light", "dark", "minimal", "classic", "void"),
  ggplot2_args = teal.widgets::ggplot2_args(),
  bins = c(30L, 1L, 100L),
  plot_height = c(600, 200, 2000),
  plot_width = NULL,
  pre_output = NULL,
  post_output = NULL,
  transformators = list(),
  decorators = list()
)

Value

Object of class teal_module to be used in teal applications.

Arguments

label

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

dist_var

(picks or list of multiple picks) Variable(s) for which the distribution will be analyzed.

strata_var

(picks or list of multiple picks) Categorical variable used to split the distribution analysis.

group_var

(picks or list of multiple picks) Variable used for faceting plot into multiple panels.

freq

(logical) optional, whether to display frequency (TRUE) or density (FALSE). Defaults to density (FALSE).

ggtheme

(character) optional, ggplot2 theme to be used by default. Defaults to "gray".

ggplot2_args

(ggplot2_args) optional, object created by teal.widgets::ggplot2_args() with settings for all the plots or named list of ggplot2_args objects for plot-specific settings. The argument is merged with options variable teal.ggplot2_args and default module setup.

List names should match the following: c("default", "Histogram", "QQplot").

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

bins

(integer(1) or integer(3)) optional, specifies the number of bins for the histogram.

When the length of bins is one: The histogram bins will have a fixed size based on the bins provided.
When the length of bins is three: The histogram bins are dynamically adjusted based on vector of value, min, and max. Defaults to c(30L, 1L, 100L).

plot_height

(numeric) optional, specifies the plot height as a three-element vector of value, min, and max intended for use with a slider UI element.

plot_width

(numeric) optional, specifies the plot width as a three-element vector of value, min, and max for a slider encoding the plot width.

pre_output

(shiny.tag) optional,
with text placed before the output to put the output into context. For example a title.

post_output

(shiny.tag) optional, with text placed after the output to put the output into context. For example the shiny::helpText() elements are useful.

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.

Decorating Module

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

histogram_plot (ggplot)
qq_plot (ggplot)
summary_table (DT::datatable)
test_table (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. See code snippet below:

tm_g_distribution(
   ..., # arguments for module
   decorators = list(
     histogram_plot = teal_transform_module(...), # applied only to `histogram_plot` output
     qq_plot = teal_transform_module(...) # applied only to `qq_plot` output
     summary_table = teal_transform_module(...) # applied only to `summary_table` output
     test_table = teal_transform_module(...) # applied only to `test_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

Run this code

# general data example
data <- teal_data()
data <- within(data, {
  iris <- iris
})

app <- init(
  data = data,
  modules = list(
    tm_g_distribution(
      dist_var = teal.picks::picks(
        datasets("iris"),
        teal.picks::variables(is.numeric),
        teal.picks::values()
      )
    )
  )
)
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_g_distribution(
      dist_var = teal.picks::picks(
        datasets("ADSL"),
        teal.picks::variables(c("BMRKR1", "AGE")),
        values(multiple = FALSE)
      ),
      strata_var = teal.picks::picks(
        datasets("ADSL"),
        teal.picks::variables(c("ARM", "COUNTRY", "SEX"), selected = NULL)
      ),
      group_var = teal.picks::picks(
        datasets("ADSL"),
        teal.picks::variables(c("ARM", "COUNTRY", "SEX"), selected = NULL)
      )
    )
  )
)
if (interactive()) {
  shinyApp(app$ui, app$server)
}

Run the code above in your browser using DataLab