Getting Started with teal (original) (raw)

Introduction

teal is a shiny-based interactive exploration framework for analyzing data, with particular emphasis on CDISC clinical trial data. teal applications allow their users to:

• “Pull” in data from external data sources
• Dynamically filter of data to be used in the analyses
• Generate reproducible code to regenerate the on-screen analyses
• Create and download reports containing results of analyses (for analysis modules which support reporting)

In addition, the teal framework provides application developers with:

• A large suite of custom-made standard analysis modules to be included in applications
• A logging framework to facilitate debugging of applications

More advanced users of the framework can also create new analysis modules which can be added into any teal applications.

Your first teal application:

This simple teal application takes the irisand mtcars datasets and displays their contents:

Hovering the image shows the teal application generated by this code.

Every teal application is composed of the following elements, all of which can be controlled by the app developer by passing arguments to the init function:

• Application Title (browser’s tab title): is the title of the application.
• Application Header and Footer (the top and the bottom of the app): any content to be placed at the top and bottom of the application.
• Teal Modules (tabs under the header): tab for each module included in the application.
  • In the example code: there are two modules named “Module 1” and “Module 2”.
• Module Content (panel on the middle): the outputs of the currently active module.
• Filter Panel (panel on the right hand side): for filtering the data to be passed into allteal modules.
  • In the example code: the filter panel is being initialized with a filter for the Species variable in the irisdataset.

Try the above app in shinylive

Creating your own applications

The key function to use to create your teal application is init, which requires two mandatory arguments:data and modules. There are other optional arguments for init, which can be used to customize the application. Please refer to the documentation for init for further details.

Application data

The data argument in the init function specifies the data used in your application. All datasets which are about to be used in teal application must be passed throughteal_data object. It is also possible to specify relationships between the datasets using the join_keysargument but in this case the datasets are not related. See this vignette for details. If data is not available and has to be pulled from a remote source, init must receive a teal_data_modulethat specifies how to obtain the desired datasets and put them into ateal_data object. See this vignette for details.

In order to use CDISC clinical trial data in a tealapplication the cdisc_data function is used instead. CustomSDTM standards can be handled with teal_dataand join_keys.

For further details, we recommend exploring the teal.datapackage documentation.

Modules

The modules argument to init consists of a list of teal modules (which can be wrapped together using the function modules). Core teal developers have created several universal teal modules that can be useful in any teal application. To learn how to create your own modules, please explore Creating Custom Modules vignette. To use our predefined modules, see the references below for links to these modules.

Defining filters

The optional filter argument in init allows you to initialize the application with predefined filters. For further details see Filter Panel vignette.

Reporting

If any of the modules in your tealapplication support reporting (see teal.reporterfor more details), users of your application can add the outputs of the modules to a report. This report can then be downloaded and a special_Report Previewer_ module will be added to your application as an additional tab, where users can view and configure their reports before downloading them. See more details in this vignette.

Reproducible code

teal hands over data with reproducible code to every module included in the application. Note that teal does not display the code, that is the modules’ responsibility. For example, theexample_module function used above shows the code in the main panel together with other outputs. For more details see this vignette.

Embedding teal in shiny application

Advanced shiny users can include teal application in their shiny application. For further details see teal as a module.