-
-
Notifications
You must be signed in to change notification settings - Fork 45
/
Copy pathgetting-started-with-teal.Rmd
164 lines (120 loc) · 8.11 KB
/
getting-started-with-teal.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
---
title: "Getting Started with teal"
author: "NEST CoreDev"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Getting Started with teal}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
## 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 `iris` and `mtcars` datasets and displays their contents:
```{r setup, include=FALSE}
library(teal)
```
```{r app}
library(teal)
app <- init(
data = teal_data(IRIS = iris, MTCARS = mtcars),
modules = modules(
example_module("Module 1"),
example_module("Module 2")
),
filter = teal_slices(
teal_slice(dataname = "IRIS", varname = "Species", selected = "setosa")
)
) |>
modify_title("My first teal application") |>
modify_header(h3("My first teal application")) |>
modify_footer(tags$div(a("Powered by teal", href = "https://insightsengineering.github.io/teal/latest-tag/")))
if (interactive()) {
shinyApp(app$ui, app$server)
}
```
<style>
.teal-example {
display: none;
}
span:hover .teal-components {
display: none;
}
span:hover .teal-example {
display: inline-block;
}
</style>
_Hovering_ the image shows the `teal` application generated by this code.
<!-- These images can be edited with Inkscape or online tools that handle SVG (vectorial) format -->
<span>
<img class="teal-components" src="images/teal-app-components.svg" alt="Example application" style="width: 100%;" />
<img class="teal-example" src="images/teal-app-components-hover.svg" alt="Example application (hover)" style="width: 100%;" />
</span>
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:
* <span style="color: #BF37F3;">Application Title</span> _(browser's tab title)_: is the title of the application.
* <span style="color: #FB6251;">Application Header and Footer</span> _(the top and the bottom of the app)_: any content to be placed at the top and bottom of the application.
* <span style="color: #f2b73f;">Teal Modules</span> _(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".
* <span style="color: #83cc41;">Module Content</span> _(panel on the middle)_: the outputs of the currently active module.
* <span style="color: #3A88FE;">Filter Panel</span> _(panel on the right hand side)_: for filtering the data to be passed into all `teal` modules.
* In the example code: the filter panel is being initialized with a filter for the `Species` variable in the `iris` dataset.
## Try the above app in `shinylive`
```{r shinylive_iframe, echo = FALSE, out.width = '150%', out.extra = 'style = "position: relative; z-index:1"', eval = requireNamespace("roxy.shinylive", quietly = TRUE) && knitr::is_html_output() && identical(Sys.getenv("IN_PKGDOWN"), "true")}
code <- paste0(c(
"interactive <- function() TRUE",
knitr::knit_code$get("app")
), collapse = "\n")
url <- roxy.shinylive::create_shinylive_url(code)
knitr::include_url(url, height = "800px")
```
## 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 through `teal_data` object.
It is also possible to specify relationships between the datasets using the `join_keys` argument but in this case the datasets are not related. See [this vignette](including-data-in-teal-applications.html) for details.
If data is not available and has to be pulled from a remote source, `init` must receive a `teal_data_module` that specifies how to obtain the desired datasets and put them into a `teal_data` object.
See [this vignette](data-as-shiny-module.html) for details.
In order to use CDISC clinical trial data in a `teal` application the `cdisc_data` function is used instead.
Custom `SDTM` standards can be handled with `teal_data` and `join_keys`.
For further details, we recommend exploring the [`teal.data`](https://insightsengineering.github.io/teal.data/) package 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](creating-custom-modules.html).
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](filter-panel.html).
### Reporting
If any of the `modules` in your `teal` application support reporting (see [`teal.reporter`](https://insightsengineering.github.io/teal.reporter/) for 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](adding-support-for-reporting.html).
### 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, the `example_module` function used above shows the code in the main panel together with other outputs.
For more details see [this vignette](including-data-in-teal-applications.html).
### Embedding teal in shiny application
Advanced `shiny` users can include teal application in their `shiny` application. For further details see [teal as a module](teal-as-a-shiny-module.html).
## Where to go next
To learn more about the `teal` framework we recommend first exploring some of the available analysis modules.
For example see:
* [general analysis modules](https://insightsengineering.github.io/teal.modules.general/)
* [clinical trial reporting modules](https://insightsengineering.github.io/teal.modules.clinical/)
* [modules for analyzing `MultiAssayExperiment` objects](https://insightsengineering.github.io/teal.modules.hermes/)
For a demo of `teal` apps see:
* [The gallery of sample apps based on teal](https://insightsengineering.github.io/teal.gallery/)
* [A catalog of Tables, Listings and Graphs](https://insightsengineering.github.io/tlg-catalog/)
* [A catalog of Biomarker Analysis Templates of Tables And Graphs](https://insightsengineering.github.io/biomarker-catalog/)
The `teal` framework relies on a set of supporting packages whose documentation provides more in-depth information.
The packages which are of most interest when defining `teal`applications are:
* [`teal.data`](https://insightsengineering.github.io/teal.data/): defining data for `teal` application.
* [`teal.slice`](https://insightsengineering.github.io/teal.slice/): defining data filtering before passing into `teal` modules.