Getting started with teal.modules.clinical

Introduction

teal.modules.clinical is a package implementing a number of teal modules helpful for exploring clinical trials data, specifically targeted at data following the ADaM standards. teal.modules.clinical modules can be used with data other than ADaM standard clinical data but some features of the package will make little sense then.

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.

Main features

The package provides ready-to-use teal modules you can embed in your teal application. The modules generate highly customizable tables, plots and outputs often used in exploratory data analysis, e.g.:

• ANCOVA - tm_t_ancova()
• cox regression - tm_t_coxreg()
• Kaplan-Meier plot - tm_g_km()
• logistic regression - tm_t_logistic()
• bar chart - tm_g_barchart_simple()
• confidence interval plot - tm_g_ci()
• binary outcome response table - tm_t_binary_outcome()
• summary of adverse events table - tm_t_events_summary()
• SMQ table - tm_t_smq()
• time to event table - tm_t_tte()

The library also offers a group of patient profile modules targeted for clinical statisticians and physicians who want to review data on a per patient basis. The modules present data about patient’s adverse events, their severity, the current therapy, their laboratory results and more.

See package functions / modules.

A simple application

A teal.modules.clinical module needs to be embedded inside a shiny / teal application to interact with it. A simple application including a bar chart module could look like this:

library(teal.modules.clinical)
library(nestcolor)

adsl <- tmc_ex_adsl
adae <- tmc_ex_adae

app <- teal::init(
  data = teal.data::cdisc_data(
    teal.data::cdisc_dataset("ADSL", adsl),
    teal.data::cdisc_dataset("ADAE", adae)
  ),
  modules = list(
    tm_g_barchart_simple(
      label = "ADAE Analysis", 
      x = teal.transform::data_extract_spec(
        dataname = "ADAE",
        select = teal.transform::select_spec(
          choices = teal.transform::variable_choices(adae),
          multiple = FALSE
        )
      )
    )
  )
)

if (interactive()) shiny::shinyApp(app$ui, app$server)

teal.modules.clinical exports modules and needs support from other libraries to run a teal app and flesh out its functionality. In the example above, tm_g_barchart_simple is the only function from teal.modules.clinical where as init is a teal function, data_extract_spec, select_spec and variable_choices are teal.transform functions and cdisc_dataset and cdisc_data are teal.data functions.

Let’s break the above app into pieces:

library(teal.modules.clinical)
library(nestcolor)

The above lines load the libraries used in this example. We will use the example data provided in the teal.modules.clinical package:

adsl <- tmc_ex_adsl
adae <- tmc_ex_adae

nestcolor is an optional package that can be loaded in to apply the standardized NEST color palette to all module plots.

There is no need to load teal as teal.modules.clinical 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 ADaM datasets adsl and adae - and the modules argument indicates the modules included in the application. Here, we include only one - tm_g_barchart_simple.

app <- teal::init(
  data = teal.data::cdisc_data(
    teal.data::cdisc_dataset("ADSL", adsl),
    teal.data::cdisc_dataset("ADAE", adae)
  ),
  modules = list(
    tm_g_barchart_simple(
      label = "ADAE Analysis", 
      x = teal.transform::data_extract_spec(
        dataname = "ADAE",
        select = teal.transform::select_spec(choices = teal.transform::variable_choices(adae), multiple = FALSE)
      )
    )
  )
)

Ultimately, the example uses shiny to launch the application:

if (interactive()) shiny::shinyApp(app$ui, app$server)

Some of teal.modules.clinical modules allow specifying arguments using teal.transform::choices_selected such as tm_t_summary module in this example:

adsl <- tmc_ex_adsl
app <- teal::init(
  data = teal.data::cdisc_data(teal.data::cdisc_dataset("ADSL", adsl)),
  modules = list(
    tm_t_summary(
      label = "Demographic Table",
      dataname = "ADSL",
      arm_var = teal.transform::choices_selected(choices = c("ARM", "ARMCD"), selected = "ARM"),
      summarize_vars = teal.transform::choices_selected(
        choices = c("SEX", "RACE", "BMRKR2", "EOSDY", "DCSREAS", "AGE"),
        selected = c("SEX", "RACE")
      )
    )
  )
)
if (interactive()) shiny::shinyApp(app$ui, app$server)

Refer to the API reference of the specific modules for more examples and information on the level of customization available.