Getting Started with {teal.modules.clinical}

NEST CoreDev Team

2025-02-28

Introduction

teal.modules.clinical is a package implementing a number of teal modules helpful for exploring clinical trials data, specifically targeted towards 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 are tailored towards data of this type.

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 home page and 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, including:

• 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 the full index of package functions & modules here.

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 <- init(
  data = cdisc_data(
    ADSL = ADSL,
    ADAE = ADAE,
    code = "
      ADSL <- tmc_ex_adsl
      ADAE <- tmc_ex_adae
    "
  ),
  modules = list(
    tm_g_barchart_simple(
      label = "ADAE Analysis",
      x = data_extract_spec(
        dataname = "ADAE",
        select = select_spec(
          choices = variable_choices(
            ADAE,
            c(
              "ARM", "ACTARM", "SEX",
              "RACE", "SAFFL", "STRATA2"
            )
          ),
          selected = "ACTARM",
          multiple = FALSE
        )
      )
    )
  )
)

shinyApp(app$ui, app$server)

Try it out in Shinylive

Open in Shinylive

Consider consulting the documentation and examples of each module (e.g. ?tm_g_barchart_simple). In many, you can also find useful links to the TLG Catalog where additional example apps can be found.

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 whereas init() is a teal function, data_extract_spec(), select_spec(), and variable_choices() are teal.transform functions, and cdisc_data() is a teal.data function.

Let’s break the above app down 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 that we can launch using shiny. The data argument tells teal about the input data - the ADaM datasets ADSL and ADAE - and the modules argument indicates the modules included in the application. Here, we include only one module: tm_g_barchart_simple().

app <- init(
  data = cdisc_data(
    ADSL = ADSL,
    ADAE = ADAE,
    code = "
      ADSL <- tmc_ex_adsl
      ADAE <- tmc_ex_adae
    "
  ),
  modules = list(
    tm_g_barchart_simple(
      label = "ADAE Analysis",
      x = data_extract_spec(
        dataname = "ADAE",
        select = select_spec(
          choices = variable_choices(
            ADAE,
            c(
              "ARM", "ACTARM", "SEX",
              "RACE", "SAFFL", "STRATA2"
            )
          ),
          selected = "ACTARM",
          multiple = FALSE
        )
      )
    )
  )
)

Finally, we use shiny to launch the application:

shinyApp(app$ui, app$server)

Some teal.modules.clinical modules allow for the specification of arguments using teal.transform::choices_selected(), such as the tm_t_summary() module in the following example.

ADSL <- tmc_ex_adsl

app <- init(
  data = cdisc_data(ADSL = ADSL, code = "ADSL <- tmc_ex_adsl"),
  modules = list(
    tm_t_summary(
      label = "Demographic Table",
      dataname = "ADSL",
      arm_var = choices_selected(choices = c("ARM", "ARMCD"), selected = "ARM"),
      summarize_vars = choices_selected(
        choices = c("SEX", "RACE", "BMRKR2", "EOSDY", "DCSREAS", "AGE"),
        selected = c("SEX", "RACE")
      )
    )
  )
)

shinyApp(app$ui, app$server)

Please refer to the API reference of specific modules for more examples and information on the customization options available.