diff --git a/R/module_teal.R b/R/module_teal.R index de8279a911..fbce6ed5bd 100644 --- a/R/module_teal.R +++ b/R/module_teal.R @@ -1,6 +1,6 @@ # This module is the main teal module that puts everything together. -#' Teal main app module +#' teal main app module #' #' This is the main teal app that puts everything together. #' diff --git a/README.md b/README.md index cbd7c39c37..220f2df423 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/) @@ -19,7 +19,7 @@ [![Open Issues](https://img.shields.io/github/issues-raw/insightsengineering/teal?color=red\&label=open%20issues)](https://github.com/insightsengineering/teal/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) -*teal* is a shiny-based interactive exploration framework for analyzing data. `teal` applications require app developers to specify: +`teal` is a shiny-based interactive exploration framework for analyzing data. `teal` applications require app developers to specify: - Data, which can be: @@ -48,23 +48,68 @@ A lot of the functionality of the `teal` framework derives from the following pa -See these packages for more information about how to use the different parts of the `teal` framework. +## Installation -Please see [`teal` gallery](https://github.com/insightsengineering/teal.gallery) and [TLG Catalog](https://github.com/insightsengineering/tlg-catalog) to see examples of `teal` apps. +```r +install.packages("teal", repos = c("https://insightsengineering.r-universe.dev", getOption("repos"))) -## Installation +# install.packages("pak") +pak::pak("insightsengineering/teal@*release") +``` -From July 2023 `insightsengineering` packages are available on [r-universe](https://r-universe.dev/). +Alternatively, you might also use the development version. ```r -# stable versions -install.packages('teal', repos = c('https://insightsengineering.r-universe.dev', 'https://cloud.r-project.org')) +install.packages("teal", repos = c("https://pharmaverse.r-universe.dev", getOption("repos"))) + +# install.packages("pak") +pak::pak("insightsengineering/teal") +``` -# beta versions -install.packages('teal', repos = c('https://pharmaverse.r-universe.dev', 'https://cloud.r-project.org')) +## Usage + +```r +library(teal) + +app <- init( + data = teal_data( + dataset("iris", iris) + ), + modules = list( + module( + "iris histogram", + server = function(input, output, session, data) { + output$hist <- renderPlot( + hist(data[["iris"]]()[[input$var]]) + ) + }, + ui = function(id, data, ...) { + ns <- NS(id) + list( + shiny::selectInput( + ns("var"), + "Column name", + names(data[["iris"]]())[1:4] + ), + plotOutput(ns("hist")) + ) + } + ) + ) +) + +shinyApp(app$ui, app$server) ``` -See package vignettes `browseVignettes(package = "teal")` for usage of this package. +![App recording](./inst/readme_app.gif) + +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/articles/teal.html) and then other [package vignettes](https://insightsengineering.github.io/teal/articles/index.html) for more detailed guide. + +## Getting help + +If you encounter a bug or you have a feature request - please file an issue. For questions, discussions and staying up to date, please use the "teal" channel in the [pharmaverse slack workspace](https://pharmaverse.slack.com). ## Acknowledgment diff --git a/_pkgdown.yml b/_pkgdown.yml index f2d67c0ef9..5e9ef259ee 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -12,10 +12,10 @@ navbar: reports: text: Reports menu: - - text: Coverage report - href: coverage-report/ - - text: Unit test report - href: unit-test-report/ + - text: Coverage report + href: coverage-report/ + - text: Unit test report + href: unit-test-report/ github: icon: fa-github href: https://github.com/insightsengineering/teal @@ -36,7 +36,7 @@ articles: - teal-bs-themes reference: - - title: Teal Core Functions + - title: teal Core Functions desc: These are the main functions needed to build a teal app. contents: - init diff --git a/inst/WORDLIST b/inst/WORDLIST index b0b6fa1a0a..24b9e8af9d 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -15,3 +15,4 @@ themer theming uncheck cloneable +pharmaverse diff --git a/inst/readme_app.gif b/inst/readme_app.gif new file mode 100644 index 0000000000..5b64ad6374 Binary files /dev/null and b/inst/readme_app.gif differ diff --git a/man/module_teal.Rd b/man/module_teal.Rd index 008b24d698..a9a7f7f0ea 100644 --- a/man/module_teal.Rd +++ b/man/module_teal.Rd @@ -4,7 +4,7 @@ \alias{module_teal} \alias{ui_teal} \alias{srv_teal} -\title{Teal main app module} +\title{teal main app module} \usage{ ui_teal( id, diff --git a/vignettes/including-general-data-in-teal.Rmd b/vignettes/including-general-data-in-teal.Rmd index 25ef349157..1d0e2c5e0b 100644 --- a/vignettes/including-general-data-in-teal.Rmd +++ b/vignettes/including-general-data-in-teal.Rmd @@ -11,7 +11,7 @@ vignette: > ## Introduction -Teal applications are not restricted to `CDISC`-standard data. Although many teal modules included with `NEST` are designed for `CDISC` data, those in the library `teal.modules.general` have been designed to work with non-relational data. +`teal` applications are not restricted to `CDISC`-standard data. Although many teal modules included with `NEST` are designed for `CDISC` data, those in the library `teal.modules.general` have been designed to work with non-relational data. For example this application uses the standard `iris` and `mtcars` datasets: diff --git a/vignettes/teal-bs-themes.Rmd b/vignettes/teal-bs-themes.Rmd index 60c9a852f3..20a0269907 100644 --- a/vignettes/teal-bs-themes.Rmd +++ b/vignettes/teal-bs-themes.Rmd @@ -1,22 +1,22 @@ --- -title: "Teal and Bootstrap Themes" +title: "teal and Bootstrap Themes" author: "NEST CoreDev" date: "2022-09-08" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Teal and Bootstrap Themes} + %\VignetteIndexEntry{teal and Bootstrap Themes} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ## Introduction -We offer the easy application of a custom bootstrap theme to a `teal::init` app. -Teal is a consumer of the `bslib` R package which provides tools for customizing Bootstrap themes e.g. of Shiny apps. +We offer an easy application of a custom bootstrap theme to a `teal::init` app. +`teal` is a consumer of the `bslib` R package which provides tools for customizing Bootstrap themes e.g. of Shiny apps. ## Usage -Teal users have the benefit of custom bootstrap themes by specifying the `teal.bs_theme` R option, which has to be set to `bslib::bs_theme` object. +`teal` users have the benefit of custom bootstrap themes by specifying the `teal.bs_theme` R option, which has to be set to `bslib::bs_theme` object. The `bslib::bs_theme(...)` function creates a Bootstrap theme object, where you should specify the (major) Bootstrap version (default or one of 3, 4 or 5). Optionally you could choose a **`bootswatch` theme** and **customize the app CSS** with functions like `bslib::bs_add_rules`. Please read more about custom themes in [the `bslib` getting started vignette](https://rstudio.github.io/bslib/articles/bslib.html). @@ -39,7 +39,7 @@ options("teal.bs_theme" = bslib::bs_theme("Custom Options")) The best and recommended ways to **explore** the bootstrap themes are to use `bslib::run_with_themer(shinyApp(app$ui, app$server))` or `bslib::bs_theme_preview()`, both functions offer an interactive explore mode. Note that the interactive theming for Bootstrap 3 is not supported. -The `bslib::bs_theme_preview()` is recommended when the end user does not have any shiny app yet. +The `bslib::bs_theme_preview()` is recommended when the end user does not have any shiny app yet. When you already have a shiny app and you want to test different bootstrap themes (and `CSS` styling) then `bslib::run_with_themer(shinyApp(app$ui, app$server))` is recommended. Available bootstrap versions could be checked with `bslib::versions()` and bootstrap themes (`bootswatch`) with `bslib::bootswatch_themes(version = "5")`. @@ -103,7 +103,7 @@ remotes::install_github("https://github.com/dreamRs/shinyWidgets@main") ### Regular `shiny::fluidPage` -If you want to update the theme in the regular `shiny::fluidPage` like app, you do not need the `teal.bs_theme` option. Then simply provide the `bslib::bs_theme` directly to the `shiny::fluidPage(theme = bslib::bs_theme(...), ...)`. +If you want to update the theme in the regular `shiny::fluidPage` like app, you do not need the `teal.bs_theme` option. Then simply provide the `bslib::bs_theme` directly to the `shiny::fluidPage(theme = bslib::bs_theme(...), ...)`. ### Interactive theming guide diff --git a/vignettes/teal-options.Rmd b/vignettes/teal-options.Rmd index 4a835c76a2..284604d84a 100644 --- a/vignettes/teal-options.Rmd +++ b/vignettes/teal-options.Rmd @@ -1,10 +1,10 @@ --- -title: "Modifying a Teal application with R options" +title: "Modifying a teal application with R options" author: "Paweł Rucki" date: " 2021-12-23" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Modifying a Teal application with R options} + %\VignetteIndexEntry{Modifying a teal application with R options} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} editor_options: @@ -81,7 +81,7 @@ This option allows modifying labels and themes of all `ggplot2` plots in a `teal Default: `teal.widgets::ggplot2_args()`. ### `teal.plot_dpi` (integer value 24 or larger) -This option controls the dots per inch of the graphs rendered and downloaded when using `plot_with_settings`. +This option controls the dots per inch of the graphs rendered and downloaded when using `plot_with_settings`. Default: 72 diff --git a/vignettes/teal.Rmd b/vignettes/teal.Rmd index 983eb406ee..192c9dd9ee 100644 --- a/vignettes/teal.Rmd +++ b/vignettes/teal.Rmd @@ -1,10 +1,10 @@ --- -title: "Getting Started with Teal" +title: "Getting Started with teal" author: "NEST CoreDev" date: "2022-11-03" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Getting Started with Teal} + %\VignetteIndexEntry{Getting Started with teal} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -14,7 +14,7 @@ vignette: > *teal* is a shiny-based interactive exploration framework for analyzing data, with particular emphasis on `CDISC` clinical trial data. `teal` applications provide their users with: -* Ability to "pull" in data from external data sources +* Ability to "pull" in data from external data sources * Dynamic filtering of data to be used in the analyses * Ability to generate reproducible code to regenerate the on-screen analyses * Ability to create and download reports containing results of analyses (for analysis modules which support reporting) @@ -75,17 +75,17 @@ For modules which include reproducibility functionality, it often contains a "Sh ## Creating your own applications -`init` is the key function to use to create your `teal` application and it requires two key arguments: `data` and `modules`. +`init` is the key function to use to create your `teal` application and it requires two key arguments: `data` and `modules`. -### Application Data +### Application Data The `data` argument to the `init` function specifies the data used by your application. This can contain data currently in your R session, as in the example above, but also can contain `connectors` which describe where to "pull" data from when the application is run. This can be used to allow data to be pulled into `teal` applications from external sources which require your application users to enter credentials. In the example above we call `teal_data` to convert the raw datasets into `teal` specific datasets and to bind them in one `R` object. -This function can also be used to specify relationships between different datasets. -In order to use `CDISC` clinical trial data in a `teal` application the `cdisc_data` function is used instead. +This function can also be used to specify relationships between different datasets. +In order to use `CDISC` clinical trial data in a `teal` application the `cdisc_data` function is used instead. For further details we recommend exploring the [`teal.data`](https://insightsengineering.github.io/teal.data/) package documentation. @@ -110,11 +110,6 @@ so your users can view and configure their reports before downloading them. To learn more about the `teal` framework we recommend first exploring some of the available analysis modules. -## Known bugs - -- It could be needed to use `options(shiny.useragg = FALSE)` to make the `teal::init` apps more stable, [till `ragg` package is not fixed](https://github.com/rstudio/shiny/issues/3704). It is recommended to put this option in the `.Rprofile` file. - - For example see: * [general analysis modules](https://insightsengineering.github.io/teal.modules.general/)