shinymgr-01: Introduction

## Introduction

Shiny is an R package that makes it easy to build interactive web apps straight from R1. As Hadley Wickham, author of Mastering Shiny2, writes, “Today, Shiny is used in almost as many niches and industries as R itself is. It’s used in academia as a teaching tool for statistical concepts, a way to get undergrads excited about learning to write code, a splashy medium for showing off novel statistical methods or models. It’s used by big pharma companies to speed collaboration between scientists and analysts during drug development. It’s used by Silicon Valley tech companies to set up realtime metrics dashboards that incorporate advanced analytics.”

Shiny applications can range from simple to complex, each with an intended purpose developed for an intended user audience (Figure 1).

Figure 1. Left: A simple Shiny application that allows users to select two columns from the iris dataset (X Variable and Y Variable), along with the number of desired clusters (Cluster count); the app returns a scatterplot that identifies points by cluster. Source: https://shiny.posit.co/r/gallery/start-simple/kmeans-example/. Right: A complex Shiny application for statistics and machine learning called Radiant. Source: https://shiny.posit.co/r/gallery/education/radiant/

Shiny apps can be deployed on a server (such as https://www.shinyapps.io/), or they can be deployed in R directly, where a desktop machine serves as the local host. Many R packages today include a Shiny application that can be used to streamline analyses or illustrate a workflow.

Complex applications, such as the Radiant Shiny app shown in Figure 1, may have multiple tabs, inputs, and functionalities. Radiant allows users to work with datasets, design experiments, run many kinds of analyses, and produce reports in a variety of formats. However, from the developer perspective, complex applications can result in many lines of code, creating challenges for collaborating, debugging, streamlining, and maintaining the overall product.

Shiny modules are a solution to this problem. As stated by Winston Chang, “A Shiny module is a piece of a Shiny app. It can’t be directly run, as a Shiny app can. Instead, it is included as part of a larger app (or as part of a larger Shiny module – they are composable). Modules can represent input, output, or both. They can be as simple as a single output, or as complicated as a multi-tabbed interface festooned with controls/outputs driven by multiple reactive expressions and observers. Once created, a Shiny module can be easily reused – whether across different apps, or multiple times in a single app.” – source: https://shiny.posit.co/r/articles/improve/modules/.

Several authors have contributed R packages for distributing pre-written modules for general use, including the datamods3, shiny.reglog4, periscope5, shinyauthr6, modchart7, and jsmodule8 packages.

While shiny modules offer several benefits, challenges can arise in the development of apps that use modules, such as tracking available modules, testing them, storing them, and stitching them together into an app where outputs from one module can serve as inputs to the next. Taken together, these elements permit an expedient analysis pipeline or workflow that is fully reproducible9–11. Moreover, the pipeline should permit rapid reporting to convey the results of an analysis workflow to a target audience (Figure 2).

Figure 2. Idealized data science analysis pipeline identifies the purpose of a given analysis, the analytical steps, and the ability to produce outputs that can be rapidly disseminated in a reproducible framework.

## Introducing shinymgr

Here, we introduce shinymgr, an R package that provides a unifying framework for managing and deploying Shiny applications that consist of modules. From the user’s perspective, an “app” consists of a series of RShiny tabs that are presented in order, establishing an analysis workflow (Figure 3). The inputs and outputs of a given app can be saved as an .RDS file to ensure reproducibility. Further, the .RDS file may be loaded into an R Markdown (.Rmd) or Quarto (.qmd) template for rapid reporting.

Figure 3. The main panel shows the ‘iris_explorer’ app, which consists of three tabs that guide a user through a workflow. Tab 1 is displayed.

From the developer’s perspective, each tab in an “app” consists of one or more Shiny modules. Each tab is defined as focused, compartmentalized code that typically has a singular objective. Modules are the basic element in the shinymgr framework; they can be used and re-used across different tabs and different apps. The shinymgr app builder “stitches” shiny modules together so that outputs from one module serve as inputs to the next, creating an analysis pipeline that is easy to implement and maintain.

In short, developers use the shinymgr framework to write modules and seamlessly combine them into shiny apps, and users of these apps can execute reproducible analyses that can be incorporated into reports for rapid dissemination.

## shinymgr tutorials

We introduce shinymgr through a series of tutorials that come with the package. Below is a list of current tutorials, intended to be worked through in order:

    learnr::available_tutorials(
      package = "shinymgr") %>%
      dplyr::arrange(title) %>%
      dplyr::select(c('name', 'title'))

The name column provides the tutorial identifier (e.g, name = “modules” is tutorial #3). You are currently reading the “intro” tutorial. See below for each tutorial’s description!

    ##  [1] "intro: This is the first tutorial to complete. It introduces shinymgr and describes how to use learnr tutorials."
    ##  [2] "shiny: A brief introduction to shiny, an R package that makes it easy to build interactive web applications with R."
    ##  [3] "modules: A brief introduction to Shiny modules, which are stand-alone pieces of a shiny app."
    ##  [4] "app_modules: A brief introduction to how to connect modules in Shiny into an 'app'; i.e., how to let outputs from one shiny module serve as inputs to another to create an analytical workflow."
    ##  [5] "tests: How to test, document, and troubleshoot modules with the R package, testthat."
    ##  [6] "shinymgr: Describes how to setup a shinymgr framework on your machine."
    ##  [7] "database: An introduction to the shinymgr SQLite database, which tracks all modules, apps, and associated reports."
    ##  [8] "shinymgr_modules: Describes how to setup a shinymgr framework on your machine."
    ##  [9] "apps: How to build apps using shinymgr."
    ## [10] "analyses: A user's guide to running shinymgr analyses."
    ## [11] "reports: Rapid reporting with RMarkdown and Quarto."
    ## [12] "deployment: Deploying a shinymgr project for your purposes."

> 👉🏾 We highly recommend that you create a new RStudio project (folder) that is your home base for working through tutorials. Once there, open R and ensure this folder is your working directory. Our tutorial examples will use `getwd()` to reference your home base in many tutorials.

Launch a tutorial with the learnr `run_tutorial()` function, providing the name of the module to launch like this:

    learnr::run_tutorial(
      name = "modules",
      package = "shinymgr"
    )

The tutorial should launch in a browser, which has the benefit of being able to print the tutorial to PDF upon completion.

> 👉🏼 If you have a large monitor, or even 2 monitors, you may find it very useful to run the tutorials as described, but to also launch a second instance of R that is not running a tutorial. This will allow you to try out some code outside the tutorial environment. To do so, select Session | New Session from the main toolbar in RStudio.

## How to use learnr tutorials

All tutorials were written with the R package, learnr. You’re looking at the introductory tutorial. Each tutorial is divided into topics, which can be seen in the left menu. As you work though the topics, your progression is saved. This means you can close out when needed and pick up where you left off at a later time. The very small “Start Over” button at the bottom of the left menu will sweep clean any progress so you can start afresh if needed.

Tutorials consist of written content (like you’re reading now) and R examples, but may also include short videos, interactive R coding and demos, and quizzes.

## Tutorial formatting

Tutorials are designed to be informative and engaging. If we want to highlight a key concept, we will place in a large yellow box, like this:

> 👉🏽 Hey! This is important!

If we want to show you how to do something in R, you should see a green colored “code chunk” that illustrates something, like this:

    # add 1 + 1
    1 + 1

    ## [1] 2

The inputs into R are shaded green, and typically include a short comment that starts with a hashtag (e.g., # add 1 + 1). Comments are not executed by R; they are notes to the programmer (you!). The outputs are identified by the double hashtag symbol enclosed in a gray or white box as shown above.

If you have a second instance of RStudio open and would like to follow along, you could copy this code and paste it into your R console and execute it in that second instance.

> 👉🏿 When a learnr tutorial is active, your R console cannot be accessed because it is “busy” with the tutorial. Instead of coding in the R console, coding is done directly in the tutorial, as you’ll see in a few seconds. This is why running a second instance of R may be useful – it will not be locked into the tutorial.

Tutorials are designed to give you hands-on practice. Exercises are identified with instructions provided in a steel blue box, like this:

Enter the equation 1 + 1 in the box below, and execute it by pressing the “Run Code” button.

    1 + 1

Hints may or may not be included, so make sure to look for them! Press the “Hint” button to see the hint.

Quizzes may include short answers or multiple choice questions, like this one provided by the authors of the learnr package:

Quiz

Your answers are saved in the tutorial itself (unless you press Start Over button in the left menu, which will erase any previous work).

Tutorials may include Shiny elements, like the one below showing the waiting time between eruptions for the Old Faithful geyser in Yellowstone National Park, Wyoming, USA. In this case, R receives “user-inputs” from a slider and produces a histogram output of waiting times. Because shinymgr is an R package that helps organize, test, and combine Shiny modules into a larger application, many of the tutorials will include R Shiny.

Use the slider to change the number of grouping “bins” in the histogram below:

Number of bins:

## Tutorial summary

We’ve briefly introduced the package, shinymgr, and provided an overview of how learnr tutorials work.

> 👉🏼 If you’d like a pdf of this document, use the browser “print” function (right-click, print) to print to pdf. If you want to include quiz questions and R exercises, make sure to provide answers to them before printing.

## References

1. Chang, W., Cheng, J., Allaire, J., Sievert, C., Schloerke, B., Xie, Y., Allen, J., McPherson, J., Dipert, A., & Borges, B. (2021). Shiny: Web application framework for r. https://CRAN.R-project.org/package=shiny
2. Wickham, H. (2020). Mastering shiny. O’Reilly Media.
3. Perrier, V., Meyer, F., & Abeer, Z. S. (2022). Datamods: Modules to import and manipulate data in ’shiny’. https://CRAN.R-project.org/package=datamods
4. Kosinski, M. (2022). Shiny.reglog: Optional login and registration module system for ShinyApps. https://CRAN.R-project.org/package=shiny.reglog
5. Brett, C., & Neuhaus, I. (2022). Periscope: Enterprise streamlined ’shiny’ application framework. https://CRAN.R-project.org/package=periscope
6. Campbell, P. (2021). Shinyauthr: ’Shiny’ authentication modules. https://CRAN.R-project.org/package=shinyauthr
7. Balehosur, Y. (2021). Modchart: A ’shiny’ module for creating charts of various types. https://CRAN.R-project.org/package=modchart
8. Kim, J., & Lee, H. (2022). Jsmodule: ’RStudio’ addins and ’shiny’ modules for medical research. https://CRAN.R-project.org/package=jsmodule
9. Peng, R. D. (2011). Reproducible research in computational science. Science, 334(6060), 1226–1227. https://doi.org/10.1126/science.1213847
10. Gentleman, R., & Lang, D. T. (2007). Statistical analyses and reproducible research. Journal of Computational and Graphical Statistics, 16(1), 1–23. https://doi.org/10.1198/106186007X178663
11. Alston, J. M., & Rick, J. A. (2021). A beginner’s guide to conducting reproducible research. The Bulletin of the Ecological Society of America, 102(2), e01801. https://doi.org/https://doi.org/10.1002/bes2.1801

## What’s next

You’re finished! If you are new to shiny, the next tutorial provides an overview of Shiny, where you will build a simple shiny app featuring the iris dataset.

    learnr::run_tutorial(
      name = "shiny",
      package = "shinymgr"
    )

If you are experienced with shiny, modules, and testing, you can safely jump to the “shinymgr” tutorial (tutorial #6). See you there!

    learnr::available_tutorials(package = "shinymgr")

## shinymgr-01: Introduction