Author: NEST CoreDev

# Getting started with teal.modules.general

#### NEST CoreDev

### Introduction

`teal` extends the `shiny` framework, enabling the creation of interactive GUI applications using the `R`. `shiny`, and `teal`facilitate 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)
    library(sparkline)

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

    # 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)

### Try it out in Shinylive

Open in Shinylive

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.data::rADSL
      ADTTE <- teal.data::rADTTE
    })
    join_keys(data) <- default_cdisc_join_keys[names(data)]

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)
    )

    if (interactive()) {
      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] "teal_app" "list"

      names(app)

      ## [1] "ui"     "server"