Getting started with teal.modules.general

Introduction

teal extends the shiny framework, enabling the creation of interactive GUI applications using the R. shiny, and tealfacilitate the development of extensive applications through combining small, decoupled modules. The teal.modules.general package consist of collection of modules essential for developing teal applications. It is “general” in the sense that the intended functions of these modules are more fundamental. This contrasts with the more specialized focus on clinical data found in the teal.modules.clinical package. The modules from teal.modules.general can be used in conjunction with modules from teal.modules.clinical and / or other shiny modules to build a large teal / shiny app.

The concepts presented here require knowledge about the core features of teal, specifically on how to launch a teal application and how to pass data into it. Therefore, it is highly recommended to refer to the README file and the introductory vignette of the teal package.

See also teal.modules.clinical’s README.

Main features

There are five areas of data science that teal.modules.general provides tools and solutions (modules) for:

• viewing data in tabular formats
• visualizing data in plots and graphs
• viewing data and files in a directory
• examining missing and extreme values in data
• performing data analysis

See package functions / modules.

Example application

A simple application featuring the tm_variable_browser() module:

# load libraries
library(teal.modules.general)
library(teal.widgets)

# teal_data object
data <- teal_data()
data <- within(data, {
  ADSL <- teal.modules.general::rADSL
  ADTTE <- teal.modules.general::rADTTE
})
datanames <- c("ADSL", "ADTTE")
datanames(data) <- datanames
join_keys(data) <- default_cdisc_join_keys[datanames]

# tm_variable_browser module
tm_variable_browser_module <- tm_variable_browser(
  label = "Variable browser",
  ggplot2_args = ggplot2_args(
    labs = list(subtitle = "Plot generated by Variable Browser Module")
  )
)

# initialize the app
app <- init(
  data = data,
  modules = modules(tm_variable_browser_module)
)

shinyApp(app$ui, app$server)

Let’s break the above app into pieces:

1: Load the necessary libraries and data.

library(teal.modules.general)
library(teal.widgets)

2: Construct a teal_data object containing that will serve as the source of data for the teal app. teal_data not only encapsulates the data for the app, but it also houses the code required to create the data to maintain reproducibility.

To do this, we create an empty teal_data object and evaluate code to produce the data within the teal_data object, so both the code and data are stored together.

Following this, we set the datanames and join_keys.

data <- teal_data()
data <- within(data, {
  ADSL <- teal.modules.general::rADSL
  ADTTE <- teal.modules.general::rADTTE
})
datanames <- c("ADSL", "ADTTE")
datanames(data) <- datanames
join_keys(data) <- default_cdisc_join_keys[datanames]

3: Initialize a teal application with specified data and modules, in this case, the module: tm_variable_browser, datasets:ADSL and ADTTE.

shiny::shinyApp() use the ui and server component to initialize the teal app.

tm_variable_browser_module <- tm_variable_browser(
  # module name to display in the GUI
  label = "Variable browser",
  # this argument takes a set of arguments to pass to ggplot2.
  # the arguments must have the same names as its ggplot2 counterpart, e.g. `subtitle`
  ggplot2_args = ggplot2_args(
    labs = list(subtitle = "Plot generated by Variable Browser Module")
  )
)

app <- init(
  data = data,
  modules = modules(tm_variable_browser_module)
)

shinyApp(app$ui, app$server)

In a teal app, data and modules are decoupled. In the app above:

• The app developer specified the data and assigned it to the data argument.

• The app developer specified the module and assigned it to the modules argument.

• The init function took these arguments and returned a list containing ui and server object, which can be demonstrated by running:

  class(app)

  ## [1] "list"

  names(app)

  ## [1] "ui"     "server"