diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 651f1c3e4f..7c429caeb2 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -64,3 +64,5 @@ repos: \.github/.*\.yaml| data/.* )$ + - id: no-browser-statement + name: Check for browser() statement diff --git a/DESCRIPTION b/DESCRIPTION index eda70618ed..95328de84b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Type: Package Package: teal Title: Exploratory Web Apps for Analyzing Clinical Trials Data -Version: 0.14.0.9009 -Date: 2023-09-20 +Version: 0.14.0.9012 +Date: 2023-10-13 Authors@R: c( person("Dawid", "Kaledkowski", , "dawid.kaledkowski@roche.com", role = c("aut", "cre")), person("Pawel", "Rucki", , "pawel.rucki@roche.com", role = "aut"), diff --git a/NAMESPACE b/NAMESPACE index 4711ead7a4..fbf4258c0c 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -27,6 +27,7 @@ export(init) export(module) export(modules) export(new_tdata) +export(report_card_template) export(reporter_previewer_module) export(show_rcode_modal) export(srv_teal_with_splash) diff --git a/NEWS.md b/NEWS.md index f9f41e020b..55545d90bf 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# teal 0.14.0.9009 +# teal 0.14.0.9012 ### Miscellaneous diff --git a/R/utils.R b/R/utils.R index d73dc67258..730153afbf 100644 --- a/R/utils.R +++ b/R/utils.R @@ -69,3 +69,34 @@ teal_data_to_filtered_data <- function(x) { # nolint check = FALSE ) } + +#' Template Function for `TealReportCard` Creation and Customization +#' +#' This function generates a report card with a title, +#' an optional description, and the option to append the filter state list. +#' +#' @param title (`character(1)`) title of the card (unless overwritten by label) +#' @param label (`character(1)`) label provided by the user when adding the card +#' @param description (`character(1)`) optional additional description +#' @param with_filter (`logical(1)`) flag indicating to add filter state +#' @param filter_panel_api (`FilterPanelAPI`) object with API that allows the generation +#' of the filter state in the report +#' +#' @return (`TealReportCard`) populated with a title, description and filter state +#' +#' @export +report_card_template <- function(title, label, description = NULL, with_filter, filter_panel_api) { + checkmate::assert_string(title) + checkmate::assert_string(label) + checkmate::assert_string(description, null.ok = TRUE) + checkmate::assert_flag(with_filter) + checkmate::assert_class(filter_panel_api, classes = "FilterPanelAPI") + + card <- teal::TealReportCard$new() + title <- if (label == "") title else label + card$set_name(title) + card$append_text(title, "header2") + if (!is.null(description)) card$append_text(description, "header3") + if (with_filter) card$append_fs(filter_panel_api$get_filter_state()) + card +} diff --git a/README.md b/README.md index 9c43676eaa..097a4c24cd 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# `teal`: Interactive Exploratory Data Analysis with Shiny Web-Applications +# `teal`: Interactive Exploratory Data Analysis with Shiny Web-Applications [![Check 🛠](https://github.com/insightsengineering/teal/actions/workflows/check.yaml/badge.svg)](https://insightsengineering.github.io/teal/main/unit-test-report/) @@ -105,7 +105,7 @@ shinyApp(app$ui, app$server) Please see [`teal.gallery`](https://insightsengineering.github.io/teal.gallery) and [TLG Catalog](https://insightsengineering.github.io/tlg-catalog) to see examples of `teal` apps. -Please start with the ["Getting Started" article](https://insightsengineering.github.io/teal/latest-tag/articles/teal.html) and then other [package vignettes](https://insightsengineering.github.io/teal/articles/index.html) for more detailed guide. +Please start with the ["Technical Blueprint" article](https://insightsengineering.github.io/teal/latest-tag/articles/blueprint/index.html), ["Getting Started" article](https://insightsengineering.github.io/teal/latest-tag/articles/teal.html), and then other [package vignettes](https://insightsengineering.github.io/teal/latest-tag/articles/index.html) for more detailed guide. ## Getting help diff --git a/_pkgdown.yml b/_pkgdown.yml index f7afd6b568..9525fbdd7a 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -6,7 +6,7 @@ template: navbar: structure: - left: [intro, reference, articles, tutorials, news, reports] + left: [intro, reference, articles, blueprint, tutorials, news, reports] right: [search, github] components: reports: @@ -16,33 +16,77 @@ navbar: href: coverage-report/ - text: Unit test report href: unit-test-report/ + blueprint: + text: Technical Blueprint + menu: + - text: About Blueprint + href: articles/blueprint/index.html + - text: Introduction + href: articles/blueprint/intro.html + - text: Actors + href: articles/blueprint/actors.html + - text: Data Flow + href: articles/blueprint/dataflow.html + - text: Product Map + href: articles/blueprint/products_map.html + - text: Features + navbar: Features + - text: "`qenv`" + href: articles/blueprint/qenv.html + - text: Filter Panel + href: articles/blueprint/filter_panel.html + - text: Delayed Data Loading (DDL) + href: articles/blueprint/ddl.html + - text: Module and Encapsulation + href: articles/blueprint/module_encapsulation.html + github: icon: fa-github href: https://github.com/insightsengineering/teal articles: - - title: Get Started - navbar: ~ - contents: - - teal - - title: Articles - navbar: Using teal - contents: - - filter-panel - - teal-options - - teal-bs-themes - - title: Articles - navbar: Data in teal Apps - contents: - - including-adam-data-in-teal - - including-general-data-in-teal - - including-mae-data-in-teal - - preprocessing-data - - title: Articles - navbar: Extending teal - contents: - - creating-custom-modules - - adding-support-for-reporting +- title: Get Started + navbar: ~ + contents: + - teal +- title: Using teal + navbar: Using teal + contents: + - filter-panel + - teal-options + - teal-bs-themes +- title: Data in teal Apps + navbar: Data in teal Apps + contents: + - including-adam-data-in-teal + - including-general-data-in-teal + - including-mae-data-in-teal + - preprocessing-data +- title: Extending teal + navbar: Extending teal + contents: + - creating-custom-modules + - adding-support-for-reporting +- title: 📃 Technical Blueprint + desc: > + The purpose of the blueprint is to aid new developer’s comprehension of the + fundamental principles of the `teal` framework. We will explore crucial `teal` + concepts such as data flow, actors, and filter panel, among others. + contents: + - blueprint/index + - blueprint/intro + - blueprint/actors + - blueprint/dataflow + - blueprint/products_map +- title: "" + desc: > + Features + contents: + - blueprint/qenv + - blueprint/filter_panel + - blueprint/ddl + - blueprint/module_encapsulation + reference: - title: Core `teal` Functions @@ -62,6 +106,7 @@ reference: contents: - reporter_previewer_module - TealReportCard + - report_card_template - title: Functions for Module Developers contents: - tdata diff --git a/inst/WORDLIST b/inst/WORDLIST index 02f29a34d2..a460fdae39 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -1,20 +1,30 @@ ADaM +CDISC +DDL Forkers Hoffmann MultiAssayExperiment +Pre +Reproducibility TLG Theming UI UIs UX +analysing cloneable +customizable +dropdown funder omics pharmaverse +pre preprocessed programmatically +qenv repo reproducibility +summarization tabsetted themer uncheck diff --git a/man/figures/filterpanel.png b/man/figures/filterpanel.png new file mode 100644 index 0000000000..020b6f3fad Binary files /dev/null and b/man/figures/filterpanel.png differ diff --git a/man/figures/notification.jpg b/man/figures/notification.jpg new file mode 100644 index 0000000000..a80c024f69 Binary files /dev/null and b/man/figures/notification.jpg differ diff --git a/man/figures/reporter.jpg b/man/figures/reporter.jpg new file mode 100644 index 0000000000..14eff4ec5f Binary files /dev/null and b/man/figures/reporter.jpg differ diff --git a/man/figures/showrcode.jpg b/man/figures/showrcode.jpg new file mode 100644 index 0000000000..b84e1f4bb4 Binary files /dev/null and b/man/figures/showrcode.jpg differ diff --git a/man/figures/teal.png b/man/figures/teal.png index e672a873c9..7c8438f2df 100644 Binary files a/man/figures/teal.png and b/man/figures/teal.png differ diff --git a/man/report_card_template.Rd b/man/report_card_template.Rd new file mode 100644 index 0000000000..1be43cf829 --- /dev/null +++ b/man/report_card_template.Rd @@ -0,0 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{report_card_template} +\alias{report_card_template} +\title{Template Function for \code{TealReportCard} Creation and Customization} +\usage{ +report_card_template( + title, + label, + description = NULL, + with_filter, + filter_panel_api +) +} +\arguments{ +\item{title}{(\code{character(1)}) title of the card (unless overwritten by label)} + +\item{label}{(\code{character(1)}) label provided by the user when adding the card} + +\item{description}{(\code{character(1)}) optional additional description} + +\item{with_filter}{(\code{logical(1)}) flag indicating to add filter state} + +\item{filter_panel_api}{(\code{FilterPanelAPI}) object with API that allows the generation +of the filter state in the report} +} +\value{ +(\code{TealReportCard}) populated with a title, description and filter state +} +\description{ +This function generates a report card with a title, +an optional description, and the option to append the filter state list. +} diff --git a/tests/testthat/test-utils.R b/tests/testthat/test-utils.R index 319dfe302b..e64f4265cf 100644 --- a/tests/testthat/test-utils.R +++ b/tests/testthat/test-utils.R @@ -10,3 +10,29 @@ testthat::test_that("get_teal_bs_theme", { testthat::expect_warning(get_teal_bs_theme(), "the default shiny bootstrap is used") }) }) + +testthat::test_that("report_card_template function returns TealReportCard object with appropriate content and labels", { + fd <- teal.slice::init_filtered_data(list(iris = list(dataset = iris))) + filter_panel_api <- teal.slice::FilterPanelAPI$new(fd) + + card <- shiny::isolate(report_card_template( + title = "Card title", + label = "Card label", + description = "Sample description", + with_filter = TRUE, + filter_panel_api = filter_panel_api + )) + testthat::expect_s3_class(card, c("TealReportCard")) + testthat::expect_equal(card$get_name(), "Card label") + testthat::expect_length(card$get_content(), 4) + + card <- shiny::isolate(report_card_template( + title = "Card title", + label = "", + with_filter = FALSE, + filter_panel_api = filter_panel_api + )) + testthat::expect_s3_class(card, c("TealReportCard")) + testthat::expect_equal(card$get_name(), "Card title") + testthat::expect_length(card$get_content(), 1) +}) diff --git a/vignettes/blueprint/_setup.Rmd b/vignettes/blueprint/_setup.Rmd new file mode 100644 index 0000000000..745980fa96 --- /dev/null +++ b/vignettes/blueprint/_setup.Rmd @@ -0,0 +1,10 @@ + +```{css, echo=FALSE} +pre.mermaid { + background: transparent; +} +``` + +```{r, echo=FALSE} +shiny::tags$script(type = "module", "import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/+esm'") +``` diff --git a/vignettes/blueprint/actors.Rmd b/vignettes/blueprint/actors.Rmd new file mode 100644 index 0000000000..3f73c3aa55 --- /dev/null +++ b/vignettes/blueprint/actors.Rmd @@ -0,0 +1,120 @@ +--- +title: "Actors" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Actors} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +There are two main actors in the `teal` development: + +* `teal` App Developer +* `teal` Module Developer + +## `teal` App Developer + +```{r, child="_setup.Rmd"} +``` + +```{r actors_mermaid1, echo=FALSE} +shiny::pre( + class = "mermaid", + " +%% This is a mermaid diagram, if you see this the plot failed to render. Sorry. +graph LR + A[teal App Developer]--utilizes--> B[teal modules] + B--to create--> C[teal app] + D[app user]--uses--> C +style A fill:lightblue +style C fill:gold +style D fill:pink +" +) +``` + +The primary responsibility of a `teal` app developer is to leverage the available building blocks of the `teal` framework to create a functional `teal` app that analyses the data. + +To expedite the app creation process, developers can take advantage of pre-existing `teal` modules found in R packages like `teal.modules.general` and `teal.modules.clinical`. + +These modules are designed with a focus on standardization and versatility, making them suitable for a wide range of use cases. + +When developing a `teal` app, the developer will select the most appropriate `teal` modules and integrate them into the app's interface to ensure seamless usability for end-users. + +To learn more about the existing modules, visit [`teal.gallery`](https://insightsengineering.github.io/teal.gallery/) that contains several demo applications and their source code. + +## `teal` Module Developer + +```{r actors_mermaid2, echo=FALSE} +shiny::pre( + class = "mermaid", + " +%% This is a mermaid diagram, if you see this the plot failed to render. Sorry. +graph LR + A[Teal App Developer]--utilizes--> B[teal modules] + E[Teal Module Developer]--develops--> B + B--to create--> C[teal app] + D[app user]--uses--> C +style A fill:lightblue +style E fill:lightgreen +style D fill:pink +style C fill:gold +" +) +``` + +The main duty of a `teal` module developer is to construct a compatible `teal` module that can be utilized within the `teal` framework. + +Several factors influence the scope and requirements for building a `teal` module. + +When creating a reusable `teal` module, it's advisable to focus on making it as general and adaptable as feasible to maximize the possibilities of being re-used in the future. +However, developers have the freedom to create a `teal` module that is customized to suit the specific demands of a project. + +Ultimately, one or more `teal` modules are employed to construct a `teal` app. + +To learn more about creating custom modules follow the [Tutorial on Creating a Custom Module](https://insightsengineering.github.io/teal/latest-tag/articles/creating-custom-modules.html). + +## Workflow in a Clinical Trial Study + +```{r actors_mermaid3, echo=FALSE} +shiny::pre( + class = "mermaid", + " +%% This is a mermaid diagram, if you see this the plot failed to render. Sorry. +%%| fig-width: 7.5 +graph LR + subgraph Study B + A2[Study Teal App Developer]--utilizes--> B2[teal modules] + E2[Study Teal Module Developer]-.develops.-> B2 + B2--to create--> C2[study teal app] + D2[study app user]--uses--> C2 + end + E3[Teal Module Developer]--develops--> B + E3--develops-->B2 + subgraph Study A + A[Study Teal App Developer]--utilizes--> B[teal modules] + E[Study Teal Module Developer]-.develops.-> B + B--to create--> C[study teal app] + D[study app user]--uses--> C + end +style A fill:lightblue +style A2 fill:lightblue +style E fill:limegreen +style E2 fill:limegreen +style E3 fill:lightgreen +style D fill:pink +style D2 fill:pink +style C fill:gold +style C2 fill:gold +" +) +``` + +In a clinical trial study setting, a unique **study `teal` app developer** is assigned to each study team and is accountable for developing a tailored `teal` app for their respective study. + +The **study `teal` app developer** will initially leverage existing `teal` modules from R packages created by **`teal` module developers**. + +In cases where there is a need to create new modules tailored to the study, a **study `teal` module developer** will need to be involved. + +Upon completion, each study team will have their own designated `teal` app tailored to their specific study. diff --git a/vignettes/blueprint/dataflow.Rmd b/vignettes/blueprint/dataflow.Rmd new file mode 100644 index 0000000000..496015a742 --- /dev/null +++ b/vignettes/blueprint/dataflow.Rmd @@ -0,0 +1,42 @@ +--- +title: "Data Flow" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Data Flow} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, child="_setup.Rmd"} +``` + +```{r dataflow_mermaid1, echo=FALSE} +shiny::pre( + class = "mermaid", + " +%% This is a mermaid diagram, if you see this the plot failed to render. Sorry. +sequenceDiagram; + autonumber + participant data + participant filters + participant filtered data + participant teal module + data->filters: gets + filters->>filtered data: becomes + filtered data->>teal module: sent to +" +) +``` + +The sequence diagram above illustrates the different stages that data goes through within the `teal` framework, supported by the `teal.slice` R package: + +1. Data is loaded into the `teal` app; + - See the [Filter panel vignette](filter_panel.html) for details; +2. Data is passed to the filter panel; + - Users _(or app developers)_ can specify filters to apply; + - Filters can be specified globally, for the whole app, or for specific modules; +3. Filtered data is sent to `teal` modules for analysis; + - Each module creates a [`qenv`](qenv.html) object track the code that is be applied to the data _(and used for reproducibility)_; + +Whenever filters are added or removed, the data coming into modules is re-computed, providing the `teal` module with new filtered data to conduct the required analysis. diff --git a/vignettes/blueprint/ddl.Rmd b/vignettes/blueprint/ddl.Rmd new file mode 100644 index 0000000000..bcf1767a3a --- /dev/null +++ b/vignettes/blueprint/ddl.Rmd @@ -0,0 +1,47 @@ +--- +title: "Delayed Data Loading (DDL)" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Delayed Data Loading (DDL)} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +## Introduction + +The `teal` framework introduced the Delayed Data Loading mechanism to enhance the user experience while reading and loading data in the app. + +## Background + +Usually, when running a shiny app, the dataset must be immediately available in the session for processing and reading. However, if the data is stored externally (such as in a database or other data repository), loading the shiny app may be delayed because the data needs to be fetched first. +If there is additional data processing code, this may further extend the loading process. + +To address this, we created the Delayed Data Loading mechanism. Learn how to use it [here](https://insightsengineering.github.io/teal.data/latest-tag/articles/using-delayed-data-basic.html). + +## What is Delayed Data Loading? + +Delayed Data Loading is an R object managed in `teal.data`, which stores instructions on how to obtain the data, including how to read and process it before it is used in `teal`. +By adopting this approach, `teal` apps can load more quickly, and the data can be fetched after the app is loaded. + +## Splash Screen + +`teal` provides a comprehensive solution for managing the delayed data loading mechanism, which includes the incorporation of a splash screen. +The splash screen serves as a visual cue to the user that data is being loaded and that they should wait for the app to be ready. + +Moreover, the splash screen can be modified to query the user for a password or other access credentials needed to fetch the data. +In cases where the modified splash screen is used, `teal` will display the customized version to prompt the user for the necessary information. + +After the data is fetched and loaded, `teal` removes the splash screen and replaces it with the content of the corresponding `teal` modules. +`teal` also displays a notification indicating that the data has been loaded, and the app has fully started up. + +![Notification that the data is loaded and app is ready to use](../../reference/figures/notification.jpg) + +## Additional resources + +The vignettes on `teal.data` documentation provide with basic and advanced examples for this feature. + +- [Pre-processing Delayed Data](https://insightsengineering.github.io/teal.data/latest-tag/articles/preprocessing-delayed-data.html) +- [Using Delayed Data Loading (basic)](https://insightsengineering.github.io/teal.data/latest-tag/articles/using-delayed-data-basic.html) +- [Creating Delayed Data Classes (Advanced)](https://insightsengineering.github.io/teal.data/latest-tag/articles/using-delayed-data-advanced.html) +- [Testing Delayed Data Loading](https://insightsengineering.github.io/teal.data/latest-tag/articles/testing-delayed-data.html) diff --git a/vignettes/blueprint/filter_panel.Rmd b/vignettes/blueprint/filter_panel.Rmd new file mode 100644 index 0000000000..2fb0691049 --- /dev/null +++ b/vignettes/blueprint/filter_panel.Rmd @@ -0,0 +1,57 @@ +--- +title: "Filter Panel" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Filter Panel} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +## Introduction + + + + + +The `teal.slice` package provides `teal` applications with the **filter panel**, a powerful tool for exploring and analyzing data, and a key component of the `teal` framework. + +One of the great things about the filter panel is that it comes built-in with `teal`, requiring no programming knowledge to use. + +The filter panel provides a convenient way for users to subset their data, simplifying the process of exploration and comprehension. +Moreover, users can activate or deactivate filter states interactively, either individually or globally, using the filter panel. + + +
+ +## Filter Flow + +```{r, child="_setup.Rmd"} +``` + +```{r dataflow_mermaid1, echo=FALSE} +shiny::pre( + class = "mermaid", + " +%% This is a mermaid diagram, if you see this the plot failed to render. Sorry. +sequenceDiagram + autonumber + data->teal.slice: processed by + teal.slice->>shiny inputs: creates + Note over teal.slice,shiny inputs: based on data type + shiny inputs->>reactive dataset: updates + reactive dataset->>teal modules: processed by +" +) +``` + +The filter panel creates subsets of data. Subsetting is achieved by creating filter states, each of which holds a logical predicate (filter condition) that is applied to single variables. These filter conditions are composed into a single expression, a call to a particular function (e.g. `dplyr::filter`), and that expression is evaluated to create a filtered data subset. + +The process is entirely interactive. Filter states can be created, removed, and changed at will, however, the app developer may choose to constrain or even restrict them. + +When a filter state is created, the filter panel generates a _filter card_ with `shiny` inputs appropriate to the type of the variable, e.g. range selectors for numeric columns and sets of checkboxes or dropdown menus for categorical ones. + +As users interact with the filter cards, the subsetting complete expression is updated and filtered data is recomputed. + +The filtered data is passed to `teal` modules for downstream analysis. The subsetting expression is returned along with the data, ensuring an unbroken track record of the entire analysis. Signature of the data are also stored to ensure reproducible results. + diff --git a/vignettes/blueprint/index.Rmd b/vignettes/blueprint/index.Rmd new file mode 100644 index 0000000000..135a2df075 --- /dev/null +++ b/vignettes/blueprint/index.Rmd @@ -0,0 +1,18 @@ +--- +title: "About Technical Blueprint" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{About Technical Blueprint} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +Welcome to `teal` Technical Blueprint documentation! + +The purpose of this material is to aid new developer's comprehension of the fundamental principles of the `teal` framework. +We will explore crucial `teal` concepts such as data flow, actors, and filter panel, among others. + +While this material will be presented at a high-level, we will direct you to our vignettes for a more in-depth understanding. + +Our hope is that this resource will provide new developers with a strong grasp of `teal` products, enabling them to contribute to code with confidence. diff --git a/vignettes/blueprint/intro.Rmd b/vignettes/blueprint/intro.Rmd new file mode 100644 index 0000000000..fe3eea200c --- /dev/null +++ b/vignettes/blueprint/intro.Rmd @@ -0,0 +1,38 @@ +--- +title: "Introduction" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Introduction} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +`teal` is an interactive data exploration framework based on Shiny, designed with emphasis on analyzing CDISC clinical trial data. + +A Shiny Application created with `teal` offers users the ability to: + +- Import data from external sources; +- Dynamically filter data for analysis; +- Generate reproducible code for future analysis +- Create downloadable reports of analysis results _(for analysis modules that support reporting)_. + +Moreover, the `teal` framework provides application developers with a wide range of customizable standard analysis modules to integrate into their applications, along with a logging framework that helps facilitate debugging. +Additionally, advanced users of the framework can develop new analysis modules and easily integrate them into any `teal` application. + +The `teal` framework's functionality draws heavily from the following packages: + +| R package | Description | +|----------------------|:------------------------------------------------------------------------| +|[`teal`](https://github.com/insightsengineering/teal) | `shiny`-based interactive exploration framework for analyzing data| +|[`teal.data`](https://github.com/insightsengineering/teal.data) | creating and loading the data needed for `teal` applications| +|[`teal.widgets`](https://github.com/insightsengineering/teal.widgets) | `shiny` UI components used within `teal`| +|[`teal.slice`](https://github.com/insightsengineering/teal.slice) | provides a filtering panel to allow filtering of data| +|[`teal.code`](https://github.com/insightsengineering/teal.code) | handles reproducibility of outputs| +|[`teal.transform`](https://github.com/insightsengineering/teal.transform) | standardizes extracting and merging data| +|[`teal.logger`](https://github.com/insightsengineering/teal.logger) | standardizes logging within `teal` framework| +|[`teal.reporter`](https://github.com/insightsengineering/teal.reporter) | allows `teal` applications to generate reports| + +Although these packages are mentioned in the material, we strongly recommend visiting their vignettes to learn more about them. + +Learn on how to make your first `teal` application [here](https://insightsengineering.github.io/teal/main/articles/teal.html)! diff --git a/vignettes/blueprint/module_encapsulation.Rmd b/vignettes/blueprint/module_encapsulation.Rmd new file mode 100644 index 0000000000..9ce5420f21 --- /dev/null +++ b/vignettes/blueprint/module_encapsulation.Rmd @@ -0,0 +1,30 @@ +--- +title: "Module Encapsulation" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Module Encapsulation} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +## Introduction + +The `teal` framework leverages the [`shiny` module concept](https://rstudio.github.io/shiny/reference/moduleServer.html) to enable encapsulation of analytical actions in `teal` modules, while maintaining seamless communication between the modules and the application. + + +## Benefits + +By implementing the modular app technique from the shiny module into the creation of the teal module, several benefits are realized: + +1. Streamlined maintenance + The development of the teal module becomes more manageable, as it can function independently from the teal framework. + This separation allows developers to maintain the module with ease. This approach has been successfully applied in R packages dedicated to teal module development, such as `teal.modules.general` and `teal.modules.clinical`. + +1. Enhanced focus on output + `teal` module developers can concentrate solely on refining parameters or encoding, and output aspects (such as data summarization and visualization) without the need to concern themselves with the intricacies of the teal framework. + When developed correctly, the module seamlessly integrates with `teal`. + +1. Facilitated Collaboration + `teal` module development becomes an accessible entry point for developers interested in collaborating. + This approach encourages user collaboration for the improvement of teal modules, as developers gain a deeper understanding of the mechanics of the teal framework. diff --git a/vignettes/blueprint/products_map.Rmd b/vignettes/blueprint/products_map.Rmd new file mode 100644 index 0000000000..6bf18283dc --- /dev/null +++ b/vignettes/blueprint/products_map.Rmd @@ -0,0 +1,83 @@ +--- +title: "Products Map" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Products Map} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, child="_setup.Rmd"} +``` + +```{r, echo=FALSE} +shiny::pre( + class = "mermaid", + " +%% This is a mermaid diagram, if you see this the plot failed to render. Sorry. +flowchart RL +teal +subgraph features + direction LR + teal.data + teal.slice + teal.transform + teal.code + teal.logger + teal.widgets +end +subgraph modules + direction RL + teal.modules.general + teal.modules.clinical + teal.osprey + teal.goshawk + teal.modules.hermes +end +teal--has-->features +features--builds-->modules +modules--creates-->teal +subgraph modules + teal.modules.general + teal.modules.clinical + teal.osprey + teal.goshawk + teal.modules.hermes +end +subgraph calculations + direction RL + tern + osprey + goshawk + hermes +end +tern--supports-->teal.modules.clinical +osprey--supports-->teal.osprey +goshawk--supports-->teal.goshawk +hermes--supports-->teal.modules.hermes +style teal fill:lightblue +style features fill:lightgreen +style modules fill:pink +" +) +``` + +`teal` is a modular framework that relies on a suite of related R packages, as illustrated in the above diagram, to provide a wide range of functionalities. + +`teal`'s primary function is to create web app for analysing clinical trial data, but it **has** a multitude of features distributed across various R packages. + +Developers can selectively leverage these R packages, such as `teal.widgets`, `teal.code`, and `teal.logger`, to **build** `teal` modules for a `teal` app. This approach gives the developers the tools that speed up their work and avoid re-implementing existing logic and UI elements. + +The `teal` modules utilize various R packages such as `tern`, `osprey`, and `goshawk` to perform calculations and analyses. +These R packages provide **support** to the `teal` modules by performing all computations while the modules only have to focus on how to wrap the input options and the output. + +Once developed, new and existing modules can be integrated into `teal` to **create** a functional `teal` app. + +## Why so many R packages? + +By breaking down `teal` features, modules, and calculations into dedicated R packages, maintenance is made significantly more manageable. + +Additionally, this separation allows for a clear distinction between the various roles and actors involved in the development of `teal`. + +To learn different roles/actors in `teal` development, visit [Actors](actors.html). diff --git a/vignettes/blueprint/qenv.Rmd b/vignettes/blueprint/qenv.Rmd new file mode 100644 index 0000000000..341238fef0 --- /dev/null +++ b/vignettes/blueprint/qenv.Rmd @@ -0,0 +1,61 @@ +--- +title: "`qenv`" +author: "NEST CoreDev" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{`qenv`} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +## Introduction + +Reproducibility is paramount in the pharmaceutical industry. +Accurate and consistent results are essential to ensure high-quality research and the safety of patients. +By prioritizing reproducibility, researchers can validate their methods, confirm their findings, and contribute to the advancement of the field. + +[`qenv`](https://insightsengineering.github.io/teal.code/latest-tag/articles/qenv.html) is an essential feature provided by the `teal.code` package that facilitates code reproducibility. +It is a class that stores both data and code, which enables tracking of the analytical process, and thus allows for sharing and replication of R code. +Code is passed to a `qenv` object, where it is evaluated in a specific environment and stored, and can be retrieved on request. + +## `qenv` in a `teal` application + +In a `teal` application, a `qenv` object is created by the module developer in the module's server function. All data operations and their R code are appended and stored within the `qenv`'s environment, which allows for the code to be evaluated and executed in the `teal` application, and reproduced outside the `teal` application. This includes data loading, preprocessing, filtering, transformations, and plotting, etc. + +The `qenv` object makes it easy for users to reproduce and validate the results of their analyses. + +```{dot qenv_dot_diagram, echo=FALSE} +digraph G { + qenv [label = "qenv"]; + node [shape=box]; + teal_modules [label = "teal modules analysis R code"]; + library [label = "R library() calls"]; + filter_states [label = "filter states R code"]; + data [label = "data preprocessing R code"]; + teal_modules -> qenv; + library -> qenv; + edge [dir="back"]; + qenv -> filter_states; + qenv -> data; +} +``` + +Learn more about the use of `qenv` in [`teal` custom module](https://insightsengineering.github.io/teal/main/articles/creating-custom-modules.html) vignette. + +## `Show R Code` and `Reporter` + +In both the `teal.modules.clinical` and `teal.modules.general` R packages, you'll find that most modules include a convenient `Show R Code`button. +When this button is clicked, a modal window appears, revealing the R code responsible for generating the module's output. +This functionality is achieved by inspecting the qenv object, which contains the stored code. +With the Show R Code button, users can now easily copy and independently run the code to reproduce the same analysis presented in the teal module. + +![Show R Code](../../man/figures/showrcode.jpg){width=50%} + +The Reporter feature also leverages the qenv object in its operation. +Much like the Show R Code mechanism, the code displayed in a Reporter Card is extracted from the qenv object. + +![Reporter](../../man/figures/reporter.jpg){width=50%} + +To learn more about the `Reporter` feature, please visit the [teal.reporter documentation](https://insightsengineering.github.io/teal.reporter/latest-tag/index.html). + +Overall, `qenv` from `teal.code` is a powerful tool for ensuring code reproducibility and promoting high-quality research in the R programming language. diff --git a/vignettes/blueprint/reporter.jpg b/vignettes/blueprint/reporter.jpg new file mode 100644 index 0000000000..14eff4ec5f Binary files /dev/null and b/vignettes/blueprint/reporter.jpg differ diff --git a/vignettes/images/reporter.jpg b/vignettes/images/reporter.jpg new file mode 100644 index 0000000000..14eff4ec5f Binary files /dev/null and b/vignettes/images/reporter.jpg differ