Getting started with teal.modules.general

Introduction

teal is a package that extends the shiny framework to build interactive GUI applications using the R programming language. shiny, and hence teal, are implemented to allow the building of large applications by combining small, decoupled modules. teal.modules.general is a package consisting of a set of modules that are used to build teal applications. It is “general” in the sense that the intended functions of these modules are more fundamental. This is in contrast to the intended functions of its sister package, teal.modules.clinical, which is more specialized around clinical data. The modules of teal.modules.general can be combined with modules of 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 form
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 including a tm_variable_browser module could look like this:

library(scda)
library(teal.modules.general)

ADSL <- synthetic_cdisc_data("latest")$adsl # nolint
ADTTE <- synthetic_cdisc_data("latest")$adtte # nolint

app <- init(
  data = cdisc_data(
    cdisc_dataset("ADSL", x = ADSL, code = "ADSL <- synthetic_cdisc_data(\"latest\")$adsl"),
    cdisc_dataset("ADTTE", x = ADTTE, code = "ADTTE <- synthetic_cdisc_data(\"latest\")$adtte"),
    check = TRUE
  ),
  modules = modules(
    tm_variable_browser(
      label = "Variable browser",
      ggplot2_args = teal.widgets::ggplot2_args(
        labs = list(subtitle = "Plot generated by Variable Browser Module")
      ),
    )
  )
)

shinyApp(app$ui, app$server)

Let’s break the above app into pieces:

library(teal.modules.general)
library(scda)

The above lines load the libraries used in this example. scda is a package containing sample data which are loaded into two R objects:

ADSL <- synthetic_cdisc_data("latest")$adsl
ADAE <- synthetic_cdisc_data("latest")$adae

There is no need to load teal as teal.modules.general already depends on it.

In the next step, we use teal to create shiny ui and server functions so we can launch using shiny. The data argument tells teal about the input data - the two datasets ADSL and ADTTE - and the modules argument indicates the modules included in the application. Here, we include only one - tm_variable_browser.

app <- teal::init(
  data = teal.data::cdisc_data(
    teal.data::cdisc_dataset("ADSL", x = ADSL, code = "ADSL <- synthetic_cdisc_data(\"latest\")$adsl"),
    teal.data::cdisc_dataset("ADTTE", x = ADTTE, code = "ADTTE <- synthetic_cdisc_data(\"latest\")$adtte"),
    check = TRUE # to check if the code executes to the data provided, x, i.e. ADSL and ADTTE
  ),
  modules = modules(
    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 = teal.widgets::ggplot2_args(
        labs = list(subtitle = "Plot generated by Variable Browser Module")
      ),
    )
  )
)

The shiny function shinyApp used the ui and server objects to initialize the teal app.

shiny::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, which can be demonstrated by running:
```
class(app)
```
```
## [1] "list"
```
This list contains two R objects named ui and server.
```
names(app)
```
```
## [1] "ui"     "server"
```

NEST CoreDev Team

01.04.2022

Introduction

Main features

Example application