Shiny alternatives ~ Words of wisdom ~ More resources
-
-
+
+
See the source code
+
+
+
You can reference the source code of all the apps we’ll be building/playing with throughout this workshop on GitHub.
-
-
- Part 1: High-level overview of Shiny
-
-
-
- What is Shiny?
+
Part 1: High-level overview of Shiny
+
+
+ What is Shiny?
-
- Anatomy of a shiny app
+
+ Anatomy of a shiny app
-
- Where to find examples
+
+ Where to find examples
- What is Shiny?
+ What is Shiny?
Think interactive web pages built by people who love to code in R (i.e. hopefully many of you!), no JavaScript experience necessary.
-
-Shiny makes building web apps easy
-
+
Shiny makes building web apps easy
+
“Shiny is an R package that makes it easy to build interactive web apps straight from R. You can host standalone apps on a webpage or embed them in R Markdown documents or build dashboards. You can also extend your Shiny apps with CSS themes, htmlwidgets, and JavaScript actions.”- RStudio
- The anatomy of a Shiny app
+ The anatomy of a Shiny app
What does a Shiny app look like under the hood?
-
-The basic anatomy of a Shiny app
-
+
The basic anatomy of a Shiny app
+
Shiny apps are composed in two parts: (1) a web page that displays the app to a user (i.e. the user interface, or UI for short), and (2) a computer that powers the app (i.e. the server)
-
-
-
-
+
+
The UI controls the layout and appearance of your app and is written in HTML (except we use functions from the shiny package to write that HTML). The server handles the logic of the app – in other words, it is a set of instructions that tells the webpage what to display when a user interacts with it.
-
-Widgets are web elements that users can interact with via the UI
-
+
Widgets are web elements that users can interact with via the UI
+
-
-
-
+
+
+
+
+
+
+
+
-
- Widgets collect information from the user which is then used to update outputs created in the server.
+ Widgets collect information from the user which is then used to update outputs created in the server.
- Shiny comes with a set of of standard widgets (see left), but you can also explore widget extensions using a variety of other packages (e.g. {shinyWidgets}, {DT}, {plotly})
+ Shiny comes with a set of of standard widgets (see left), but you can also explore widget extensions using a variety of other packages (e.g. {shinyWidgets}, {DT}, {plotly})
-
-Reactivity: a brief intro
-
+
Reactivity: a brief intro
+
Reactivity is what makes Shiny apps responsive i.e. it lets the app instantly update itself whenever the user makes a change. At a very basic level, it looks something like this:
- Can I see an example please?
+ Can I see an example please?
I’m glad you asked! There are lots of great examples online, including those developed by Bren alumni, as well as built-in teaching examples.
-
-Example shiny apps built by some familiar folks
-
+
Example shiny apps built by some familiar folks
+
-HydroTech Helper (video tutorial), by MEDS 2022 alumn, Daniel Kerstan, developed during his time as a USGS Hydrologic Technician – access real-time monitoring of USGS hydrology sites and equipment
+HydroTech Helper (video tutorial), by MEDS 2022 alumn, Daniel Kerstan, developed during his time as a USGS Hydrologic Technician – access real-time monitoring of USGS hydrology sites and equipment
-The Shiny packages comes with 11 built-in examples
-
-
- Check out the available Shiny app examples by running this code in your console:
+
The Shiny packages comes with 11 built-in examples
+
+
+ Check out the available Shiny app examples by running this code in your console:
library(shiny)runExample(example =NA)
-
- Run the first example, which plots R’s built-in faithful data set with a configurable number of bins:
+
+ Run the first example, which plots R’s built-in faithful data set with a configurable number of bins:
runExample("01_hello")
-
+
Change the number of bins using the sliderInput widget and watch the histogram re-render.
-
- These working examples also come paired with source code for you to see how the app is built. For example, the sliderInput is built with the following code:
+
+ These working examples also come paired with source code for you to see how the app is built. For example, the sliderInput is built with the following code:
# Input: Slider for the number of bins ----
@@ -678,7 +660,7 @@
-
+
Now let’s build our own!
@@ -686,7 +668,7 @@
-
@@ -694,52 +676,42 @@
-
-Create your GitHub repo
-
+
Create your GitHub repo
+
Let’s start by creating a GitHub repo to house our soon-to-be app(s), then we’ll clone our repo to our computer. I’m using RStudio to clone my repo in the example below, but you can also do this via the command line using git clone <repo-url>.
-
-
-
-
-
-Shiny app repo structure
-
-
+
+
+
Shiny app repo structure
+
+
Not much is required to make a functional app (which is awesome) – for a basic app, you really just need an app.R file where you’ll write the code for your UI and server. To stay organized, we’ll place app.R into a subdirectory (e.g. /myapp), which will also house any dependencies (e.g. other scripts/files/etc.) used by app.R.
-
-
-
-
-
-All Shiny apps begin (in almost) the same way
-
+
+
+
All Shiny apps begin (in almost) the same way
+
You have the option of creating either a single-file app or two-file app, and they look nearly the same (we’ll see both formats in the coming slides).
-
-
-
-
+
+
Why two options? Before v0.10.2, Shiny apps needed to be split into two separate files, ui.R and server.R, that defined the UI and server components, respectively. With v0.10.2+, users can create a single-file app, app.R, which contains both the UI and server components together. While it largely comes down to personal preference, a single-file format is best for smaller apps or when creating a reprex, while the two-file format is beneficial when writing large, complex apps where breaking apart code can make things a bit more navigable/maintainable.
-
-Create a single-file Shiny app
-
+
Create a single-file Shiny app
+
You can create a single-file app using RStudio’s built-in Shiny app template (e.g. File > New Project… > New Directory > Shiny Application), but it’s just as easy to create it from scratch (and you’ll memorize the structure faster!). Let’s do that now.
-
+
1. In your project repo, create a subdirectory to house your app – I’m calling mine, single-file-app.
-
+
2. Create a new R script inside /single-file-app and name it app.R – you must name your script app.R. Copy/type the following code into app.R, or use the shinyappsnippet to automatically generate a shiny app template.
@@ -757,195 +729,191 @@
# combine UI & server into an app ----shinyApp(ui = ui, server = server)
-
+
Tip: Use code sections (denoted by # some text ----) to make navigating different sections of your app code a bit easier. Code sections will appear in your document outline (find the button at the top right corner of the script/editor panel).
-
-Run your app
-
-
+
Run your app
+
+
Once you have saved your app.R file, the “Run” code button should turn into a “Run App” button that looks like: . Click that button to run your app (alternatively, run runApp("directory-name") in your console – for me, that looks like, runApp("single-file-app"))!
-
+
You won’t see much yet, as we have only built a blank app (but a functioning app, nonetheless!). In your RStudio console, you should see something like: Listening on http://127.0.0.1:XXXX, which is the URL where your app can be found. 127.0.0.1 is a standard address that means “this computer,” and the last four digits represent a randomly assigned port number. You can click the “Open in Browser” button, , to see how your app will appear when viewed in your web browser.
-
+
You should also notice a red stop sign, , appear in the top right corner of your console indicating that R is busy–this is because your R session is currently acting as your Shiny app server and listening for any user interaction with your app. Because of this, you won’t be able to run any commands in the console until you quit your app. Do so by pressing the stop button.
-
-
-
+
+
+
+
+
+
+
+
-
-
-
+
+
+
+
+
+
-
-
-Create a two-file Shiny app
+
+
+
Create a two-file Shiny app
+
In practice, you will likely find yourself opting for the the two-file format – code expands quickly, even when building relatively small apps. This two-file approach (well, three if you use a global.R file, which is encouraged) will help to keep your code a bit more manageable.
-
+
1. In your project repo, create a new subdirectory to house your app – I’m calling mine, two-file-app.
-
+
2. Create two new R scripts inside /two-file-app named ui.R and server.R – you must name your scripts ui.R and server.R. Copy the following code into the respective files. Note: When splitting your UI and server into separate files, you do not need to include the shinyApp(ui = ui, server = server) line of code (as required in your single-file app).
-
-ui.R
-
+
+
+
+
ur.R
+
# user interface ----ui <-fluidPage()
+
-
-server.R
-
+
+
+
+
server.R
+
# server instructions ----server <-function(input, output) {}
+
-
+
3. Lastly, let’s create a global.R file within /two-file-app and add dependencies (right now, that’s just loading the shiny package). Run your app as we did earlier.
By the end of building out this first app, you should be a bit more familiar with:
-
- writing a single-file (app.R) shiny app
+
+ writing a single-file (app.R) shiny app
-
- adding and styling text in the UI using tags
+
+ adding and styling text in the UI using tags
-
- practicing data wrangling and visualization outside of your shiny app
+
+ practicing data wrangling and visualization outside of your shiny app
-
- following a general workflow for building reactive apps, which includes adding inputs and outputs to the UI, then writing the server instructions on how to assemble user input values into outputs
+
+ following a general workflow for building reactive apps, which includes adding inputs and outputs to the UI, then writing the server instructions on how to assemble user input values into outputs
-
- running and quitting apps in RStudio
+
+ running and quitting apps in RStudio
-
+
Packages introduced:
-
-shiny: framework for building our reactive app + standard widgets
+
+shiny: framework for building our reactive app + standard widgets
-
-DT: interactive datatable widgets (that can be made reactive using shiny!)
+
+DT: interactive datatable widgets (that can be made reactive using shiny!)
-
-tidyverse: collection of packages for wrangling & visualizing data
+
+tidyverse: collection of packages for wrangling & visualizing data
We’ll start by building a small single-file app using data from the palmerpenguins package. We’ll build out the the following features:
@@ -964,19 +932,27 @@
-
-
-
+
+
+
+
+
+
-
-
-Add text in the UI
-
+
+
+
Add text in the UI
+
+
We’ll do this in the UI within fluidPage(), a layout function that sets up the basic visual structure of the page and scales components in real time to fill all available browser width. Add a title and subtitle to your app (be sure to separate each with a comma, ,), save, and run:
+
+
+
~/one-file-app/app.R
+
# user interface ----ui <-fluidPage(
@@ -988,11 +964,16 @@
)
+
-
+
Recall that the UI is actually just an HTML document. We can style our text by adding static HTML elements using tags – a list of functions that parallel common HTML tags (e.g. <h1> == tags$h1()) The most common tags also have wrapper functions (e.g. h1()).
+
+
+
~/one-file-app/app.R
+
# user interface ----ui <-fluidPage(
@@ -1005,17 +986,17 @@
)
-
-
-What are inputs and outputs?
-
+
+
What are inputs and outputs?
+
+
Next, we will begin to add some inputs and outputs to our UI inside fluidPage() (anything that you put into fluidPage() will appear in our app’s user interface…and we want inputs and outputs to show up there!).
-
+
Inputs (or widgets) are the things that users can interact with (e.g. toggle, slide) and provide values to your app. The input functions below correspond to the widgets you see on slide #9. Outputs are the R objects that your user sees (e.g. tables, plots) and are what respond when a user interacts with/changes an input value.
-
+
The shiny package comes with a number of input and output functions, but you can extend these with additional packages (e.g. shinyWidgets, plotly, DT, etc.; more on those later).
Next, we’ll create a scatterplot of penguin bill lengths vs. penguin flipper lengths using the penguins data set from the {palmerpengiuns} package. We will make this scatterplot reactive by adding a sliderInput that allows users to filter the displayed data points by selecting a range of penguin body masses (e.g. only plot bill and flipper lengths for penguins with body masses ranging from 4,500 grams to 6,000 grams).
-
+
To create a reactive plot, we will follow these steps:
-
+
1. Add an input (e.g. sliderInput) to the UI that users can interact with
-
+
2. Add an output (e.g. plotOutput) to the UI that creates a placeholder space to fill with our eventual reactive output
-
+
3. Tell the server how to assemble inputs into outputs
-
-
-
+
+
+
+
+
+
-
-
-Input function syntax
-
-All input functions have the same first argument, inputId (NOTE:IdnotID), which is used to connect the front end of your app (the UI) with the back end (the server). For example, if your UI has an inputId = "name", the server function will access that input value using the syntax input$name. The inputId has two constraints: (1) it must be a simple string containing only letters, numbers, and underscores, (2) it must be unique within your app.
+
+
+
Input function syntax
+
+
+All input functions have the same first argument, inputId (NOTE:IdnotID), which is used to connect the front end of your app (the UI) with the back end (the server). For example, if your UI has an inputId = "name", the server function will access that input value using the syntax input$name. The inputId has two constraints: (1) it must be a simple string containing only letters, numbers, and underscores, (2) it must be unique within your app.
-
- Most input functions have a second parameter called label, which is used to create a human-readable label for the control, which will appear in the UI.
+
+ Most input functions have a second parameter called label, which is used to create a human-readable label for the control, which will appear in the UI.
-
- The remaining arguments are unique to each input function. Oftentimes, these include a value parameter, which lets you set the default value of your widget, where applicable.
+
+ The remaining arguments are unique to each input function. Oftentimes, these include a value parameter, which lets you set the default value of your widget, where applicable.
A couple examples:
@@ -1148,17 +1113,20 @@
selectInput(inputId ="island_input", label ="Choose and island:", ...)
-
+
Check out the interactive Shiny Widgets Gallery to learn how to implement the most common widgets.
-
-Step 1: Add an input to your app
-
+
Step 1: Add an input to your app
+
First let’s add a sliderInput() that will allow users to select a range of penguin body masses (g).
+
+
+
~/one-file-app/app.R
+
# user interface ----ui <-fluidPage(
@@ -1169,18 +1137,23 @@
min =2700, max =6300, value =c(3000, 4000)) )
+
When you run your app, you should see something similar to the image below. It’s operable, but does not yet have an associated output.
-
-
-
+
+
+
+
+
+
+
-
-
-Output function syntax
+
+
Output function syntax
+
Outputs in the UI create placeholders which are later filled by the server function.
Let’s now add a plotOutput(), which will be updated based on the user inputs via the sliderInput(), then run the app.
+
+
+
~/one-file-app/app.R
+
# user interface ----ui <-fluidPage(
@@ -1218,33 +1194,36 @@
)
+
-
+
Okay, it looks like nothing changed?? Remember, *Output() functions create placeholders, but we have not yet written the server instructions on how to fill and update those placeholders. We can inspect the HTML and see that there is, in fact, a placeholder area awaiting our eventual output, which will be a plot named “bodyMass_scatterPlot”:
-
-
-
+
+
+
+
+
-
-
-Rendering outputs
+
+
+
+
Rendering outputs
+
Each *Output() function in the UI is coupled with a render*() function in the server, which contains the “instructions” for creating the output based on user inputs (or in other words, the instructions for making your output reactive).
-
-
-Examples of *Output() functions and their corresponding render*() functions:
+
+Examples of *Output() functions and their corresponding render*() functions:
-
Output function
@@ -1273,19 +1252,18 @@
-
-Step 3: Tell the server how to assemble inputs into outputs
-
-
+
Step 3: Tell the server how to assemble inputs into outputs
+
+
Now that we’ve designed our input/output in the UI, we need to write the server instructions (i.e. write the server function) on how to use the input value(s) (i.e. penguin body mass range via a slider input) to update the output (scatter plot).
-
+
The server function is defined with two arguments, input and output, both of which are list-like objects. You must define both of these arguments within the server function. input contains the values of all the different inputs at any given time, while output is where you’ll save output objects to display in the app.
-
+
This part can be intimidating, but if you follow these three rules, you will successfully create reactivity within your shiny app!
-
+
Rules:
@@ -1300,12 +1278,15 @@
-
-Rule 1: Save objects you want to display to output$<id>
-
+
Rule 1: Save objects you want to display to output$<id>
In our UI, we created a placeholder for our plot using the plotOutput() function and gave it the Id "bodyMass_scatterplot". In our server, we will save our plot to the output argument by its outputId.
-
+
Note: In the UI, our outputId is quoted ("bodyMass_scatterPlot"), but not in the server (bodyMass_scatterPlot).
-
-Rule 2: Build reactive objects with render*()
-
-
-Use the appropriate render*() function to make your output reactive (e.g. if you have a plotOutput in your UI, you will need to use renderPlot() in your server).
-
-
-Within your render*(), write any code inside a set of curly braces, {}. This allows you to include as many lines of code as it takes to build your object.
+
Rule 2: Build reactive objects with render*()
+
+
+Use the appropriate render*() function to make your output reactive (e.g. if you have a plotOutput in your UI, you will need to use renderPlot() in your server). Within your render*(), write any code inside a set of curly braces, {}. This allows you to include as many lines of code as it takes to build your object.
-An Aside: Draft objects (e.g. plots) in a separate script first
+
+
An Aside: Draft objects (e.g. plots) in a separate script first
+
I find it easier to experiment and draft my objects (e.g. plots) first in a separate script, then copy the code over to the server after. I want to make a plot that looks like this:
-Tip: Save your practice script in a separate directory (i.e. not inside your app directory) – I typically save mine to something like ~/scratch/practice_script.R.
+
+
+Tip: Save your practice script in a separate directory (i.e. not inside your app directory) – I typically save mine to something like ~/scratch/practice-script.R.
-
-Copy your plot code into the server
-
-
+
Copy your plot code into the server
+
+
Copy your code over to your app, placing it inside the {} (and make sure to add any additional required packages to the top of your app.R script). Run your app. What do you notice?
-A non-reactive plot now lives in our plotOutput() placeholder
+
+
A non-reactive plot now lives in our plotOutput() placeholder
+
We have a plot (yay!), but it isn’t reactive. We have not yet told the server how to update the plot based on user inputs via the sliderInput() in the UI. Let’s do that next…
-
-
-
-
-
-Practice filtering data in our separate script
-
-
+
+
+
Practice filtering data in our separate script
+
+
First, create a new data frame where we filter the body_mass_g column for observations within a specific range of values (in this example, values ranging from 3000 - 4000):
Recall that in our UI, we gave our sliderInput() an inputId = "body_mass_input".
+
+
+
~/one-file-app/app.R
+
# load packages (omitted for brevity) ----# user interface ----
@@ -1591,17 +1615,21 @@
}
-
-
-Rule 3: Access input values with input$<id>
-
+
+
Rule 3: Access input values with input$<id>
+
+
In our server, we can access the values of that slider input using the syntax, input$body_mass_input. If you want your output to change according to the input values, substitute hard-coded values (e.g. 3725:5191) with the input values from the UI (e.g. input$body_mass_input[1]:input$body_mass_input[2]).
-
+
Importantly, we need to use reactive() to create reactive data frames that update with user inputs. When you call your reactive data frame in your ggplot, the data frame name must be followed by ().
+
+
+
~/one-file-app/app.R
+
# load packages (omitted for brevity) ----# user interface ----
@@ -1634,20 +1662,17 @@
}
-
-
-Okay, RUN THAT APP!
+
+
Okay, RUN THAT APP!
+
You should now have a reactive Shiny app! Note that reactivity automatically occurs whenever you use an input value to render an output object.
-
-
-
-
-
-Recap: We created our first reactive Shiny app following these steps:
-
+
+
+
Recap: We created our first reactive Shiny app following these steps:
+
1. We created an app.R file in it’s own directory and began our app with the template, though you can also create a two-file Shiny app by using separate ui.R and server.R files.
@@ -1667,125 +1692,124 @@
4. We wrote the server instructions for how to assemble inputs into outputs, following these rules:
-
- save objects that you want to display to output$<id>
+
+ save objects that you want to display to output$<id>
-
- build reactive objects using a render*() function (and similarly, build reactive data frames using reactive()
+
+ build reactive objects using a render*() function (and similarly, build reactive data frames using reactive()
-
- access input values with input$<id>
+
+ access input values with input$<id>
-
+
And we saw that reactivity automatically occurs whenever we use an input value to render an output object.
-
- Exercise 1: Add another reactive widget
-
-
+
Exercise 1: Add another reactive widget
+
+
The {DT} package provides an R interface to the JavaScript library DataTables (you may have already used the DT package in your knitted RMarkdown/Quarto HTML documents). DT datatables allow for filtering, pagination, sorting, and lots of other neat features for tables on your HTML pages.
-
+
Working alone or in groups, add a reactive DT datatable to your app with a checkboxGroupInput that allows users to select which year(s) to include in the table. Configure your checkboxGroupInput so that the years 2007 and 2008 are pre-selected.
-
+
In the end, your app should look something like the example to the right.
-
-
-
+
+
+
+
+
+
+
+
-
+
See next slide for some tips on getting started!
-
- Exercise 1: Tips
-
-
+
Exercise 1: Tips
+
+
Tips:
-
- Use ?checkboxGroupInput to learn more about which arguments you need (remember, all inputs require an inputId and oftentimes a label, but there are others required to make this work as well)
+
+ Use ?checkboxGroupInput to learn more about which arguments you need (remember, all inputs require an inputId and oftentimes a label, but there are others required to make this work as well)
-
- Both shiny and DT packages have functions named dataTableOutput() and renderDataTable() – DT::renderDataTable() allows you to create both server-side and client-side DataTables and supports additional DataTables features while shiny::renderDataTable() only provides server-side DataTables. Be sure to use the one from the DT package using the syntax packageName::functionName().
+
+ Both shiny and DT packages have functions named dataTableOutput() and renderDataTable() – DT::renderDataTable() allows you to create both server-side and client-side DataTables and supports additional DataTables features while shiny::renderDataTable() only provides server-side DataTables. Be sure to use the one from the DT package using the syntax packageName::functionName().
-
- There are lots of ways to customize DT tables, but to create a basic one, all you need is to DT::dataTable(your_dataframe)
+
+ There are lots of ways to customize DT tables, but to create a basic one, all you need is DT::dataTable(your_dataframe)
-
+
And remember to follow the steps outlined on the previous slides (jump back to slide 27):
-
+
1. Add an input (e.g. checkboxGroupInput) to the UI that users can interact with
-
+
2. Add an output (e.g. DT::datatableOutput) to the UI that creates a placeholder space to fill with our eventual reactive output
-
+
3. Tell the server how to assemble inputs into outputs following 3 rules:
-
+
3.1 Save objects you want to display to output$<id>
-
+
3.2 Build reactive objects using a render*() function
-
+
3.3 Access input values with input$<id>
-
+
See next slide for a solution!
-
- Exercise 1: A solution
-
-
+
Exercise 1: A solution
+
+
Press the right arrow key to advance through the newly added lines of code.
+
+
+
~/one-file-app/app.R
+
# load packages ----library(shiny)library(palmerpenguins)
@@ -1865,49 +1889,49 @@
# combine UI & server into an app ----shinyApp(ui = ui, server = server)
-
-
-Common mistakes to look out for
+
+
Common mistakes to look out for
+
It’s inevitable that you’ll make mistakes here and there as you build out your app…and they can be frustrating to catch. A few that I find myself making over and over again are:
-
- misspelling inputId as inputID (or outputId as outputID)
+
+ misspelling inputId as inputID (or outputId as outputID)
-
- misspelling your inputId (or outputId) name in the server (e.g. UI: inputId = "myInputID", server: input$my_Input_ID)
+
+ misspelling your inputId (or outputId) name in the server (e.g. UI: inputId = "myInputID", server: input$my_Input_ID)
-
- repeating inputIds (each must be unique)
+
+ repeating inputIds (each must be unique)
-
- forgetting to separate UI elements with a comma, ,
+
+ forgetting to separate UI elements with a comma, ,
-
- forgetting the set of parentheses when calling the name of a reactive data frame in a plot (e.g. ggplot(my_reactive_df(), aes(...)))
+
+ forgetting the set of parentheses when calling the name of a reactive data frame in a plot (e.g. ggplot(my_reactive_df(), aes(...)))
-
-
-
+
+
+
+
+
+
+
+
+
- Break
+ Break
Give your eyes a break from the computer screen!
@@ -1915,7 +1939,7 @@
-
+
@@ -1926,90 +1950,78 @@
- Building out your 2nd app
+ Building out your 2nd app
Up until now, we’ve been adding our text and widgets in a pretty unstructured way – elements are stacked on top of one another within a single column. Next, we’ll learn how to customize the layout of our app to make it a bit more visually pleasing.
-
- Learning Objectives - App #2v1 (two-file app)
-
-
+
Learning Objectives - App #2v1 (two-file app)
+
+
By the end of building out this second app, you should:
-
- be comfortable creating a shiny app using the two-file (ui.R & server.R) format along with a global.R file
+
+ be comfortable creating a shiny app using the two-file (ui.R & server.R) format along with a global.R file
-
- understand how to use layout functions to customize the visual structure of your app’s UI
+
+ understand how to use layout functions to customize the visual structure of your app’s UI
-
- have more practice building reactive outputs – and placing them within the layout structure of your app
+
+ have more practice building reactive outputs – and placing them within the layout structure of your app
-
- be able to create multiple inputs that control a given output
+
+ be able to create multiple inputs that control a given output
-
- know how to import larger bodies of text using includeMarkdown() (rather than writing & styling text within your UI)
+
+ know how to import larger bodies of text using includeMarkdown() (rather than writing & styling text within your UI)
-
- successfully publish an app using shinyapps.io
+
We’ll be building out our two-file app using data from the lterdatasampler and palmerpenguins packages. We’ll focus on creating a functional app that has a more visually pleasing UI layout (and we’ll refine it’s appearance even further in v2). By the end of v1, we’ll have created:
-
+
(a) A navigation bar with two pages, one of which will contain two tabs (one tab for each plot)
-
+
(b) A pickerInputandcheckboxGroupButtons for users to filter cutthroat trout data in a reactive scatterplot
-
+
(c) A pickerInput for users to filter penguin data and a sliderInput to adjust the number of bins in a reactive histogram
@@ -2021,14 +2033,13 @@
-
+
You’ll notice that there are some UI quirks (most notably, blank plots that appear when no data is selected) that can make the user experience less than ideal (and even confusing) – we’ll learn about ways to improve this in v2 of our app.
-
-Two files? Try two panes!
-
+
Two files? Try two panes!
+
We’ll be building out a two-file shiny app this time around. You can open multiple scripts up side-by-side by navigating to Tools > Global Options > Pane Layout > Add Column
@@ -2039,10 +2050,9 @@
This setup is certainly not required/necessary – organize your IDE however you work best!
-
-Practice data wrangling, filtering & viz first!
-
-
+
Practice data wrangling, filtering & viz first!
+
+
Here’s what I’ve done in my ~scratch/practice_script_app2_lter.R file:
We’ll use the and_vertebrates data set from lterdatasampler to create a scatter plot of trout weights by lengths. When we move to shiny, we’ll build 2 inputs for filtering our data: one to select channel_type and one to select section.
We’ll use the penguins data set from palmerpenguins to create a histogram of penguin flipper lengths. When we move to shiny, we’ll build 2 inputs for filtering our data: one to select island and one to change the number of histogram bins.
@@ -2155,36 +2175,29 @@
-
-A global.R file can help you keep code organized
-
+
A global.R file can help you keep code organized
+
While not a requirement of a shiny app, a global.R file will help reduce redundant code, increase your app’s speed, and help keep code more clearly organized. It works by running once when your app is first launched, making any logic, objects, etc. contained in it available to both the ui.R and server.R files (or, in the case of a single-file shiny app, the app.R file). It’s a great place for things like:
-
- loading packages
+
+ loading packages
-
- importing data
+
+ importing data
-
- sourcing scripts (particularly functions – we’ll talk more about functions later)
+
+ sourcing scripts (particularly functions – we’ll talk more about functions later)
-
- data wrangling (though you’ll want to do any major data cleaning before bringing your data into your app)
+
+ data wrangling (though you’ll want to do any major data cleaning before bringing your data into your app)
-
- building custom ggplot themes
+
+ building custom ggplot themes
-
- etc.
+
+ etc.
@@ -2194,22 +2207,18 @@
-
-We created a perfectly functional first app, but it’s not so visually pleasing
-
+
We created a perfectly functional first app, but it’s not so visually pleasing
+
-
- nothing really grabs your eye
+
+ nothing really grabs your eye
-
- inputs & outputs are stacked vertically on top of one another (which requires a lot of vertical scrolling)
+
+ inputs & outputs are stacked vertically on top of one another (which requires a lot of vertical scrolling)
-
- widget label text is difficult to distinguish from other text
+
+ widget label text is difficult to distinguish from other text
@@ -2224,13 +2233,12 @@
Before we jump into adding reactive outputs to our next app, we’ll first plan out the visual structure of our UI – first on paper, then with layout functions.
-
-Layout functions provide the high-level visual structure of your app
-
-
+
Layout functions provide the high-level visual structure of your app
+
+
Layouts are created using a hierarchy of function calls (typically) insidefluidPage(). Layouts often require a series functions – container functions establish the larger area within which other layout elements are placed. See a few minimal examples of layout functions on the following slides (though more exist!).
-
+
Some useful layout function pairings:
@@ -2254,10 +2262,9 @@
)
-
-Example UI layouts
-
-
+
Example UI layouts
+
+
Note: You can combine multiple layout function groups to really customize your UI – for example, you can create a navbar, include tabs, and also establish sidebar and main panel areas for inputs and outputs.
First, let’s build a UI that has a navigation bar with two tabs – one for background information and one to contain our data visualizations. To do this, we’ll use navbarPage() instead of fluidPage() to create our webpage.
-
+
Tip: It can be super helpful add code comments at the start and end of each UI element – for example, see # data viz tabPanel--- and # END data viz tabPanel, below. Adding text that you will eventually replace with content (e.g. plots, tables, images, longer text) may help to visualize what you’re working towards as well.
+
+
+
ui.R
+
ui <-navbarPage(title ="LTER Animal Data Explorer",
@@ -2429,14 +2437,18 @@
) # END navbarPage
-
-
-Add two tabs to the “Explore the Data” page
-
+
+
Add two tabs to the “Explore the Data” page
+
+
Give your tabs the following titles: Trout and Penguins.
+
+
+
ui.R
+
ui <-navbarPage(title ="LTER Animal Data Explorer",
@@ -2474,14 +2486,18 @@
) # END navbarPage
-
-
-Add sidebar & main panels to the Trout tab
-
+
+
Add sidebar & main panels to the Trout tab
+
+
We’ll eventually place our input in the sidebar and output in the main panel.
+
+
+
ui.R
+
ui <-navbarPage(title ="LTER Animal Data Explorer",
@@ -2536,11 +2552,10 @@
) # END navbarPage
-
-
- Exercise 2: Add sidebar and main panels to the Penguins tab
+
+
Exercise 2: Add sidebar and main panels to the Penguins tab
+
@@ -2556,16 +2571,17 @@
-
+
See next slide for a solution!
-
- Exercise 2: A solution
-
+
Exercise 2: A solution
+
+
+
ui.R
+
ui <-navbarPage(title ="LTER Animal Data Explorer",
@@ -2637,83 +2653,80 @@
) # END navbarPage
-
-
-Some important things to remember when building your UI’s layout:
+
+
Some important things to remember when building your UI’s layout:
+
- try creating a rough sketch of your intended layout before hitting the keyboard (I like to think of this as UI layout “pseudocode”)
+ try creating a rough sketch of your intended layout before hitting the keyboard (I like to think of this as UI layout “pseudocode”)
- keeping clean code is important – we haven’t even any added any content yet and our UI is already >70 lines of code!
+ keeping clean code is important – we haven’t even any added any content yet and our UI is already >70 lines of code!
- use rainbow parentheses, code comments and plenty of space between lines to keep things looking manageable and navigable
+ use rainbow parentheses, code comments and plenty of space between lines to keep things looking manageable and navigable
- use the keyboard shortcut, command + I (Mac) or control + I (Windows), to align messy code – this helps put those off-alignment parentheses back where they belong
+ use the keyboard shortcut, command + I (Mac) or control + I (Windows), to align messy code – this helps put those off-alignment parentheses back where they belong
- things can get out of hand quickly – add one layout section at a time, run your app to check that things look as you intend, then continue
+ things can get out of hand quickly – add one layout section at a time, run your app to check that things look as you intend, then continue
-
-Add data viz: First up, trout
-
-
+
Add data viz: First up, trout
+
+
We’ll be using the and_vertebrates dataset from the {lterdatasampler} package to create our first reactive plot. These data contain coastal cutthroat trout (Oncorhynchus clarkii clarkii) lengths and weights collected in Mack Creek, Andrews Forest LTER. Original data can be found on the EDI Data Portal. Refer back to this slide to revisit our practice data wrangling & visualization script.
-We can also do the bulk of our data wrangling here, rather than in the server (to keep our server code a bit more manageable). If we were reading in a data file (e.g. .csv), we would do that here too. Our new data object clean_trout, will now be available for us to call directly in our server.
-
-
-We can easily copy our wrangling code over from our practice script.
+
+
Add packages & wrangle data in global.R
+
+
+We can also do the bulk of our data wrangling here, rather than in the server (to keep our server code a bit more manageable). If we were reading in a data file (e.g. .csv), we would do that here too. Our new data object clean_trout, will now be available for us to call directly in our server (NOTE: we can easily copy our wrangling code over from our practice script).
-Add a pickerInput for selecting channel_type to your UI
-
+
+
Add a pickerInput for selecting channel_type to your UI
+
+
The channel_type variable (originally called unittype – we updated the name when wrangling data (see line 9 on previous slide)) represents the type of water body (cascade, riffle, isolated pool, pool, rapid, step (small falls), or side channel) data were collected in. We’ll start by building a shinyWidgets::pickerInput() to allow users to filter data based on channel_type.
-
+
Reminder: When we we designed our UI layout, we added a sidebarPanel to our Trout tab with the placeholder text "trout plot input(s) go here". Replace that text with the code for your pickerInput:
Next, we need to create a placeholder in our UI for our trout scatterplot to live. Because we’ll be creating a reactive plot, we can use the plotOutput() function to do so.
-
+
Reminder: When we we designed our UI layout, we added a mainPanel to our Trout tab with the placeholder text "trout plot output goes here". Replace that text with the code for your plotOuput():
+
+
+
ui.R
+
plotOutput(outputId ="trout_scatterplot")
-
+
+
Save and run your app – it won’t look different at first glance, but inspecting your app in a browser window (using Chrome, right click > Inspect) will reveal a placeholder box for your plot output to eventually live:
@@ -2788,15 +2809,18 @@
-
-Tell the server how to assemble pickerInput values into your plotOutput
-
-
+
Tell the server how to assemble pickerInput values into your plotOutput
+
+
Remember the three rules for building reactive outputs:(1) save objects you want to display to output$<id>, (2) build reactive objects using a render*() function, and (3) access input values with input$<id>. When complete, your server should contain the following code:
+
+
+
server.R
+
server <-function(input, output) {# filter trout data ----
@@ -2825,34 +2849,35 @@
} # END server
+
A couple notes/reminders:
-
- If needed, reference your practice script to remind yourself how you planned to filter and plot your data
+
+ If needed, reference your practice script to remind yourself how you planned to filter and plot your data
-
- Reactive data frames need a set of parentheses, (), following the name of the df (see ggplot(trout_filtered_df() ...))
+
+ Reactive data frames need a set of parentheses, (), following the name of the df (see ggplot(trout_filtered_df() ...))
-
- For a cohesive appearance, save your ggplot theme parameters to a named object in global.R (here, myCustomTheme), then apply to all plots in your app. See the following slide for code.
+
+ For a cohesive appearance, save your ggplot theme parameters to a named object in global.R (here, myCustomTheme), then apply to all plots in your app. See the following slide for code.
-
-Save a custom ggplot theme to global.R
-
-
+
Save a custom ggplot theme to global.R
+
+
Rather than re-typing your ggplot theme parameters out for every plot in your app, do so once in global.R, and save to an object name. You can then easily add your custom theme as a layer to each of your ggplots. Bonus: If you decide to modify your plot theme, you only have to do so in one place!
-Run your app and try out your pickerInput widget!
+
+
Run your app and try out your pickerInput widget!
+
-
-Add a second input that will update the same output
-
-
+
Add a second input that will update the same output
+
+
You can have more than one input control the same output. Let’s now add a checkboxGroupButtons widget to our UI for selecting forest section (either clear cut forest or old growth forest). Check out the function documentation for more information on how to customize the appearance of your buttons.
-
-Be sure to add the widget to the same sidebarPanel as our pickerInput (and separate them with a comma, ,!:
+
+Be sure to add the widget to the same sidebarPanel as our pickerInput (and separate them with a comma!:
-Update your reactive df to also filter based on the new checkboxGroupInput
-
+
+
Update your reactive df to also filter based on the new checkboxGroupInput
+
+
Return to your server to modify trout_filtered_df – our data frame needs to be updated based on both the pickerInput, which selects for channel_type, and the checkboxGrouptInput, which selects for forest section:
-Run your app and try out your pickerInput & checkboxGrouptInput widgets!
+
+
Run your app and try out your pickerInput & checkboxGrouptInput widgets!
+
- Break
+ Break
Up next: your turn to add a reactive penguin plot to our “Penguin” tab!
@@ -2977,7 +3008,7 @@
-
+
@@ -2986,45 +3017,36 @@
-
-Add data viz: Next up, penguins
-
-
+
Add data viz: Next up, penguins
+
+
We’ll be using the penguins dataset from the {palmerpenguins} package to create our second reactive plot. These data contain penguin (genus Pygoscelis) body size measurements collected from three islands in the Palmer Archipelago, Antarctica, as part of the Palmer Station LTER. Original data can be found on the EDI Data Portal (Adélie data, Gentoo data, and Chinstrap data). Refer back to this slide to revisit our practice data wrangling & visualization script.
- Exercise 3: Add a reactive plot to the ‘Penguins’ tab
-
-
+
Exercise 3: Add a reactive plot to the ‘Penguins’ tab
+
+
Working alone or in groups, add a reactive histogram of penguin flipper lengths (using the penguins data set from the {palmerpenguins} package) to the Penguins tab. Your plot should have the following features and look like the example below, when complete:
-
- data colored by penguin species
+
+ data colored by penguin species
-
- a shinyWidgets::pickerInput that allows users to filter data based on island, and that includes buttons to Select All / Deselect All island options at once
+
+ a shinyWidgets::pickerInput that allows users to filter data based on island, and that includes buttons to Select All / Deselect All island options at once
-
- a shiny::sliderInput that allows users to change the number of histogram bins and that by default, displays a histogram with 25 bins
+
+ a shiny::sliderInput that allows users to change the number of histogram bins and that by default, displays a histogram with 25 bins
-
- the two widgets should be placed in the sidebarPanel and the reactive histogram should be placed in the mainPanel of the Penguins tab
+
+ the two widgets should be placed in the sidebarPanel and the reactive histogram should be placed in the mainPanel of the Penguins tab
@@ -3035,44 +3057,37 @@
-
+
See next slide for some tips on getting started!
-
- Exercise 3: Tips
-
+
Exercise 3: Tips
+
Tips:
-
- Remember to load the palmerpenguins package at the top of global.R so that your app can find the data
+
+ Remember to load the palmerpenguins package at the top of global.R so that your app can find the data
-
- Add your widgets to the sidebarPanel and your plot output to the mainPanel of the Penguins tab – look for that placeholder text we added earlier to help place your new code in the correct spot within your UI!
+
+ Add your widgets to the sidebarPanel and your plot output to the mainPanel of the Penguins tab – look for that placeholder text we added earlier to help place your new code in the correct spot within your UI!
-
- Try changing the histogram bin number in your practice code script first, before attempting to make it reactive
+
+ Try changing the histogram bin number in your practice code script first, before attempting to make it reactive
And remember to follow the our three steps for building reactive outputs (1. add input to UI, 2. add output to UI, 3. tell server how to assemble inputs into outputs)!
Next, we’ll finish up v1 of our app by adding some intro text to the landing page
@@ -3280,7 +3294,7 @@
-
+
@@ -3289,9 +3303,8 @@
-
-Lastly: add background/other important information text
-
+
Lastly: add background/other important information text
+
It’s usually valuable (and important) to provide some background information/context for your app – the landing page of your app can be a great place for this. We’re going to add text to our app’s landing page (i.e. the About this App page) so that it looks like the example below:
@@ -3307,28 +3320,28 @@
Some important pieces for information to consider adding:
-
- motivation for building the app
+
+ motivation for building the app
-
- brief instructions for exploring the data
+
+ brief instructions for exploring the data
-
- who maintains the app, where the code lives, how to submit issues/suggestions
+
+ who maintains the app, where the code lives, how to submit issues/suggestions
-
-Adding long text to the UI can get unruly
-
-
+
Adding long text to the UI can get unruly
+
+
For example, I’ve added and formatted my landing page’s text directly in the UI using lots of nested tags – I’ve done this inside the tabPanel titled About this App (Note: I’ve formatted the layout of this page a bit using fluidRow and columns to create some white space around the edges. I’ve also created a faint gray horizontal line, using hr(), beneath which I added a footnote):
+
+
+
ui.R
+
ui <-navbarPage(title ="LTER Animal Data Explorer",
@@ -3437,14 +3450,14 @@
) # END navbarPage
-
-
-Instead, use includeMarkdown() to read in text from separate .md files
-
+
+
Instead, use includeMarkdown() to read in text from separate .md files
+
+
To maintain readability and an overall tidier-looking UI, you can write and style long bodies of text in separate markdown (.md) files that you then read into your UI using the includeMarkdown() function (Important: the includeMarkdown() function requires the markdown package – be sure to add library(markdown) to your global.R file!).
-
+
I recommend saving those .md files in a subdirectory named /text within your app’s directory (e.g. ~/two-file-app/text/mytext.md). See how I simplified my UI by saving my long landing page text to two new files, about.md and footer.md, then imported them into my UI using includeMarkdown().
@@ -3456,6 +3469,10 @@
+
+
+
ui.R
+
ui <-navbarPage(title ="LTER Animal Data Explorer",
@@ -3562,8 +3579,13 @@
) # END navbarPage
+
+
+
+
text/about.md
+
## Welcome to the LTER Animal Data Explorer!<br>
@@ -3579,28 +3601,30 @@
Check out the **Explore the Data** page to find interactive data visualizations looking at Cutthroat trout of the [Andrews Forest LTER](https://andrewsforest.oregonstate.edu/) and Adelie, Gentoo & Chinstrap penguins of the [Palmer Station LTER](https://pallter.marine.rutgers.edu/).
+
+
+
+
text/footer/md
+
*This app is maintained by [Samantha Csik](https://samanthacsik.github.io/) and is updated as needed for teaching purposes. Please report any issues [here](https://github.com/samanthacsik/EDS430-shiny-app/issues). Source code can be found on [GitHub](https://github.com/samanthacsik/EDS430-shiny-app).*
-
-
-Run your app one more time to admire your beautiful creation!
-
-
-
-
+
+
Run your app one more time to admire your beautiful creation!
+
+
+
Again, we have some UX/UI quirks to fix (most notably, blank plots when all widget options are deselected), which we’ll handle soon. But for now, we have a functioning app that we can practice deploying for the first time!
-
-Code recap for app #2v1, so far:
-
-
+
Code recap for app #2v1, so far:
+
+
Additionally, you should have a /text folder within your app’s directory (/two-file-app, if you named it as I did) that contains two markdown files, about.md and footer.md.
Sharing your Shiny app with others isn’t so easy when it just lives on your computer (and your R session has to act as the server that powers it). We’ll now learn how to host your app using shinyapps.io, a free service for sharing your Shiny apps online.
-
-Connect your shinyapps.io account to RStudio
-
-
+
Connect your shinyapps.io account to RStudio
+
+
Go to shinyapps.io and login or create an account (if you don’t already have one) – I created my account and login with GitHub. To use shinyapps.io, you first need to link your account with RStudio on your computer. Follow the instructions on shinyapps.io when you first create your account to install the {rsconnect} package and authorize your account:
-
-
-
-
-
-Deploy your app to shinyapps.io
-
-
+
+
+
Deploy your app to shinyapps.io
+
+
Once your account has been authorized, run rsconnect::deployApp("<app_directory_name>") in your console to deploy your app to shinyapps.io. Here, we’ll run rsconnect::deployApp("two-file-app") to deploy the app we’ve been working on.
-
+
Once deployed, a browser will open to your application. The URL will take the form: https://username.shinyapps.io/your_app_directory_name. You should also now see an /rsconnect folder within your app’s directory – this is generated when an application bundle is successfully deployed and contains a DCF file with information on the deployed content (i.e. the name, title, server address, account, URL, and time). This /rsconnect folder should be added and committed into version control (i.e. push it to GitHub!) so that future re-deployments target the same endpoint (i.e. your app’s URL).
-
-
-
-
-
-The shinyapps.io dashboard
-
-
+
+
+
The shinyapps.io dashboard
+
+
Your shinyapps.io dashboard provides tons of information about your application metrics, instance (the virtualized server that your app is hosted on) and worker (a special type of R process that an Application Instance runs to service requests to an application) settings, plan management, and more. The free plan (the plan we’re using here today) allows you to deploy five Shiny apps. You are able to archive and/or delete once-deployed apps to make space for new ones.
-
-
-
-
+
+
Check out the shinyapps.io user guide for more information on hosting your apps on shinyapps.io.
-
-Other ways to host your Shiny apps
-
-
+
Other ways to host your Shiny apps
+
+
shinyapps.io is not the only Shiny app hosting service (though it’s the easiest to get started with and the only one we’ll be covering in detail in this workshop).
Posit also offers the following:
-
-Shiny server is an open source server which you can deploy for free on your own hardware. It requires more setup and configuration, but can be used without a fee. The Bren and NCEAS servers are configured with Shiny Server for hosting for some in-house apps.
+
+Shiny server is an open source server which you can deploy for free on your own hardware. It requires more setup and configuration, but can be used without a fee. The Bren and NCEAS servers are configured with Shiny Server for hosting for some in-house apps.
-
-Posit connect is a paid product that provides an advanced suite of services for hosting Shiny apps, Quarto and R Markdown reports, APIs, and more.
+
+Posit connect is a paid product that provides an advanced suite of services for hosting Shiny apps, Quarto and R Markdown reports, APIs, and more.
-
-So how should I host my app?
-
+
So how should I host my app?
+
The Bren compute team will work with groups to deploy and maintain apps on in-house servers for up to 6 months after capstone/GP presentations or until they break.
@@ -3888,90 +3898,80 @@
-
-Preferred: Stick with the free tier of shinyapps.io, if you can! This is by far the most straightforward option that requires no server maintenance for you or your client. If your app exceeds the limitations set by the free tier (e.g. requires more active hours, needs more RAM or instances to support high traffic usage, etc.), you/your client have the option to upgrade to a paid tier – there are 5 paid plan types. Check out the shinyapps.io user guide for more information. Consider setting aside your allocated capstone/GP funds to help support a paid shinyapps.io plan.
+
+Preferred: Stick with the free tier of shinyapps.io, if you can! This is by far the most straightforward option that requires no server maintenance for you or your client. If your app exceeds the limitations set by the free tier (e.g. requires more active hours, needs more RAM or instances to support high traffic usage, etc.), you/your client have the option to upgrade to a paid tier – there are 5 paid plan types. Check out the shinyapps.io user guide for more information. Consider setting aside your allocated capstone/GP funds to help support a paid shinyapps.io plan.
-
- If you have a server-savvy client, they may want to deploy/host your app using their own infrastructure. If your client plans to pursue this option, but does not yet have a their own server configured to do so, we recommend directing them to the online instructions for getting started with Shiny Server. PLEASE NOTE that Bren staff (including the compute team) are unable to provide technical support for clients in server configuration and app deployment/maintenance.
+
+ If you have a server-savvy client, they may want to deploy/host your app using their own infrastructure. If your client plans to pursue this option, but does not yet have a their own server configured to do so, we recommend directing them to the online instructions for getting started with Shiny Server. PLEASE NOTE that Bren staff (including the compute team) are unable to provide technical support for clients in server configuration and app deployment/maintenance.
-
+
IMPORTANT: Hosting on a server means that shiny applications will be prone to breaking as updates to server software are made. It is important to have an application maintenance plan in place. This may mean identifying who is responsible for maintaining code, or even deciding to decommission applications and archive the code repository when appropriate.
- Improving user experience
+ Improving user experience
Our two-file-app is looking pretty good! It’s functional and deployed via shinyapps.io. Next, we’ll focus on making some minor tweaks that can help to improve usability
-
- Learning Objectives - App #2v2 (two-file app)
-
-
+
Learning Objectives - App #2v2 (two-file app)
+
+
By the end of this section, you should:
-
- understand how to provide users with helpful error messages using validate()
+
+ understand how to provide users with helpful error messages using validate()
-
- know how to add customizable loading animations to alert users when reactive objects are re-rendering
+
+ know how to add customizable loading animations to alert users when reactive objects are re-rendering
-
- know how to add alternate (alt) text to rendered plots
+
+ know how to add alternate (alt) text to rendered plots
-
- understand how to republish an app using shinyapps.io
+
+ understand how to republish an app using shinyapps.io
We’ll be refining our two-file app with a focus on creating a more user-friendly experience. When finished with v2, we’ll have added:
-
+
(a) user-friendly validation error messages that appear when widgets are used to deselect all data
-
+
(b) loading animations for both two reactive plots
-
+
(c) alternate (alt) text for all data visualizations
@@ -3983,18 +3983,17 @@
-
-Take out any guesswork for your app’s users
-
+
Take out any guesswork for your app’s users
+
It’s important to remove any possible points of confusion for successfully using your app.
-
+
In version 1 of our published app, you’ll notice that users are able to (1) Deselect All data using the pickerInputs for both the trout and penguin plots, and (2) “uncheck” both clear cut forest and old growth forest sampling section buttons using the checkboxGroupInput. When any of these actions are taken by the user, all data are removed from the plot, leaving a completely blank box behind.
-
+
While this response is expected (and normal), we can generate a user-friendly validation error message to provide clear guidance to our users on what is expected by the app in order to display data.
@@ -4006,16 +4005,19 @@
-
-Writing validation tests
-
-
+
Writing validation tests
+
+
validate() tests a condition and returns an error if that conditions fails. It’s used in conjunction with need(), which takes an expression that returns TRUE or FALSE, along with a character string to return if the condition is FALSE.
-
+
Place your validation test(s) at the start of any reactive() or render*() expression that calls input$data. For example, we can add two validation tests inside the reactive that generates our trout_filtered_df – we’ll need two separate validation tests, one for each of our inputs where users can deselect all data.
+
+
+
server.R
+
server <-function(input, output) {# filter for channel types ----
@@ -4033,40 +4035,38 @@
})}
-
-
- & Exercise 4: Add a validation test for your penguin histogram
+
+
& Exercise 4: Add a validation test for your penguin histogram
+
To Do:
-
- Construct a validation test that displays a clear but succinct message when a user deselects all islands using the pickerWidget
+
+ Construct a validation test that displays a clear but succinct message when a user deselects all islands using the pickerWidget
Tips:
-
- Despite having two inputs, we only need one validation test for our Penguins plot. Why is this?
+
+ Despite having two inputs, we only need one validation test for our Penguins plot. Why is this?
-
+
See next slide for a solution!
-
- Exercise 4: A solution
-
+
Exercise 4: A solution
+
+
+
+
server.R
+
server <-function(input, output) {# filter for channel types ----
@@ -4128,29 +4128,33 @@
} # END server
-
-
-Add loading animations to re-rendering outputs
-
+
+
Add loading animations to re-rendering outputs
+
+
The {shinycssloaders} package makes it easy to add visual indicators to outputs as they’re loading or re-rendering. This can be particularly helpful if you have outputs that take a few seconds to render – it alerts users that their updated inputs were recognized and that the app is working to re-render outputs.
-
+
Check out the demo app to start designing your own “spinner” (choose style, color, size).
-
+
We can pipe the withSpinner() function directly into our plotOutputs in ui.R (be sure to load the package in global.R first) – here, we define the spinner color and style (there are 8 different spinner types to choose from) and adjust the size of the penguin plot spinner.
-
# in ui.R
-plotOutput(outputId ="trout_scatterplot") |>
-withSpinner(color ="#006792", type =1)
-
-plotOutput(outputId ="flipperLength_histogram") |>
-withSpinner(color ="#4BA4A4", type =4, size =2)
+
+
+
ui.R
+
+
plotOutput(outputId ="trout_scatterplot") |>
+withSpinner(color ="#006792", type =1)
+
+plotOutput(outputId ="flipperLength_histogram") |>
+withSpinner(color ="#4BA4A4", type =4, size =2)
+
@@ -4161,94 +4165,95 @@
-
-Include alt text for all data visualizations
-
-
+
Include alt text for all data visualizations
+
+
Alt text are written descriptions added to images, and importantly, to data visualizations, to help more users understand the content. Assistive technologies (e.g. screen readers) read alt text out loud for users to hear. When alt text is successfully added, the alt tag (along with your text) should appear in the HTML (right click on your app’s data viz to Inspect and ensure that it was added).
-
+
We’ll talk a bit more about alt text later on, but for now we can add alt text easily to our data visuzliations using the alt argument. Place this outside of the {} but inside the () of renderPlot{()}. For example, we can add alt text to our trout and penguin plots in server.R:
-
# in server.R
-# render trout scatterplot ----
-output$trout_scatterplot <-renderPlot({
-
-ggplot(trout_filtered_df(), aes(x = length_mm, y = weight_g, color = channel_type, shape = channel_type)) +
-geom_point(alpha =0.7, size =5) +
-scale_color_manual(values =c("cascade"="#2E2585", "riffle"="#337538", "isolated pool"="#DCCD7D",
-"pool"="#5DA899", "rapid"="#C16A77", "step (small falls)"="#9F4A96",
-"side channel"="#94CBEC")) +
-scale_shape_manual(values =c("cascade"=15, "riffle"=17, "isolated pool"=19,
-"pool"=18, "rapid"=8, "step (small falls)"=23,
-"side channel"=25)) +
-labs(x ="Trout Length (mm)", y ="Trout Weight (g)", color ="Channel Type", shape ="Channel Type") +
- myCustomTheme
-
- },
-
-alt ="A scatterplot of the relationship between cutthroat trout lengths (mm) (x-axis) and weights (g) (y-axis), with data points colored and shaped based on the water channel type from which they were collected. Trout tend to be longer, but weight less in waterways within the old growth forest. Trout tend to be shorter, but weight more in waterways within the clear cut forest."
-
-) # END render trout scatterplot
+
+
+
server.R
+
+
# render trout scatterplot ----
+output$trout_scatterplot <-renderPlot({
+
+ggplot(trout_filtered_df(), aes(x = length_mm, y = weight_g, color = channel_type, shape = channel_type)) +
+geom_point(alpha =0.7, size =5) +
+scale_color_manual(values =c("cascade"="#2E2585", "riffle"="#337538", "isolated pool"="#DCCD7D",
+"pool"="#5DA899", "rapid"="#C16A77", "step (small falls)"="#9F4A96",
+"side channel"="#94CBEC")) +
+scale_shape_manual(values =c("cascade"=15, "riffle"=17, "isolated pool"=19,
+"pool"=18, "rapid"=8, "step (small falls)"=23,
+"side channel"=25)) +
+labs(x ="Trout Length (mm)", y ="Trout Weight (g)", color ="Channel Type", shape ="Channel Type") +
+ myCustomTheme
+
+ },
+
+alt ="A scatterplot of the relationship between cutthroat trout lengths (mm) (x-axis) and weights (g) (y-axis), with data points colored and shaped based on the water channel type from which they were collected. Trout tend to be longer, but weight less in waterways within the old growth forest. Trout tend to be shorter, but weight more in waterways within the clear cut forest."
+
+) # END render trout scatterplot
+
-
-# render flipperLength hisogram ----
-output$flipperLength_histogram <-renderPlot({
-
-ggplot(na.omit(island_df()), aes(x = flipper_length_mm, fill = species)) +
-geom_histogram(alpha =0.6, bins = input$bin_num) +
-scale_fill_manual(values =c("Adelie"="#FEA346", "Chinstrap"="#B251F1", "Gentoo"="#4BA4A4")) +
-labs(x ="Flipper length (mm)", y ="Frequency",
-fill ="Penguin species") +
- myCustomTheme
-
- },
-
-alt ="A histogram of penguin flipper lengths (mm), with data colored by penguin species. Flipper lengths tend to be smallest on Adélie penguins and largest on Gentoo penguins."
-
-) # END render flipperLength histogram
+# render flipperLength hisogram ----
+output$flipperLength_histogram <-renderPlot({
+
+ggplot(na.omit(island_df()), aes(x = flipper_length_mm, fill = species)) +
+geom_histogram(alpha =0.6, bins = input$bin_num) +
+scale_fill_manual(values =c("Adelie"="#FEA346", "Chinstrap"="#B251F1", "Gentoo"="#4BA4A4")) +
+labs(x ="Flipper length (mm)", y ="Frequency",
+fill ="Penguin species") +
+ myCustomTheme
+
+ },
+
+alt ="A histogram of penguin flipper lengths (mm), with data colored by penguin species. Flipper lengths tend to be smallest on Adélie penguins and largest on Gentoo penguins."
+
+) # END render flipperLength histogram
Now that we’ve added some updates to our app, it’s time to redeploy our newest version.
-
-Redeploying is similar to deploying for the first time
-
+
Redeploying is similar to deploying for the first time
+
Just a few quick steps before your updates are live at your URL from earlier:
-
+
1. double check to make sure any required packages are being imported in global.R
-
+
2. Rerun rsconnect::deployApp("<app-directory-nam")> in your console and type Y when you see the prompt Update application currently deployed at https://githubUserName.shinyapps.io/yourAppName? [Y/n]
-
+
3. Give it a minute (or few) to deploy. Your deployed app will open in a browser window once processed
-
+
4. Push all your files (including the /rsconnect directory) to GitHub
Shiny alone is powerful and flexible, however it can take a lot of work to create a sleek/modern UI. shinydashboard provides a “template” for quickly building visually appealing dashboard apps.
-
- Learning Objectives - App #3 (shinydashboard)
-
-
+
Learning Objectives - App #3 (shinydashboard)
+
+
After this section, you should:
-
- understand the general workflow for pre-processing, saving & reading data into an app
+
+ understand the general workflow for pre-processing, saving & reading data into an app
-
- be comfortable building out a dashboard UI using shinydashboard layout functions
+
+ be comfortable building out a dashboard UI using shinydashboard layout functions
-
- understand how to add static images to your app
+
+ understand how to add static images to your app
-
- feel comfortable creating a basic reactive leaflet map
+
+ feel comfortable creating a basic reactive leaflet map
-
+
Packages introduced:
-
-shinydashboard: provides an alternative UI framework for easily building dashboard-style shiny applications
+
+shinydashboard: provides an alternative UI framework for easily building dashboard-style shiny applications
In this section, we’ll be building a shinydashboard using data downloaded from the Arctic Data Center. We’ll be building out the following features:
@@ -4342,16 +4337,16 @@
-
+
(a) a dashboardHeader with the name of your app
-
+
(b) a dashboardSidebar with two menuItems
-
+
(c) a landing page with background information about your app
-
+
(d) an interactive and reactive leaflet map
@@ -4363,9 +4358,8 @@
-
-But first, what do we mean by a shiny “dashboard”?
-
+
But first, what do we mean by a shiny “dashboard”?
+
shinydashboard is just an alternative framework for building shiny apps. In other words, shiny dashboards are just shiny apps, but with some different UI elements that make building apps with a classic “dashboard” feel to them a little bit easier.
@@ -4373,10 +4367,9 @@
-
-The most basic shinydashboard is made up of a header, a sidebar, and a body
-
-
+
The most basic shinydashboard is made up of a header, a sidebar, and a body
+
+
The main difference between a shiny app and a shinydashboard are the UI elements. Rather than a fluidPage() (as used in our previous shiny apps), we’ll create a dashboardPage(), which expects three main parts: a header, a sidebar, and a body. Below is the most minimal possible UI for a shinydashboard page (you can run this code in an app.R file, if you wish).
@@ -4410,41 +4403,33 @@
-
-Example shiny dashboards built by some familiar folks
-
-
-Bren Student Data Explorer (source code), by MEDS 2022 alum, Halina Do-Linh, during her Bren Summer Fellowship (and continued by future MEDS students!) – explore Bren school student demographics and career outcomes
+
Example shiny dashboards built by some familiar folks
+
+
+Bren Student Data Explorer (source code), by MEDS 2022 alum, Halina Do-Linh, during her Bren Summer Fellowship (and continued by future MEDS students!) – explore Bren school student demographics and career outcomes
First, create a subdirectory called /shinydashboard and add a ui.R, server.R, and global.R file.
-
+
Add the server function to server.R and the three main UI components (header, sidebar, and body) to our dashboard page. You can do so just as the example a few slides back, or alternatively, you can split the UI into separate pieces, then combine them into a dashboardPage the end of ui.R (as shown below) – this can help with organization as you app grows in complexity.
-
+
We’ll set our dashboard aside for now while we work on downloading and pre-processing our data, as well as practice creating our data visualization outside of our app.
@@ -4484,9 +4469,8 @@
-
-As always, let’s start with the data
-
+
As always, let’s start with the data
+
Building an app doesn’t make much sense if we don’t know what we’re going to put in it. So, just like the last two apps, we’ll start with some data wrangling and practice data visualization.
@@ -4497,7 +4481,7 @@
-
+
Christopher Arp, Matthew Whitman, Katie Drew, and Allen Bondurant. 2022. Water depth, surface elevation, and water temperature of lakes in the Fish Creek Watershed in northern Alaska, USA, 2011-2022. Arctic Data Center. doi:10.18739/A2JH3D41P.
@@ -4510,35 +4494,37 @@
-
-Pre-processing data is critical
-
-
+
Pre-processing data is critical
+
+
Where you choose to store the data used by your Shiny app will depend largely on the type and size of the file(s) and who “owns” those data. It is likely that you’ll be working with data stored in a database or on a server. This is outside the scope of this workshop, but I suggest reading Dean Attali’s article, Persistent data storage in Shiny apps to start. Because we are going to be working with a relatively small data set, we’ll be downloading and storing our data locally (i.e. on our machines and in our GitHub repo).
-
+
Regardless of where you choose to store your data, you can help your application more quickly process inputs/outputs by providing it only as much data as needed to run. This means pre-processing your data.
-
-
+
FCWO_lakemonitoringdata_2011_2022_daily.csv contains 8 attributes (variables) and 18,894 observations collected from a set of 11 lakes located in the Fish Creek Watershed in northern Alaska between 2011-2022. We’ll download and save the file to a raw_data/ folder in the root directory of our repository. We’ll then pre-process the data in a separate script(s) saved to scratch/ and save a cleaned/processed version of the data to our app’s directory, /shinydashboard/data/lake_data_processed.csv. Your repository structure should look similar to example on the right:
-
-
-
+
+
+
+
+
+
-
-
-The Goal:
+
+
+
The Goal:
+
@@ -4554,13 +4540,16 @@
-
-Process lake data & save new file
-
-
+
Process lake data & save new file
+
+
NOTE: In this example exercise, I’ve removed all rows with missing values (i.e. NaNs in the Depth column & NAs in the BedTemperature column) before calculating averages. This is NOT good practice – exploring and thinking critically about missing data is an important part of data analysis, and in a real-life scenario, you should consider the most appropriate method for handling them.
+
+
+
scratch/data_processing_app3_shinydashboard.R
+
#....................SETUP & DATA PROCESSING.....................# load packages ----
@@ -4591,24 +4580,23 @@
# save processed data to your app's data directory ----write_csv(unique_lakes, "shinydashboard/data/lake_data_processed.csv")
-
-
-A note on file types
-
+
+
A note on file types
+
+
Oftentimes, you may choose to save your processed data frame as a .rds file (a data file format, native to R, which stores a single R object). .rds file are relatively small (and therefore take up little storage space), take less time to import/export, and preserve data types and classes (e.g. factors and dates), eliminating the need to redefine data types after loading the file. Bear in mind that this increased speed and space-saving may come at the cost of generality – you can’t open a .rds file outside of R or read it in with another programming language (e.g. Python).
-
+
While we’ll be sticking to .csv files in this workshop, it’s worth experimenting with .rds when you begin working with your own (likely larger) data. You can read in (readRDS()) and write out to (saveRDS()) .rds files as easily as .csv files.
-
-Draft leaflet map
-
-
+
Draft leaflet map
+
+
There are lots of ways to customize leaflet maps. We’ll be keeping ours relatively simple, but check out the Leaflet for R documentation for more ways to get creative with your maps.
@@ -4620,13 +4608,17 @@
-
-
+
+
+
+
+
scratch/practice_script_app3_shinydashboard.R
+
#....................SETUP & DATA PROCESSING.....................# omitted for brevity (see slide 112 for code)
@@ -4655,11 +4647,11 @@
-
-
-Practice filtering leaflet observations
-
+
+
Practice filtering leaflet observations
+
+
We’ll eventually build three sliderInputs to filter lake makers by Elevation, AvgDepth, and AvgTemp. Practice filtering here first (and be sure to update the data frame name in your leaflet code!):
@@ -4671,13 +4663,17 @@
-
-
+
+
+
+
+
scratch/practice_script_app3_shinydashboard.R
+
#....................SETUP & DATA PROCESSING.....................# omitted for brevity (see slide 112 for code)
@@ -4714,11 +4710,11 @@
-
-
-Sketch out our dashboard UI
-
+
+
Sketch out our dashboard UI
+
+
I want my dashboard to have two menu items: a welcome page with some background information, and a dashboard page with my reactive map. All elements will be placed inside boxes, the primary building blocks of shinydashboards (more on that soon).
@@ -4734,16 +4730,19 @@
-
-Add a title & menuItems
-
-
+
Add a title & menuItems
+
+
First, add a title to dashboardHeader() and make more space using titleWidth, if necessary.
-
+
Next, we’ll build our dashboardSidebar(). Add a sidebarMenu() that contains two menuItems. Be sure to provide each menuItem() with text as you’d like it to appear in your app (for me, that’s Welcome and Dashboard), and a tabName which will be used to place dashboardBody() content in the appropriate menuItem(). Optionally, you can provide an icon. By default, icon() uses icons from FontAwesome.
+
+
+
ui.R
+
#........................dashboardHeader.........................header <-dashboardHeader(
@@ -4772,14 +4771,18 @@
#..................combine all in dashboardPage..................dashboardPage(header, sidebar, body)
-
-
-Add tabItems to your dashboardBody
-
+
+
Add tabItems to your dashboardBody
+
+
Next, we’ll create tabItems in our dashboardBody – we’ll make a tabItem (singular) for each menuItem in our dashboardSidebar. In order to match a menuItem and a tabItem, ensure that they have matching a tabName (e.g. any content added to the dashboardtabItem will appear under the dashboardmenuItem).
+
+
+
ui.R
+
#........................dashboardHeader.........................header <-dashboardHeader(
@@ -4829,14 +4832,18 @@
#..................combine all in dashboardPage..................dashboardPage(header, sidebar, body)
-
-
-Add boxes to contain UI content (part 1)
-
+
+
Add boxes to contain UI content (part 1)
+
+
Boxes are the primary building blocks of shinydashboards and can contain almost any Shiny UI element (e.g. text, inputs, outputs). Start by adding two side-by-side boxes to our dashboard tab inside a fluidRow(). Together, their widths will add up to 12 (the total width of a browser page). These boxes will eventually contain our sliderInputs and our leafletOutput.
+
+
+
ui.R
+
#........................dashboardHeader.........................header <-dashboardHeader(
@@ -4903,14 +4910,18 @@
#..................combine all in dashboardPage..................dashboardPage(header, sidebar, body)
-
-
-Add boxes to contain UI content (part 2)
-
+
+
Add boxes to contain UI content (part 2)
+
+
Lastly, add boxes to our welcome tab We’ll use columns to place one box on the left-hand side of our page, and two stacked boxes on the right-hand side. Each column will take up half the page (Note:For column-based layouts, use NULL for the box width, as the width is set by the column that contains the box). We can create two fluidRows within the right-hand column to stack two boxes vertically.
+
+
+
ui.R
+
#........................dashboardHeader.........................header <-dashboardHeader(
@@ -5016,14 +5027,18 @@
#..................combine all in dashboardPage..................dashboardPage(header, sidebar, body)
-
-
-Read data into global.R & add necessary packages
+
+
Read data into global.R & add necessary packages
+
Remember to load your pre-processed data, which should live in the /data folder within your app’s directory.
+
+
+
global.R
+
# LOAD LIBRARIES ----library(shiny)library(shinydashboard)
@@ -5034,14 +5049,18 @@
# READ IN DATA ----lake_data <-read_csv("data/lake_data_processed.csv")
-
-
-Add a sliderInput & leafletOutput to the UI
-
+
+
Add a sliderInput & leafletOutput to the UI
+
+
Start by adding just one sliderInput (for selecting a range of lake Elevations) to the left-hand box in the dashboard tab. Then, add a leafletOutput to create a placeholder space for our map, along with a Spinner animation (from the shinycssloaders package). While we’re here, we can also add titles to each box.
+
+
+
ui.R
+
#........................dashboardHeader.........................header <-dashboardHeader(
@@ -5155,14 +5174,18 @@
#..................combine all in dashboardPage..................dashboardPage(header, sidebar, body)
-
-
-Assemble inputs & outputs in server.R
-
+
+
Assemble inputs & outputs in server.R
+
+
Remember to reference your practice data viz script and to follow our three steps for creating reactive outputs. And don’t forget to add () following each reactive data frame called in your leaflet map!
+
+
+
server.R
+
server <-function(input, output) {# filter lake data ----
@@ -5201,10 +5224,10 @@
}
-
-
-Run your app & test out your first widget
+
+
Run your app & test out your first widget
+
If all is good, you should see something similar to this:
@@ -5212,32 +5235,26 @@
-
- Exercise 5: Add two more sliderInputs to filter for AvgDepth & AvgTemp
-
+
Exercise 5: Add two more sliderInputs to filter for AvgDepth & AvgTemp
+
To Do:
-
- Add two more sliderInputs, one for AvgDepth and one for AvgTemp beneath our first Elevation sliderInput in the UI
+
+ Add two more sliderInputs, one for AvgDepth and one for AvgTemp beneath our first Elevation sliderInput in the UI
-
- Update our reactive data frame so that all three widgets filter the leaflet map
+
+ Update our reactive data frame so that all three widgets filter the leaflet map
Up next: Adding background information and an image to our Welcome tab
@@ -5425,7 +5441,7 @@
-
+
@@ -5434,21 +5450,16 @@
-
- & Exercise 6: Add titles & text to Welcome page boxes
-
+
& Exercise 6: Add titles & text to Welcome page boxes
+
To Do:
-
- Add titles to each box
+
+ Add titles to each box
-
- Create a /text folder within your app’s directory and add three markdown (.md) files. Write/format text for the background info (left), data citation (top-right), and disclaimer (bottom-right) boxes. Example text below:
+
+ Create a /text folder within your app’s directory and add three markdown (.md) files. Write/format text for the background info (left), data citation (top-right), and disclaimer (bottom-right) boxes. Example text below:
@@ -5459,37 +5470,49 @@
+
+
+
text/intro.md
+
The [Fish Creek Watershed Observatory (FCWO)](http://www.fishcreekwatershed.org/) is a focal watershed within the [National Petroleum Reserve in Alaska (NPR-A)](https://www.blm.gov/programs/energy-and-minerals/oil-and-gas/about/alaska/NPR-A). Targeted lake and stream monitoring within the watershed provide site-specific data prior to and after the establishment of new petroleum development, as well as insight into dynamics related to climate change and variability. Eleven lakes of interest (Harry Potter, Hipbone, Iceshove, L9817, L9819, L9820, Little Alaska, Lower Snowman, M9925, Middle Snowman, and Serenity) are featured in this dashboard.
+
+
+
+
text/citation.md
+
Data presented in this dashboard were collected as part of the [Fish Creek Watershed Observatory](http://www.fishcreekwatershed.org/) are archived and publicly accessible on the NSF [Arctic Data Center](https://arcticdata.io/). **Citation:** *Christopher Arp, Matthew Whitman, Katie Drew, and Allen Bondurant. 2022. Water depth, surface elevation, and water temperature of lakes in the Fish Creek Watershed in northern Alaska, USA, 2011-2022. Arctic Data Center [doi:10.18739/A2JH3D41P](https://arcticdata.io/catalog/view/doi%3A10.18739%2FA2JH3D41P).*
+
+
+
+
text/disclaimer.md
+
This app is build for demonstration/teaching purposes only and is not paid for or endorsed by the Fish Creek Watershed Observatory or affiliates in any way. The data as presented here are not intended for publication nor scientific interpretation.
+
Tips:
-
-Titles can include icons! For example: title = tagList(icon("icon-name"), strong("title text here"))
+
+ Titles can include icons! For example: title = tagList(icon("icon-name"), strong("title text here"))
-
- Exercise 6: A solution
-
-
+
Exercise 6: A solution
+
+
Press the right arrow key to advance through the newly added lines of code.
@@ -5642,16 +5665,19 @@
-
-Add a static image
-
-
+
Add a static image
+
+
As a final touch, let’s add an image to the Welcome page, inside the left-hand box beneath our intro text. First, create a /www folder inside your app’s directory (refer back to this slide for a description of this special directory). Download the map of the Fish Creek Watershed from FCWO’s website here and save it to your /www directory.
-
+
Next, use the img tag to add your image. Supply a file path, relative to your /www directory, using the src argument, and alt text using the alt argument.
+
+
+
ui.R
+
#........................dashboardHeader.........................header <-dashboardHeader(
@@ -5778,25 +5804,27 @@
#..................combine all in dashboardPage..................dashboardPage(header, sidebar, body)
-
-
-Unfortunately, our image doesn’t look so great as-is…
-
+
+
Unfortunately, our image doesn’t look so great as-is…
+
-
-Use in-line CSS to adjust the image size
-
-
+
Use in-line CSS to adjust the image size
+
+
We can use in-line CSS to style our image element, as shown below (see style argument). It’s okay if you don’t fully understand what’s going on here for now – we’ll talk in greater detail about how CSS (and Sass) can be used to customize the appearance of your apps in just a bit.
-
+
I’ve also added a caption below our image that links to the image source, and used in-line CSS to center my text within the box.
+
+
+
ui.R
+
#........................dashboardHeader.........................header <-dashboardHeader(
@@ -5926,20 +5954,19 @@
#..................combine all in dashboardPage..................dashboardPage(header, sidebar, body)
-
-
-Check out your finished dashboard!
+
+
Check out your finished dashboard!
+
-
+
There’s a ton more to learn about building shinydashboards. Check out the documentation to find instructions on adding components like infoBoxes and valueBoxes, building inputs in the sidebar, easy ways to update the color theme using skins, and more.
By the end of this section, you should be equipped with:
-
- a number of different approaches for themeing and styling your shiny apps and dashboards
+
+ a number of different approaches for themeing and styling your shiny apps and dashboards
-
- a basic understanding of how to apply CSS & Sass styling to your app
+
+ a basic understanding of how to apply CSS & Sass styling to your app
-
+
Packages introduced:
-
-bslib: provides tools for customizing Bootstrap themes directly from R for shiny apps and RMarkdowns
+
+bslib: provides tools for customizing Bootstrap themes directly from R for shiny apps and RMarkdowns
-
-fresh: provides tools for creating custom themes for use with shiny, shinydashboard, and bs4Dash apps
+
+fresh: provides tools for creating custom themes for use with shiny, shinydashboard, and bs4Dash apps
- Creating custom themes
+ Creating custom themes
We’ve built some really cool apps so far, but they all have a pretty standard and similar appearance. In this section, we’ll explore two packages for creating custom themes for your apps.
The {bslib} package provides tools for customizing Bootstrap themes directly from R, making custom themeing for Shiny apps (and R Markdown docs!) quite easy.
- plays well with the thematic package for matching plot styling to app
+
+ plays well with the thematic package for matching plot styling to app
-
-bslib does more than just themeing! Check out the December 2022 announcement of new UI components made possible with the latest package release
+
+bslib does more than just themeing! Check out the December 2022 announcement of new UI components made possible with the latest package release
-
+
Cons:
-
- does not work with shinydashboard (bslib is only intended for use with shinyapps)
+
+ does not work with shinydashboard (bslib is only intended for use with shinyapps)
-
- styling is constrained by the arguments available to bs_theme()
+
+ styling is constrained by the arguments available to bs_theme()
@@ -6262,16 +6269,19 @@
-
-Apply a pre-built theme with {bslib}
-
-
+
Apply a pre-built theme with {bslib}
+
+
By default, Shiny uses the Bootstrap v3 theme (which is not so exciting). Change the theme to a slightly more modern Bootstrap v5 theme by setting the theme argument of fluidPage() to bslib::bs_theme(version = 5), or supply bs_theme() with a pre-built bootswatch theme, as shown below (for a list of theme names, run bootswatch_themes() in your console):
Check out the complete source code for App #1 here (NOTE: applied themes are commented out).
@@ -6325,20 +6340,23 @@
-
+
Be sure to check out the interactive themeing widget to test custom color/font/etc. combos by running bs_theme_preview() in your console, or visit the hosted version here. You can also call bs_themer() within your server function to open the theme customization UI alongside your own app.
-
-Use {thematic} to extend your theme to plots
-
-
+
Use {thematic} to extend your theme to plots
+
+
You probably noticed that our scatterplot looks a little silly against the darker background of our themed app. Enter the {thematic} package, which is built to help simplify plot themeing. Call thematic_shiny() before launching your app to generate plots that reflect your application’s bs_theme(). For example:
The {fresh} package provides tools for creating custom themes to use in Shiny apps and dashboards – set parameters of your theme using create_theme(), generate a stylesheet based off your specifications, and apply your stylesheet to your app.
- styling is constrained by the variables available to create_theme()
+
+ styling is constrained by the variables available to create_theme()
@@ -6413,16 +6428,15 @@
-
-A general workflow for using fresh themes
-
+
A general workflow for using fresh themes
+
Whether you’re working on a shiny app or a shiny dashboard, you’ll need the following:
-
+
1. a /www folder within your app’s directory – this is where we’ll save the stylesheet (a .css file) that fresh will generate for us
-
+
2. a separate script for building our theme using the create_theme() function – I recommend saving this to ~/scratch (it seemed to cause issues when saved anywhere within my app directory)
@@ -6434,52 +6448,53 @@
-
-Creating a fresh theme for two-file-app
-
-
-In this example, we update the colors of our app’s body, navbar, and tabPanels using the appropriate freshvariables for shiny apps. We specify a file path, two-file-app/www (you’ll need to create the /www directory, since we don’t have one yet), where our stylesheet (e.g. shiny_fresh_themes.css, as shown here) file will be saved to.
-
-
-Of course, these color combos are not recommended, but chosen purely for demonstration purposes .
-
-
-
# in a separate script: ~/R/create_fresh_theme_shiny.R
-# load library ----
-library(fresh)
-
-# create theme -----
-create_theme(
-
-# you can supply a bootstrap theme to begin with
-theme ="default",
-
-# global styling
-bs_vars_global(
-body_bg ="#D2D0CA", # beige
-text_color ="#F23ACB", # hot pink
-link_color ="#0E4BE3"# royal blue
- ),
-
-bs_vars_navbar(
-default_bg ="#13CC13", # lime green
-default_color ="#66656C"# gray
- ),
-
-# tabPanels
-bs_vars_tabs(
-border_color ="#F90909"# red
- ),
-
-# generate css file
-output_file ="two-file-app/www/shiny_fresh_theme.css"
-)
+
Creating a fresh theme for two-file-app
+
+
+In this example, we update the colors of our app’s body, navbar, and tabPanels using the appropriate freshvariables for shiny apps. We specify a file path, two-file-app/www (you’ll need to create the /www directory, since we don’t have one yet), where our stylesheet (e.g. shiny-fresh-theme.css, as shown here) file will be saved to.
+
+
+Of course, these color combos are not recommended, but chosen purely for demonstration purposes .
+
+
+
+
+
~/R/create-fresh-theme-shiny.R
+
+
# load library ----
+library(fresh)
+
+# create theme -----
+create_theme(
+
+# you can supply a bootstrap theme to begin with
+theme ="default",
+
+# global styling
+bs_vars_global(
+body_bg ="#D2D0CA", # beige
+text_color ="#F23ACB", # hot pink
+link_color ="#0E4BE3"# royal blue
+ ),
+
+bs_vars_navbar(
+default_bg ="#13CC13", # lime green
+default_color ="#66656C"# gray
+ ),
+
+# tabPanels
+bs_vars_tabs(
+border_color ="#F90909"# red
+ ),
+
+# generate css file
+output_file ="two-file-app/www/shiny-fresh-theme.css"
+)
-
-
-Apply a fresh theme to our app
+
+
Apply a fresh theme to our app
+
To apply our theme, provide the theme argument of your fluidPage() or navbarPage() with the name of our stylesheet. Note: shiny knows to look in the /www directory, so you can omit that from your file path, as shown below:
Check out the complete source code for App #2 here (NOTE: applied themes are commented out).
@@ -6509,47 +6529,49 @@
-
-Creating a fresh theme for our shinydashboard
-
-
-In this example, we update the colors of our app’s header, body, and sidebar using the appropriate freshvariables for shiny dashboards. We specify a file path, shinydashboard/www where our stylesheet (e.g. shinydashboard_fresh_themes.css, as shown here) file will be saved to. Again, these color combos are not recommended, but chosen purely for demonstration purposes.
-
-
-
# in a separate script: ~/R/create_fresh_theme_shinydashboard.R
-# load libraries ----
-library(fresh)
-
-# create theme ----
-create_theme(
-
-# change "light-blue"/"primary" color
-adminlte_color(
-light_blue ="#150B5A"# dark blue
- ),
-
-# dashboardBody styling (includes boxes)
-adminlte_global(
-content_bg ="#E7B5B5"# blush pink
- ),
-
-# dashboardSidebar styling
-adminlte_sidebar(
-width ="400px",
-dark_bg ="#57F8F3", # light blue
-dark_hover_bg ="#BF21E6", # magenta
-dark_color ="#F90000"# red
- ),
-
-# generate css file
-output_file ="shinydashboard/www/shinydashboard_fresh_theme.css"
-
-)
+
Creating a fresh theme for our shinydashboard
+
+
+In this example, we update the colors of our app’s header, body, and sidebar using the appropriate freshvariables for shiny dashboards. We specify a file path, shinydashboard/www where our stylesheet (e.g. shinydashboard-fresh-theme.css, as shown here) file will be saved to. Again, these color combos are not recommended, but chosen purely for demonstration purposes.
+
To apply our theme, use the fresh::use_theme() function inside your dashboardBody, providing it with the name of your stylesheet. Note: shiny knows to look in the /www directory, so you can omit that from your file path, as shown below:
@@ -6558,6 +6580,10 @@
+
+
+
~/shinydashboard/ui.R
+
body <-dashboardBody(# set theme
@@ -6567,7 +6593,8 @@
)
-
+
+
Check out the complete source code for the shinydashboard here (NOTE: applied themes are commented out).
@@ -6581,51 +6608,44 @@
- Styling apps with CSS & Sass
+ Styling apps with CSS & Sass
bslib & fresh are great ways to get started on your app customization journeys, but knowing some CSS & Sass can help you really fine-tune the appearance of your apps
You can write your own stylesheets using CSS and Sass to fully customize your apps, from background colors, to font styles, to size and shape of elements, and more. Unlike bslib and fresh, these are languages, meaning they can be a bit more challenging to get started with (but the payoff it big!).
-
-
+
Pros:
-
- applies to any web page (not just shiny apps)
+
+ applies to any web page (not just shiny apps)
-
- allows you to customize pretty much any aspect of your app
+
+ allows you to customize pretty much any aspect of your app
-
- can be combined with themes generated using bslib or fresh to fine-tune your app’s styling
+
+ can be combined with themes generated using bslib or fresh to fine-tune your app’s styling
-
+
Cons:
-
- a steeper learning curve/generally more complex than packages like bslib and fresh
+
+ a steeper learning curve/generally more complex than packages like bslib and fresh
@@ -6637,9 +6657,8 @@
-
-Resources for a deeper dive
-
+
Resources for a deeper dive
+
We’ll be doing a rather high-level and quick overview of Sass & CSS today, though I encourage you to check out the Customizing Quarto Websites workshop, which takes a much deeper dive (the information in that workshop is largely applicable here).
@@ -6653,16 +6672,15 @@
-
-What even is CSS? Sass?
-
+
What even is CSS? Sass?
+
-
+
CSS (Cascading Style Sheets) is a programming language that allows you to control how HTML elements look (e.g. colors, font styles, etc.) on a webpage.
@@ -6674,16 +6692,15 @@
-
+
Sass (Syntactically Awesome Stylesheets) is a CSS extension language and CSS preprocessor – meaning Sass needs to be converted (aka compiled) to CSS before it can be interpreted by your web browser.
-
-CSS is a rule-based language
-
+
CSS is a rule-based language
+
CSS is a rule-based language, meaning that it allows you to define groups of styles that should be applied to particular elements or groups of elements on a web page. For example, “I want all level one headings (<h1> or tags$h1() as written in Shiny) in my app to be green with a bit of extra space between each letter” could be coded as:
@@ -6696,39 +6713,35 @@
-
-Selectors select the HTML element(s) you want to style (e.g. level one headings, <h1>)
+
+Selectors select the HTML element(s) you want to style (e.g. level one headings, <h1>)
-
-Declarations sit inside curly brackets, {}, and are made up of property and value pairs. Each pair specifies the property of the HTML element(s) you’re selecting (e.g. the color property of the element <h1>), and a value you’d like to assign to that property (e.g. green)
+
+Declarations sit inside curly brackets, {}, and are made up of property and value pairs. Each pair specifies the property of the HTML element(s) you’re selecting (e.g. the color property of the element <h1>), and a value you’d like to assign to that property (e.g. green)
-
- A property and it’s corresponding value are separated by a colon, :. Declarations end with a semicolon, ;
+
+ A property and it’s corresponding value are separated by a colon, :. Declarations end with a semicolon, ;
-
+
There are a variety of CSS selectors – check out some of the basics that will take you far in styling your apps, starting on this slide of the Customizing Quarto Websites workshop.
-
-3 ways to add CSS styling to your apps
-
-
-You can (1) add styling directly to tags, (2) add CSS rules to your header, and/or (3) build a stylesheet that is applied to your app. Creating a stylesheet is the preferred approach, and you should do this whenever possible.
+
3 ways to add CSS styling to your apps
+
+
+You can (1) add styling directly to tags, (2) add CSS rules to your header, and/or (3) build a stylesheet that is applied to your app. Creating a stylesheet is often the preferred approach.
Add styling directly to tags. It’s best not to use a lot of these! It’s easy to lose track of your “in-line” styling in large projects, you can’t reuse rules easily, it’s hard to keep styling consistent, and it’s difficult to implement large stylistic changes.
@@ -6773,7 +6786,7 @@
-
+
Add CSS rules to your app’s header (tags$head). This is a little bit better than option 1 since it allows for the reuse of rules, however, styles can’t be cached (i.e. saved for future usage when you reopen your app). Note: explore Google fonts here and check out this slide for instructions on selecting a font.
@@ -6826,7 +6839,7 @@
-
+
Build a stylesheet (a .css file) inside your app’s www/ directory and apply your styles to your app’s header (for shinydashboards, include your header inside dashboardBody(). This is the most ideal approach – it allows for style reuse, caching, and keeps styling contained in one spot. Tip: use touch styles.css in the terminal to create a new .css file.
-What if I want to style an element, but don’t know how to target it?
-
-
+
What if I want to style an element, but don’t know how to target it?
+
+
Oftentimes, you’ll have to do a bit of exploration to determine how to target specific elements for styling. In either your app viewer or web browser, right click on an element of interest and choose Inspect (or Inspect Element) to open up the underlying HTML and CSS. You can make temporary edits to your app (e.g. adding a background color, changing font sizes, etc.) to see how they look first, then copy the appropriate CSS rule into your stylesheet to apply to your app.
-
-Inspect & identify how to update box styling
-
-
+
Inspect & identify how to update box styling
+
+
For example, let’s say I want to change the color of this shinydashboard’s boxes and the color of the box text.
-
+
First, we need to determine which type of HTML element creates our box. Right clicking on a box and choosing Inspect Element pulls up the HTML and CSS files underlying the app. Hovering over different parts of the HTML highlights different elements in the UI. The box is highlighted when I hover over <div class="box-body"> – this tells me that boxes are formed using the <div> HTML element and they’re assigned a class called box-body.
-
+
Next, we can (temporarily) adjust the CSS rules that style these boxes to see how they work. I can hop down to the CSS file (here, that’s located in the bottom half of my sidebar, but depending on the size of your window/layout, the HTML and CSS might be side-by-side) and find the .box-body class selector. You can add property/value pairs and/or update existing property values to adjust the appearance of our box. Notice that changing the .box-body class selector updates both boxes – upon inspecting the box containing our plot, you’ll notice that it is also of class, box-body. Therefore changes to this class selector will apply to both boxes. This process is purely for testing purposes – refreshing your app will remove any of these changes.
-
-Finally, apply box styling to our dashboard
-
-
+
Finally, apply box styling to our dashboard
+
+
Now that we know that we can use the box-body class to customize the appearance of our boxes, let’s create a stylesheet and add our new rules. The shinydashboard framework already provides the “standard” styling for boxes, contained in the box-body class. Anything we specify in our own stylesheet will build upon or modify existing styling.
-
+
Remember to create a header and link your stylesheet within dashboardBody() to apply our styles.
@@ -7156,9 +7165,8 @@
-
-What about Sass?
-
+
What about Sass?
+
Okay, we wrote and applied some CSS styling to our apps, but what about Sass? You don’t need to write any Sass at all, however, it provides a number of benefits, including helping to reduce repetition.
@@ -7172,10 +7180,9 @@
You might imagine how often you’ll need to type those HEX codes out as you developing your stylesheet…it can get annoying rather quickly.
-
-We can define and reference Sass variables throughout our stylesheet
-
-
+
We can define and reference Sass variables throughout our stylesheet
+
+
Sass allows us to define variables (in the form $var-name: value;) for our colors to reference instead of writing out their HEX codes each time:
@@ -7197,45 +7204,47 @@
border-color: $darkgray;}
-
+
If you decide that you actually like a different shade of teal better, you’ll only need to update the hex code where you first define the $teal Sass variable, saving lots of time.
-
-Sass for Shiny workflow
-
+
Sass for Shiny workflow
+
To style apps using both Sass and CSS, you’ll follow this general workflow:
-
+
1. Create a .scss file inside ~/myapp/www using the touch command in the terminal (e.g. cd into the appropriate directory, then touch styles.scss). Write both your Sass variables and CSS rules in your .scss file (Note: you can write both Sass & CSS in a .scss file, but only CSS in a .css file)
-
+
2. Compile (i.e. convert) Sass to CSS in global.R (or, if using a one-file app, at the top of your script before you define your UI) using the the sass() function from the {sass} package – this will generate a .css file that our shiny app can actually use. Be sure to save your .css file to your app’s /www directory.
-
+
3. Apply your styles to your app by linking to to your .css file in your app’s header.
-
-Let’s build our Sass file
-
-
+
Let’s build our Sass file
+
+
We’ll practice on our two-file-app – first, remove any reference to your bslib or fresh themes that we practiced applying earlier so that we’re starting off with just the default shiny styling.
-
-Next, create your Sass file within two-file-app/www/. Then, using your terminal, cd into ~/two-file-app/www and use the touch command to create a .scss file (I’m calling mine my_sass_styles.scss).
+
+Next, create your Sass file within two-file-app/www/. Then, using your terminal, cd into ~/two-file-app/www and use the touch command to create a .scss file (I’m calling mine my-sass-styles.scss).
-
-Add Sass variables and CSS rules to my_sass_styles.scss:
+
+Add Sass variables and CSS rules to my-sass-styles.scss:
Because web browsers can only interpret CSS (not Sass), we need to compile our Sass to CSS. To do this, we can use the sass() function from the {sass} package. We can do this in global.R. The sass() function requires two arguments: a sass file input and a file path + named .css file output.
-
+
We also need to apply our styles to our app by linking this newly-generated .css file in our app’s header.
-
-Note: After running your app, you should see a my_sass_styles.css file appear in www/ – it should look quite familiar, except all of our Sass variables have been converted to CSS.
+
+Note: After running your app, you should see a my-sass-styles.css file appear in www/ – it should look quite familiar, except all of our Sass variables have been converted to CSS.
- Part 4: Improving your app’s user experience (UX)
-
-
-
- Important UX considerations
+
Part 4: Improving your app’s user experience (UX)
+
+
+ Important UX considerations
-
- Web accessibility
+
+ Web accessibility
- UX/UI matters
+ UX/UI matters
When designing your app, it’s critically important that you consider your user’s needs and how they will interact with your app – it doesn’t matter how innovative you back-end computations are if people don’t understand how to use your app!
-
- Learning Objectives - UX/UI Design
-
-
+
Learning Objectives - UX/UI Design
+
+
After this section, you should:
-
- have a checklist of considerations to reference each time you build an app
+
+ have a checklist of considerations to reference each time you build an app
-
- have a few additional resources to dive deeper into UX/UI design
+
+ have a few additional resources to dive deeper into UX/UI design
-
-Tips for designing your Shiny apps
-
+
Tips for designing your Shiny apps
+
Chapters 6 and 7 of Engineering Production-Grade Shiny Apps, by Colin Fay, Sébastien Rochette, Vincent Guyader, and Cervan Girard provide a list of considerations as you embark on your app-building journey. Some of their suggestions are summarized below, but check out the book for greater detail, examples, and additional considerations:
-
-Simplicity is gold: using the application shouldn’t require reading a manual, and interfaces should be as self-explanatory as possible.
+
+Simplicity is gold: using the application shouldn’t require reading a manual, and interfaces should be as self-explanatory as possible.
-
-Adapt a defensive programming mindset: your app should always fail gracefully and informatively (e.g. provide users with a helpful error message)
+
+Adapt a defensive programming mindset: your app should always fail gracefully and informatively (e.g. provide users with a helpful error message)
-
-Build a self-explanatory app: consider the following three suggestions for doing so – (a) remember the rule of least surprise (in UI design, always do the least surprising thing e.g. we often assume that underlined text is clickable, so if you include underlined text in your UI, there’s a good chance a user will try clicking on it). (b) think about progression (design a clear pattern of moving forward for your user), and (c) related to b, make sure that if an input is necessary, it is made clear to your user. Check out the {shinyjs} package for implementing nifty ways to improve the user experience of your shiny apps.
+
+Build a self-explanatory app: consider the following three suggestions for doing so – (a) remember the rule of least surprise (in UI design, always do the least surprising thing e.g. we often assume that underlined text is clickable, so if you include underlined text in your UI, there’s a good chance a user will try clicking on it). (b) think about progression (design a clear pattern of moving forward for your user), and (c) related to b, make sure that if an input is necessary, it is made clear to your user. Check out the {shinyjs} package for implementing nifty ways to improve the user experience of your shiny apps.
-
-Avoid feature-creep: feature-creep is the process of adding features to an app that complicates its usage and maintenance – this includes adding too much reactivity and too much interactivity (e.g. plotly) – interactivity adds visual noise, so it’s best to not make elements interactive if there is no value is gained.
+
+Avoid feature-creep: feature-creep is the process of adding features to an app that complicates its usage and maintenance – this includes adding too much reactivity and too much interactivity (e.g. plotly) – interactivity adds visual noise, so it’s best to not make elements interactive if there is no value is gained.
-Web accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities can use them. More specifically, people can:
+
+Web accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities can use them. More specifically, people can:
-
- perceive, understand, navigate, and interact with the Web
+
+ perceive, understand, navigate, and interact with the Web
-
- contribute to the Web
+
+ contribute to the Web
-
-Web accessibility encompasses all disabilities that affect access to the Web, including: auditory, cognitive, neurological, physical, speech, and visual
+
+ Web accessibility encompasses all disabilities that affect access to the Web, including: auditory, cognitive, neurological, physical, speech, and visual
-
-Web accessibility also benefits people without disabilities, for example:
+
+ Web accessibility also benefits people without disabilities, for example:
-
- people using mobile phones, smart watches, smart TVs, and other devices with small screens, different input modes, etc.
+
+ people using mobile phones, smart watches, smart TVs, and other devices with small screens, different input modes, etc.
-
- older people with changing abilities due to ageing
+
+ older people with changing abilities due to ageing
-
- people with “temporary disabilities” such as a broken arm or lost glasses
+
+ people with “temporary disabilities” such as a broken arm or lost glasses
-
- people with “situational limitations” such as in bright sunlight or in an environment where they cannot listen to audio
+
+ people with “situational limitations” such as in bright sunlight or in an environment where they cannot listen to audio
-
- people using a slow Internet connection, or who have limited or expensive bandwidth
+
+ people using a slow Internet connection, or who have limited or expensive bandwidth
-
+
Check out the A11Y Project for lots of great tutorials and information about web accessibility.
-
-Small changes can lead to tangible increases in functionality for all users
-
+
Small changes can lead to tangible increases in functionality for all users
+
Ensuring that your shiny apps are accessible can feel overwhelming – but considering even a few small changes can have a large impact on user experience.
@@ -7579,21 +7553,17 @@
-
- Use HTML elements appropriately (e.g. consider hierarchy)
+
+ Use HTML elements appropriately (e.g. consider hierarchy)
-
- Include alt text for graphical elements
+
+ Include alt text for graphical elements
-
- Consider navigation from a mobility perspective
+
Screen readers use HTML elements to understand web page organization. Header elements create hierarchy within a webpage and are used by screen readers (i.e. devices used by those with visual impairments) to understand a page’s organizational structure. An <h1> element is more important (hierarchically speaking) than an <h2>, which is more important than an <h3>, and so on.
@@ -7647,24 +7616,23 @@
-
+
Ideally, you would only have one <h1> element (e.g. your app’s title), a small number of <h2> elements, more <h3> elements, and so on. See the minimal example, to the left.
-
+
You should not rely on headers for styling purposes – for example, you should not use a level-one header elsewhere in your app just because you want larger text. Instead, use CSS to increase text size (refer to the Customizing Quarto Websites workshop for instruction on how to construct CSS selectors for styling HTML elements).
-
-Include alt text with all graphical elements
-
+
Include alt text with all graphical elements
+
All images and graphical elements should include alternative (alt) text that describe the image and/or information being represented. This text won’t appear in the UI, but is detected and read by screen readers.
-
+
Include the alt argument (similar to adding the alt attribute to an HTML element) when using renderPlot() to add alt text to your reactive plots – the alt argument lives outside of the {} but inside the (). For example:
@@ -7680,7 +7648,7 @@
-
+
Similarly, use the alt argument within tags$img when adding static images to your app. For example:
@@ -7691,9 +7659,8 @@
-
-Tips on writing alt text for data visualizations
-
+
Tips on writing alt text for data visualizations
+
A good rule of thumb for writing alt text for data visualizations is alt=“Chart type of type of data where reason for including chart” (see this post by Amy Cesal for more). One example:
@@ -7703,23 +7670,22 @@
alt=“Bar chart of gun murders per 100,000 people where America’s murder rate is 6 times worse than Canada, and 30 times Australia”
-
+
For more great tips on how and when to use alt text, check out this article by the A11Y Project. For examples of how to construct good alt text, take a peek at this resource by Datawrapper.
-
-Consider UI navigation for those with mobility impairments
-
-
+
Consider UI navigation for those with mobility impairments
+
+
For users with mobility impairments, using a mouse to navigate a UI packed with widgets may be challenging – some users may even be exclusively using a keyboard to navigate the web.
-
+
Ideally, actions required of your user can be done using a keyboard (e.g. pressing a button in the UI) – however from a new shiny developer standpoint, this may be technically challenging to implement (the authors of Engineering Production-Grade Shiny Apps suggest the {nter} package for building shiny action buttons that can be triggered by pressing enter, however, at the time of building this workshop, the package source code hadn’t been updated since 2019).
-
+
At a minimum, consider spacing out and/or limiting the number of widgets on any given page to make navigation with a mouse as easy as possible.
@@ -7731,13 +7697,12 @@
-
-Use colorblind-friendly palettes
-
-
+
Use colorblind-friendly palettes
+
+
About 1 in 12 males and 1 in 200 females have some form of colorblindness (Wikipedia). Ensuring that your color choices are distinguishable from one another and/or providing an additional non-color-based way (e.g. patterns, shapes) of distinguishing between treatments/variables/etc. can greatly help with interpretation of data visualizations.
-
+
There are lots of great colorblind-accessible palettes and resources (check out this one by Alex Phillips to start). Google Chrome also has a built-in vision deficiency emulator (see gif, below right; right click in your web browser > Inspect > Rendering (add tab by clicking on the three stacked dots if it’s not already open) > scroll down and choose emulation type from drop down where it says “Emulate vision deficiencies”).
@@ -7746,7 +7711,7 @@
-
+
Four different forms of colorblindness. Image Source: Venngage
@@ -7757,101 +7722,83 @@
-
+
Using Google Chrome’s vision deficiency emulator to view webpages as seen by those with vision deficiencies
-
- Part 5: Debugging & testing
-
-
-
- Debugging approaches
+
Part 5: Debugging & testing
+
+
+ Debugging approaches
-
- Testing apps
+
+ Testing apps
- Debugging
+ Debugging
Like any code, you’re bound to run into errors as you’re developing your shiny app(s). However, Shiny can be particularly challenging to debug. In this section, we’ll review a few approaches for solving pesky issues.
-
- Learning Objectives - Debugging
-
-
+
Learning Objectives - Debugging
+
+
After this section, you should:
-
- understand some of the challenges associated with debugging shiny applications
+
+ understand some of the challenges associated with debugging shiny applications
-
- be introduced to a few approaches and tools for debugging shiny applications, including using diagnostic messages and the reactlog package.
+
+ be introduced to a few approaches and tools for debugging shiny applications, including using diagnostic messages and the reactlog package.
Shiny apps can be particularly challenging to debug for a few reasons:
-
- Shiny is reactive, so code execution isn’t as linear as other code that you’re likely more familiar with (e.g. analytical pipelines written in “normal” R scripts, where each line of code is executed in succession)
+
+ Shiny is reactive, so code execution isn’t as linear as other code that you’re likely more familiar with (e.g. analytical pipelines written in “normal” R scripts, where each line of code is executed in succession)
-
- Shiny code runs behind a web server and the Shiny framework itself, which can obscure what’s going on
+
+ Shiny code runs behind a web server and the Shiny framework itself, which can obscure what’s going on
While there are a number of different tools/strategies for debugging Shiny apps, I find myself turning to one (or more) of these approaches most often:
-
- isolating pesky errors (typos, missing commas, unmatched parentheses) in the UI by commenting out code from the outside in
+
+ isolating pesky errors (typos, missing commas, unmatched parentheses) in the UI by commenting out code from the outside in
-
- reducing your app to just problematic code by commenting out as much correctly-functioning code as possible
+
+ reducing your app to just problematic code by commenting out as much correctly-functioning code as possible
-
- adding diagnostic messages to my reactives
+
+ adding diagnostic messages to my reactives
-
- using reactlog to visualize reactivity errors
+
+ using reactlog to visualize reactivity errors
@@ -7860,19 +7807,18 @@
-
-Track down pesky UI errors by commenting out code from the outside in
-
-
+
Track down pesky UI errors by commenting out code from the outside in
+
+
Many of us experienced the frustrations of finding unmatched parentheses, typos, missing commas, etc. when building out our UI layout for App #2, and tracking down the issue can require some patience and persistence.
-
+
My preferred approach for troubleshooting a situation like this is to comment out all code moving from the highest-level layout function (e.g. navbarPage()) inwards, re-running your app each time you un-comment the next little bit of code, until you find the place where your app breaks.
-
+
For example, if I were to trouble shoot the UI for App #2, I’d comment out everything except ui <- navbarPage(title = "LTER Animal Data Explorer" and the ending ) # END navbarPage, then run my app to make sure an empty app with a gray navbar and title at the top appears. It does? Great. Next, un-comment the two tabPanel()s that create the “About this App” and “Explore the Data” pages. Works? Add a little bit more back in now, and continue this process. I like to un-comment/re-run all layout function code first, then begin adding back the inputs and outputs one by one. See a short, but incomplete demo to the right:
@@ -7883,64 +7829,60 @@
-
+
Ultimately, taking your time, adding lots of code comments to mark the ending parentheses of each function, and leaving space between lines of code so that you can more easily see what’s going on will save you lots of headache!
-
-What about “larger” errors?
-
-
+
What about “larger” errors?
+
+
Oftentimes, you’ll need to identify larger, more complex errors, like why an output isn’t rendering correctly or even appearing in your app at all.
-
+
I often turn to two strategies:
-
+
(1) commenting out everything except the UI elements and server logic where I believe the issue is stemming from, and
-
+
(2) adding diagnostic messages to my reactives
-
+
(3) …and on rare occasions, I’ll try using the {reactlog} package to help visualize my app’s reactivity in an attempt to identify the problem.
-
+
To demo these approaches, we’ll use two pre-constructed apps as examples: (1) reactlog-working (a small app that’s functioning as intended) and (2) reactlog-broken (the same small app that’s not functioning as intended).
-
-I’m building an app that should look like this…
-
-
+
I’m building an app that should look like this…
+
+
In Tab 1, both the image and text should update whenever a new radio button is chosen. In Tab 2, the scatterplot should update so that only data points for penguins with body masses within our chosen range are displayed. Find the source code for this functioning app here.
-
-…but let’s say it actually looks like this:
-
-
+
…but let’s say it actually looks like this:
+
+
In Tab 1, only the image updates whenever a new radio button is chosen, and text is missing altogether. In Tab 2, the scatterplot updates as expected whenever the body mass range is changed. Find the source code for this buggy app here.
-
-Start by commenting out functioning code
-
-
+
Start by commenting out functioning code
+
+
Even though this is a relatively small/simple app, there is still code that, for lack of a better term, gets in the way. After a quick assessment, my reactive scatterplot on Tab 2 appears to be working as expected. To help simplify the amount of code I need to look at, I’ll start by commenting out all UI elements (sliderInput & plotOutput) and server logic for building that reactive plot.
-
+
Note: As you begin building more complex apps, you may have reactives that depend on other reactives – it’s important to think about these dependencies when commenting out parts of your app for debugging purposes.
@@ -8073,10 +8015,9 @@
-
-Next, add messages to your reactives
-
-
+
Next, add messages to your reactives
+
+
You can insert diagnostic messages within your reactives using message() – here, I add a short message where each text and image output should be rendered. I can run my app and see messages successfully (or in the case of a broken app, unsuccessfully) print in my RStudio console as I interact with the app. You’ll notice that the each image message (e.g. “Displaying all penguins image”) prints when a new radioButton is selected, but those associated with the text outputs do not. This tells me that code is not being executed, beginning with first if statement inside renderText and that this is a good starting location for reviewing code (e.g. carefully crosschecking all inputIds and outputIds in that section).
@@ -8217,16 +8158,15 @@
-
-If helpful, use reactlog to visualize reactivity
-
“A snapshot of the history (log) of all reactive interactions within a shiny application”- Barret Schloerke in his 2019 RSTUDIO::CONF talk, Reactlog 2.0: Debugging the state of Shiny
@@ -8237,89 +8177,83 @@
-
+
Reactivity can be confusing. I recommend watching Barret Schloerke’s talk, linked above, and reading through the Shiny Reactlog vignette as you get started.
reactlog should already be installed as a dependency of shiny (but be sure to import the package at the top of your script using library(reactlog)). When enabled, it provides an interactive browser-based tool to visualize reactive dependencies and executions in your app.
3. Run your app, interact with it, then quit your app
-
-4. Launch reactlog by running shiny::reactlogShow() in your console (or use the keyboard shortcut cmd/ctrl + F3)
+
+4. Launch reactlog by running shiny::reactlogShow() in your console (or use the keyboard shortcut cmd/ctrl + F3)
-
+
5. Use your <- and -> arrow keys (or and ) to move forward and backward through your app’s reactive life cycle
-
-
+
+
Read about the components of the status bar and the meaning of different reactive states in the reactlog vignette.
-
-Using reactlog to visualize reactivity in a correctly-functioning app
-
-
-To visualize the reactive life cycle of the reactlog-working app, I’ll first load the reactlog library, then call reactlog_enable() in my console. Next, I’ll run my app and interact with it. By default, All penguins is selected. For demonstration purposes, I’ll click down the list (Sassy chinstrap, Staring gentoo, and finally Adorable adelie). When done, I’ll stop my app, then run shiny::reactlogShow() in the console to open the reactlog visualizer in a browser window.
+
Using reactlog to visualize reactivity in a correctly-functioning app
+
+
+To visualize the reactive life cycle of the reactlog-working app, I’ll first load the reactlog library, then call reactlog_enable() in my console. Next, I’ll run my app and interact with it. By default, All penguins is selected. For demonstration purposes, I’ll click down the list (Sassy chinstrap, Staring gentoo, and finally Adorable adelie). When done, I’ll stop my app, then run shiny::reactlogShow() in the console to open the reactlog visualizer in a browser window.
-
+
Note: I’ve left the scatter plot on Tab 2 (and it’s related UI elements) commented out (as we practiced in the earlier few slides) for this demo – the reactlog package has many features that allow you to explore reactive dependencies across your whole app, but it can get complicated quickly. For demo purposes, we’re going to work with this “smaller” version of our app, which contains just the problematic code.
-
-
-
-
-
-Interpreting reactlog (used with our correctly-functioning app)
-
+
+
+
Interpreting reactlog (used with our correctly-functioning app)
+
There’s a lot to take when looking at the reactlog viewer, so let’s take it one step at a time:
-
+
(1) The radioButton input defaults to show the All penguins image and associated text. When we launch reactlog, our input , reactive expression , and outputs are Ready, meaning the calculated values are available (defaults in this case) and reactive elements have finished executing (i.e. the image and text is displayed). This Ready state is indicated by the green icons.
-
+
(2) I (the user) then updated the input by choosing Sassy chinstrap, invalidating (i.e. resetting) the input and thereby invalidating any dependencies – in this case both the image and text outputs. This Invalidating state is indicated by the gray icons.
-
+
(3) Once all dependencies are invalidated, the reactive elements can begin Calculating (i.e. executing) based on the new input (Sassy chinstrap). Elements are colored yellow when they are being calculated, then green when calculations are complete and the reactive element has been updated. In this example, first the image and then the text are calculated and updated.
-
+
(4) These same steps are repeated when I select the Staring gentoo, then Adorable adelieradioButtons
-
-Using reactlog to visualize reactivity in a broken app
-
-
+
Using reactlog to visualize reactivity in a broken app
+
+
Let’s try out reactlog on our intentionally broken app (reactlog-broken, where our image changes when a radioButton user input is updated, but our text doesn’t appear). As in our functioning app, the All penguins image is selected by default. For demonstration purposes, I’ll select each option moving down the list (Sassy chinstrap, Staring gentoo, Adorable adelie) before launching reactlog.
-
+
Similar to our functioning app, the default input, All penguins, and image output are Ready (green). However, in this example our text output is not a dependency of our application’s input – there’s no linkage and the text output is Invalidated (gray).
-
+
As we click down the list of radioButtons, the image output is invalidated, then updated accordingly, but the text output remains disconnected from our input.
@@ -8331,13 +8265,12 @@
-
-So what’s the issue with our app?
-
-
+
So what’s the issue with our app?
+
+
Evidence from our diagnostic messages andreactlog suggests that we should make sure that our UI and server are actually able to communicate about our desired text output. After careful inspection of our textOutput() and renderText() code, we find that a spelling error is to blame:
-
+
Our outputId in the UI is set to penguin_text:
@@ -8350,7 +8283,7 @@
)
-
+
But we call penguins_text when rendering our output in the server:
@@ -8366,79 +8299,70 @@
})}
-
+
By updating our outputId to match in both the UI and the server, we fix our app.
- Testing
+ Testing
Creating automated tests for your apps can save time and effort, ensuring that they continue working as expected.
-
- Learning Objectives for Testing
-
-
+
Learning Objectives for Testing
+
+
After this section, you should:
-
- understand some of the reasons why apps break and the benefit of having automated tests
+
+ understand some of the reasons why apps break and the benefit of having automated tests
-
- have a basic understanding of how to use the shinytest2 package to create regression tests
+
+ have a basic understanding of how to use the shinytest2 package to create regression tests
-
- know how to rerun tests
+
+ know how to rerun tests
-
+
Packages introduced:
-
-shinytest2: provides tools for creating and running automated tests on Shiny applications
+
+shinytest2: provides tools for creating and running automated tests on Shiny applications
Why test our Shiny apps?
+
It’s almost inevitable that apps will break – there are lots of reasons why this happens, but to name a few:
-
- an upgraded R package(s) has a different behavior (this includes shiny) – this is especially relevant for those apps hosted on servers, where server software (including packages) may be updated by system administrators
+
+ an upgraded R package(s) has a different behavior (this includes shiny) – this is especially relevant for those apps hosted on servers, where server software (including packages) may be updated by system administrators
-
- you make changes to your app
+
+ you make changes to your app
-
- an external data source stops working or returns data in a different format than expected by your app
+
+ an external data source stops working or returns data in a different format than expected by your app
The {shinytest2} package is a useful tool for conducting regression testing on shiny apps – or in other words, testing existing app behavior for consistency over time.
@@ -8459,7 +8382,7 @@
From the shinytest2 documentation:
-
+
“shinytest2 uses testthat’s snapshot-based testing strategy. The first time it runs a set of tests for an application, it performs some scripted interactions with the app and takes one or more snapshots of the application’s state. These snapshots are saved to disk so that future runs of the tests can compare their results to them.”
@@ -8470,13 +8393,12 @@
-
+
Rather than having to write tests by hand, you can interact with your app via the “app recorder” and shinytest2 will record the test code automatically for you. Simply rerun tests to check for consistency.
-Shiny testing overview, by Winston Chang – this article discussed the shinytest2 predecessor, shinytest (which is now entering maintenance mode), but provides some helpful context and is worth a read
+
+Shiny testing overview, by Winston Chang – this article discussed the shinytest2 predecessor, shinytest (which is now entering maintenance mode), but provides some helpful context and is worth a read
-
-Let’s test the following app
-
+
Let’s test the following app
+
This small app accepts a text input for users to type their name. When the “Greet” button is pressed, the app returns a short greeting message that says, “Hello name!
-To get started, create a subdirectory called /testing_app, add a file named app.R, and drop this code in your file. Take a moment to try out the app.
+To get started, create a subdirectory called ~/testing_app, add a file named app.R, and drop this code in your file. Take a moment to try out the app.
(1) Run record_test(<app-directory>) to launch the app recorder in browser window
-
+
(2) Interact with your application and tell the recorder to make an expectation (e.g. an expected value when inputX is updated) on the state at various points
-
+
(3) Quit the recorder to save and execute your tests
@@ -8555,23 +8477,22 @@
To test our app specifically, we’ll do the following:
-
+
(1) run shinytest2::record_test("testing_app") in the console to launch the recorder in a browser window
-
+
(2) interact with your app by first typing a name (e.g. Sam), then pressing the “Greet” button to display the output text
-
+
(3) click the “Expect Shiny values” button in the recorder app sidebar to set an expectation (this will record inputs, outputs, and exported values)
-
+
(4) give your test a name in the recorder app sidebar, then click “Save test and exit” - this will save the recorded test and setup the testing infrastructure, if it doesn’t exit already
-
-Creating our first test
-
+
Creating our first test
+
Following the steps on the previous slide, creating your test should look similar to this:
@@ -8582,9 +8503,8 @@
Note: Your test is automatically run as soon as you save and exit the recorder. See the results of your test in your console (it should pass!).
-
-Test files are generated automatically
-
+
Test files are generated automatically
+
After recording your first test, a /tests folder is generated, containing a number of different files and subdirectories. Some important files to note:
@@ -8597,7 +8517,7 @@
-
+
(located at <app-directory>/tests/testthat/setup-shinytest2.R); For more complex apps, you’ll often have support files (e.g. those contained in <app-directory>/R and/or global.R) – content from those files will be stored here so that it is made accessible to your test(s). Since we don’t have any support files for our rather small/somewhat simple app, you should only see the following:
@@ -8606,7 +8526,7 @@
-
+
(located at <app-directory>/tests/testthat/test-shinytest2.R); This test script contains your recorded test, and should automatically open when you finish recording and save your test. You can manually modify this test (e.g. add additional interactions and expectations), if you wish. Yours should look similar to this:
@@ -8621,7 +8541,7 @@
-
+
(located at <app-directory>/tests/testthat/_snaps/shinytest2/*_.png); This is a screenshot of your app from when app$expect_values() was called – this file should be tracked using git so that you know how your app visually changes over time. My .png file looks like this:
@@ -8629,7 +8549,7 @@
-
+
(located at <app-directory>/tests/testthat/_snaps/shinytest2/*.json); This is a JSON representation of the state of the app when app$expect_values() was called – you’ll see the state of all input, output, and export values at the time of the snapshot (we don’t have any exports in our example app, but we do have a name input and a greeting output). This file should be tracked with git so that you have a record of your expected results. Your .json file should look something like this:
@@ -8650,116 +8570,95 @@
-
-Tips for testing
-
+
Tips for testing
+
- Record subsequent tests following the same workflow, giving each a unique name. Run test_app("path/to/app") to run all test scripts in your app’s tests/testhat directory.
+ Record subsequent tests following the same workflow, giving each a unique name. Run test_app("path/to/app") to run all test scripts in your app’s tests/testhat directory.
- Use record_test() fairly often – Barret Schloerke argues that you should make a test recording for each feature of your app (many little recordings are encouraged!)
+ Use record_test() fairly often – Barret Schloerke argues that you should make a test recording for each feature of your app (many little recordings are encouraged!)
- Limit testing to objects under your control. For example, let’s say you have a reactive data frame that you then send to a DT::datatable – if package maintainers update the DT package, your output might change which could lead to false positive failed tests. Instead, test just your data frame that gets sent to DT.
+ Limit testing to objects under your control. For example, let’s say you have a reactive data frame that you then send to a DT::datatable – if package maintainers update the DT package, your output might change which could lead to false positive failed tests. Instead, test just your data frame that gets sent to DT.
-
+
This is only a brief intro to shinytest2! Dig into the documentation to learn more.
-
- Part 6: Streamlining code
-
-
-
- Writing functions
+
Part 6: Streamlining code
+
+
+ Writing functions
-
- Shiny modules
+
+ Shiny modules
- Writing functions
+ Writing functions
Functions have many benefits and can improve your code base, particularly as your app grows in complexity
-
- Learning Objectives - Functions
-
-
+
Learning Objectives - Functions
+
+
By the end of this section, you should:
-
- understand the benefits of turning UI elements and server logic into functions
+
+ understand the benefits of turning UI elements and server logic into functions
-
- know where to write/save your functions
+
+ know where to write/save your functions
-
- successfully turn a repeated input into a function
+
+ successfully turn a repeated input into a function
-
- successfully turn a piece of server logic into a function
+
+ successfully turn a piece of server logic into a function
-
-
-Why write functions
-
+
+
Why write functions
+
Functions are useful for a wide variety of reasons. Most notably:
-
- reducing redundancy
+
+ reducing redundancy
-
- reducing complexity
+
+ reducing complexity
-
- increasing code comprehension
+
+ increasing code comprehension
-
- increasing testability
+
+ increasing testability
Importantly, functions can live outside of your app file(s) (i.e. app.R or ui.R, server.R and global.R), helping you to break up/streamline your code. Hadley Wickham recommends creating a folder called /Rinside your app’s directory (e.g. ~/app-directory/R/...) and:
-
+
(a) storing larger functions in their own files (e.g. ~/app-directory/R/{function-name}.R) and/or
-
+
(b) creating a utils.R file (e.g ~/app-directory/R/utils.R) to store smaller, simpler functions all in one script.
@@ -8767,11 +8666,10 @@
-
-Create a small app for function practice
-
-
-Create a new subdirectory called functions-app/ and add your ui.R, server.R, and global.R files with the following code. Run your app to see how it functions.
+
Create a small app for function practice
+
+
+Create a new subdirectory called ~/functions-app and add your ui.R, server.R, and global.R files with the following code. Run your app to see how it functions.
-Write a function for adding a pickerInput to select for penguin species
-
+
+
Write a function for adding a pickerInput to select for penguin species
+
+
This app includes two pickerInputs, both of which allow users to select which penguin species to display data for. The only difference between both pickerInputs is the inputId. Let’s write a function for our penguin species pickerInput that we can use in place of these two, rather long, chunks of code.
-
+
First, create an /R folder inside your functions-app directory. Then, add a new script to this folder. I’m calling mine penguinSpp_pickerInput.R.
-
+
Since the only difference between our original two pickerInputs are their inputIds, we can write a function that takes inputId as an argument (Recall that inputIds must be unique within an app, so it makes sense that both of our pickerInputs have different inputIds).
-
+
Once written, source() your function script into global.R (if necessary) to make your function available for use in your app.
Finally, replace your original UI code for building both pickerInputs with our penguinSpp_pickerInput() function, save, and run your app. It should look exactly the same as before!
-We reduced code redundancy and increased readability!
+
+
We reduced code redundancy and increased readability!
+
By turning our pickerInput code into a function, we not only reduced ten lines of UI code into two, but we also made our UI code a bit easier to read – our function, penguinSpp_pickerInput() tells a reader/collaborator/future you exactly what that line of code is meant to do, which is create a pickerInput that allows users to select penguin species. Even without code comments or additional context, one may deduce what that line of code does.
-
-Turn reactives & rendered outputs into functions
-
-
+
Turn reactives & rendered outputs into functions
+
+
Next, let’s see where we can streamline our server code using functions. We have two discrete sections of code – (1) a reactive data frame and scatterplot output and (2) a reactive data frame and histogram output.
-
server <-function(input, output) {
+
+
+
~/functions-app/server.R
+
+
server <-function(input, output) {# filter penguin species (scatterplot) ---- filtered_spp_scatterplot <-reactive ({
@@ -9100,55 +9032,66 @@
} # END server
-
-
-Create a function to builds our scatterplot
-
-First, create a new file in ~/function-app/R and name it build_penguin_histogram.R (or a name that is succinct/clear – I’m going to name my function similarly).
+
+
Create a function to build our scatterplot
+
+
+First, create a new file in ~/function-app/R and name it build-penguin-scatterplot.R (or a name that is succinct/clear – I’m going to name my function similarly).
-
-The goal of my function is to filter the penguins data based on the user input and render our ggplot scatterplot. To start, I’m going to cut/paste both the code to generate the reactive filtered_spp_histogram data frame and the renderPlot() code from server.R into our build_penguin_histogram() function.
+
+The goal of my function is to filter the penguins data based on the user input and render our ggplot scatterplot. To start, I’m going to cut/paste both the code to generate the reactive filtered_spp_scatterplot data frame and the renderPlot() code from server.R into our build_penguin_scatterplot() function.
-
+
Important: In isolation, our function does not know about the user input (input is not in our global environment, it’s only known within the server() function). Therefore, we must pass input as an argument to our function.
-
-Note that in R, functions return the last executed line – when we run build_penguin_histogram() in our server, it will return the object created by renderPlot().
+
+Note that in R, functions return the last executed line – when we run build_penguin_scatterplot() in our server, it will return the object created by renderPlot().
Remember, the output of build_penguin_scatterplot() is renderPlot(), which is used to build our reactive scatterplot. Following our rules for creating reactivity, we need to save our function’s output to output$penguin_scatterplot. In doing so, we reduced 23 lines of code to 1 inside our server function.
+
+
+
~/functions-app/server.R
+
server <-function(input, output) {# filter data & create penguin scatterplot ----
@@ -9177,21 +9120,25 @@
} # END server
-
-
-Build a function to create our histogram
-
+
+
Build a function to create our histogram
+
+
We can repeat a similar process to create a function for building our histogram:
server <-function(input, output) {# filter data & create penguin scatterplot ----
@@ -9232,71 +9184,66 @@
+
- Writing modules
+ Writing modules
We can take our code abstraction a step further and bundle repeated UI & server components together into modules, streamlining our code and increasing efficiency.
-
- Learning Objectives - Modules
-
-
+
Learning Objectives - Modules
+
+
By the end of this section, you should have an intro-level understanding of:
-
- what is a shiny module and when it might make sense to build one
+
+ what is a shiny module and when it might make sense to build one
-The utility of modules is best demonstrated by taking a look at an example app
-
-
+
The utility of modules is best demonstrated by taking a look at an example app
+
+
This app, developed by Garrett Grolemund & Joe Cheng’s as part of their Modules lesson, taught at the 2016 Shiny Developer Conference, is a prime candidate for modularization.
-
+
It uses the gapminder data set to display life expectancy by GDP per capita from 1952 to 2007 for Africa, the Americas, Asia, Europe, Oceania, and all regions collectively. The only difference between each tab is the subset of data displayed.
-
-
-
-
-
-The code for this app isn’t particularly complex, but it’s repetitive and long
-
+
+
+
The code for this app isn’t particularly complex, but it’s repetitive and long
+
+
+
+
~/modularized-app/app.R
+
# app.R#..............................setup.............................
@@ -9620,16 +9567,15 @@
# Run the application shinyApp(ui = ui, server = server)
-
-
-Repeated code sections
-
+
+
Repeated code sections
+
+
Taking a closer look at the gapminder app code, we’ll see that the following sections of code are repeated for each region (6 times total; only code sections for “all” regions shown below):
-
-tabPanel (UI)
+
+tabPanel (UI)
# "All" tabPanel (repeated 5 more times for each subregion)
@@ -9639,9 +9585,8 @@
value =1952, min =1952, max =2007, step =5, animate =animationOptions(interval =500)))
-
- reactive data frame (server)
+
+ reactive data frame (server)
# "All" reactive data frame (repeated 5 more times for each subregion)
@@ -9649,9 +9594,8 @@
filter(all_data, year == input$all_year)})
-
- reactive data frame (server)
+
+ reactive data frame (server)
# "All" reactive data frame (repeated 5 more times for each subregion)
@@ -9659,9 +9603,8 @@
filter(all_data, year == input$all_year)})
-
- calculating date ranges (server)
+
+ calculating date ranges (server)
# "All" date range (repeated 5 more times for each subregion)
@@ -9669,12 +9612,10 @@
yrange_all <-range(all_data$lifeExp)
-
-Repeated code sections (cont.)
-
-
-renderPlot({}) (server)
+
Repeated code sections (cont.)
+
+
+renderPlot({}) (server)
# "All" plot (repeated 5 more times for each subregion)
@@ -9710,62 +9651,60 @@
})
-
-Enter Shiny modules
-
+
Enter Shiny modules
+
-A shiny module is a piece of a shiny app – it can’t be run directly, but instead is included as part of a larger app. While functions work well for code that that is either completely on the client (UI) side or completely on the server side, modules can be written for code that spans both.
+A shiny module is a piece of a shiny app – it can’t be run directly, but instead is included as part of a larger app. While functions work well for code that that is either completely on the client (UI) side or completely on the server side, modules can be written for code that spans both.
-Modules can represent inputs, outputs, or both (we’ll be building a module that represents both). Motivation for building modules can range from enabling reuse of code (once created, modules can be reused within the same app or even across different apps), to breaking up a large, complex app into smaller, separate components.
+Modules can represent inputs, outputs, or both (we’ll be building a module that represents both). Motivation for building modules can range from enabling reuse of code (once created, modules can be reused within the same app or even across different apps), to breaking up a large, complex app into smaller, separate components.
-Modules help to solve a namespacing problem – recall that all Ids (e.g. inputIds) must be unique across your app. Namespacing is a system for organizing objects with identical names (similar to namespacing functions from particular packages using the syntax package::function() e.g. plyr::arrange() vs dplyr::arrange()).
+Modules help to solve a namespacing problem – recall that all Ids (e.g. inputIds) must be unique across your app. Namespacing is a system for organizing objects with identical names (similar to namespacing functions from particular packages using the syntax package::function() e.g. plyr::arrange() vs dplyr::arrange()).
-
-What do modules look like?
-
+
What do modules look like?
+
Modules are a coding pattern, organized into two functions: one that creates the UI elements and one that loads the server logic. They can look a bit different, depending on your module, but they generally follow this pattern:
-
# myModule.R
-#..........................ui function...........................
-
-myModuleUI <-function(id) {
-
- ns <-NS(id)
-
-tagList(
-# inputs with ids wrapped in ns() (e.g. `sliderInput(id = ns("slider"))`)
-# outputs with ids wrapped in ns() (e.g. `plotOutput(id = "ns(plot"))`)
- )
-
-}
-
-#........................server function.........................
-myModuleServer <-function(id, ...) { # where `...` includes any number of additional parameters
-
-moduleServer(id, function(input, output, session) {
-
-# server logic
-
- })
-
-}
+
+
+
myModule.R
+
+
#..........................ui function...........................
+
+myModuleUI <-function(id) {
+
+ ns <-NS(id)
+
+tagList(
+# inputs with ids wrapped in ns() (e.g. `sliderInput(id = ns("slider"))`)
+# outputs with ids wrapped in ns() (e.g. `plotOutput(id = "ns(plot"))`)
+ )
+
+}
+
+#........................server function.........................
+myModuleServer <-function(id, ...) { # where `...` includes any number of additional parameters
+
+moduleServer(id, function(input, output, session) {
+
+# server logic
+
+ })
+
+}
-
-
-Where should I define/save my module?
+
+
Where should I define/save my module?
+
Part of the appeal of creating modules is breaking your long app.R (or ui.R & server.R) scripts into smaller pieces. Creating a separate R script to house a given module (both the UI and Server function components) is typically the best course of action (a good naming convention is giving it a descriptive name with the suffix “Module” e.g. gapModule.R). There are a variety of places you can write and/or save your modularized code to, but I recommend one of the following two options (at least while we’re just getting started on our shiny modules journey):
@@ -9773,7 +9712,7 @@
(1) save your modularized code script inside your app’s directory (e.g. ~/app-directory/myModule.R)
-
+
If you choose this option, call source("myModule.R") from global.R (if using ui.R/server.R) or app.R.
@@ -9781,21 +9720,24 @@
(2) save your modularized code script inside the /R subdirectory of your application (e.g. ~/app-directory/R/myModule.R)
-
+
If you choose this option, your module will automatically be sourced (as of Shiny 1.5.0) when the application is loaded.
-
-Breaking down the UI function:
-
-
+
Breaking down the UI function:
+
+
The UI part of a module needs to do two things: (1) return a shiny element (e.g. an input & output), and (2) assign module elements to a unique namespace using NS(). NS() provides an easy way to help with namespacing within your module, ensuring that each time your module is called, a unique id is assigned.
-
+
The UI function for our gapminder module will look like this (NOTE: code comments below denote the general order of operations I followed when writing this UI function):
+
+
+
~/modularized-app/R/gapModule.R
+
# step 1: a good function naming convention is a descriptive base name, suffixed by `UI`gapModuleUI <-function(id) { # step 2: the first argument to a UI function should always be `id` -- this is the namespace for the module
@@ -9814,20 +9756,24 @@
} # END gapModuleUI function
-
+
+
Wrapping our input and output Ids in ns() will create unique Ids each time our module is called, preventing things from overwriting one one another. For example, if we call gapModuleUI(id = "myFirstModuleCall"), our outputId will be set to myFirstModuleCall-plot and our inputId will be set to myFirstModuleCall-year. Calling our module a second time (e.g. gapModuleUI(id = "mySecondModuleCall")) will generate two new unique Ids (e.g. mySecondModuleCall-plot & mySecondModuleCall-year).
-
-Breaking down the Server function:
-
-
+
Breaking down the Server function:
+
+
The server part of a module looks very similar to a normal (i.e. non-modular) Shiny app server function. Begin by defining your module server function name and provide it with the first required parameter, id, along with any other necessary parameters (we also need to pass our particular function a data parameter to differentiate between data subsets (e.g. All vs. Africa vs. Asia etc.)).
-
+
Next, call moduleServer()inside your server function and pass it the id variable, along with the module function. The module function must have three parameters: input, output, and session. You do not have to use ns() to refer to inputs and outputs here. Copy server code from our original app, plop it inside the module function, and sub in our data parameter where ever a data frame subset is called.
+
+
+
~/modularized-app/R/gapModule.R
+
# step 1: a good function naming convention is a descriptive base name, suffixed by `Server`gapModuleServer <-function(id, data) { # step 2: the first argument to a server function should always be `id`, followed by any other necessary arguments; here we include a 'data' parameter, since we need to be able to tell our server function which data subset to plot in each tab
@@ -9880,14 +9826,18 @@
} # END server function
-
-
-Now let’s use our module:
-
+
+
Now let’s use our module:
+
+
First, since we’ve saved our gapModule.R file to our app’s directory, we’ll need to source it at the top of our app.R file:
Next, let’s use our module’s UI function. We’ll need to define/name each of our tabPanels (one for each of our six regions), but rather than building a plotOutput and sliderInput inside each tabPanel (each with unique Ids), we can instead call our gapModuleUI() function, and ensure that each time we call it to supply a unique character string for our id parameter.
+
+
+
~/modularized-app/app.R
+
#..............................setup.............................library(shiny)library(gapminder)
@@ -9946,14 +9900,18 @@
) # END fluidPage
-
-
-Now let’s use our module:
-
+
+
Now let’s use our module:
+
+
Finally, we can re-write our server. Rather than writing out the lengthy code required to make each plot six times over, we can instead call our gapModuleServer() function, supplying each call with ids that match those used in gapModuleUI(), along with the appropriate data subset. Now, run your app! If written correctly, your app should run exactly the same as your initial version.
+
+
+
~/modularized-app/app.R
+
#..............................setup.............................library(shiny)library(gapminder)
@@ -10004,214 +9962,171 @@
# Run the application shinyApp(ui = ui, server = server)
-
-
-Additional module resources
+
+
Additional module resources
+
We’ve barely scratched the surface of modules. Continue on with some of the following resources:
-
-Modularizing Shiny App Code & associated materials, by Garrett Grolemund & Joe Cheng at the 2016 Shiny Developer’s Conference – NOTE: This 2016 talk is an excellent introduction to modules and is definitely worth a watch, especially because we just explored the exact example demoed by G. Grolemund. Please note, however, that Shiny modules were overhauled in 2020 with the introduction of moduleServer(). The code on the previous slides has been updated to reflect those changes, and therefore differs slightly from what’s taught in this video.
+
+Modularizing Shiny App Code & associated materials, by Garrett Grolemund & Joe Cheng at the 2016 Shiny Developer’s Conference – NOTE: This 2016 talk is an excellent introduction to modules and is definitely worth a watch, especially because we just explored the exact example demoed by G. Grolemund. Please note, however, that Shiny modules were overhauled in 2020 with the introduction of moduleServer(). The code on the previous slides has been updated to reflect those changes, and therefore differs slightly from what’s taught in this video.
- Consider if you need Shiny at all
+ Consider if you need Shiny at all
While a well-developed shiny app is fun and appealing, it’s worth having a conversation about whether shiny is truly necessary, or if taking an alternative approach to sharing your data might be better.
-
-Additional data presentation frameworks
-
-
-Shiny is awesome, but depending on your goals, vision, and end users, you may not need the full functionality that shiny provides. You can potentially save yourself (and your clients) the stress of deploying and maintaining apps by first considering other options:
+
Additional data presentation frameworks
+
+
+Shiny is awesome, but depending on your goals and end users, you may not need the full functionality that shiny provides. Importantly, you also can potentially save yourself (and your clients) the stress of deploying and maintaining shiny apps by first considering other options:
-
-
- Widgets aren’t only for Shiny! Embed interactive htmlwidgets into your R Markdown documents that range from geo-spatial mapping with leaflet to generating network graph diagrams with DiagrammeR. Check out the htmlwidgets for R - gallery for many more options.
+
+
+
+Embed interactive htmlwidgets into your R Markdown & Quarto markdown documents that range from geo-spatial mapping with leaflet to generating network graph diagrams with DiagrammeR. Check out the htmlwidgets for R - gallery for many more options.
-
- Compose multiple widgets into a dashboard using flexdashboard. Based in R Markdown, this framework allows you to produce dynamic dashboards using tools you are already familiar with. Find example projects and their source code here.
+
+Compose multiple widgets into a dashboard using flexdashboard. Based in R Markdown, this framework allows you to produce dynamic dashboards using tools you are already familiar with. Find example projects and their source code.
-
- Embed reactive shiny components (e.g. inputs & outputs) in Quarto documents. By using some fun new code chunk options, you can instruct Quarto to spin up it’s own self-contained shiny server to run your reactives. Read the Quarto documentation to learn more and check out some teaching examples here.
+
+Embed reactive shiny components (e.g. inputs & outputs) in Quarto documents. By using some fun new code chunk options, you can instruct Quarto to spin up it’s own self-contained shiny server to run your reactives. Read the Quarto documentation to learn more and check out some teaching examples.
-
-
-
-
-Example flexdashboards built by some familiar folks
-
- Final Thoughts & Additional Resources
+ Final Thoughts & Additional Resources
We’ve covered a lot in this workshop, and we’ve only just begun to scratch the surface – we’ll end with some final thoughts/words of wisdom, along with some resources that are worth returning to as you begin your deep dive into shiny app development.
-
-Some takeaway messages that are worth keeping in mind
-
-
- Oftentimes, the most time consuming part of building a shiny app is deciding on how to present the data visually – make your data visualizations first, outside of shiny, refine, decide which variables you think are important enough to make reactive, etc. THEN, build them into your shiny application.
+
Some takeaway messages that are worth keeping in mind
+
+
+ Oftentimes, the most time consuming part of building a shiny app is deciding on how to present the data visually – make your data visualizations first, outside of shiny, refine, decide which variables you think are important enough to make reactive, etc. THEN, build them into your shiny application.
-
- Get your data in the most wrangled form possible before loading it into your app to avoid unnecessary slowdowns.
+
+ Get your data in the most wrangled form possible before loading it into your app to avoid unnecessary slowdowns.
-
- Code expands quickly – stay organized! Create a repository map (see an example in this README), so you and your collaborators know where files live and what they do. Use rainbow parentheses, add extra space between sections of code, and include clear code comments to denote the start and end of parentheses. This will help save headaches later on.
+
+ Code expands quickly – stay organized! Create a repository map (see an example in this README), so you and your collaborators know where files live and what they do. Use rainbow parentheses, add extra space between sections of code, and include clear code comments to denote the start and end of parentheses. This will help save headaches later on.
-
- Keep in mind the considerations for good UX/UI design. You’re building an app for the user first and foremost – be sure to assess often if your app is going to meet their needs.
+
+ Keep in mind the considerations for good UX/UI design. You’re building an app for the user first and foremost – be sure to assess often if your app is going to meet their needs.
-
- Before taking the plunge, consider if you really need shiny at all – maintaining apps can be challenging. What other options might you have for sharing your data with end users?
+
+ Before taking the plunge, consider if you really need shiny at all – maintaining apps can be challenging. What other options might you have for sharing your data with end users?
-
-Great Shiny resources
-
-
-A quick Google search will yield lots of online resources, forum discussions, video tutorials, etc. for building Shiny applications. Many are linked throughout these slides, but here’s an attempt at putting some of those that I referenced most often all in one spot (along with some that we didn’t have time to cover). Be sure to poke around online yourself, and let me know if you come across any that you find particularly useful so that I can add them here!
+
Great Shiny resources
+
+
+A quick Google search will yield lots of online resources, forum discussions, video tutorials, etc. for building Shiny applications. Many are linked throughout these slides, but here’s an attempt at putting some of those that I referenced most often all in one spot (along with some that we didn’t have time to cover).
-Shiny UI Editor and Nick Strayer’s rstudio::conf(2022) talk introducing it – a visual tool for building the UI portion of a Shiny application that generates clean and human-readable code (currently in Alpha, as of January 2023)
+
+Shiny UI Editor and Nick Strayer’s rstudio::conf(2022) talk introducing it – a visual tool for building the UI portion of a Shiny application that generates clean and human-readable code (currently in Alpha, as of January 2023)
-
- The {golem} package provides an opinionated framework for building production-grade shiny applications and is a part of a growing ecosystem of packages called the {golemverse}. There are lots of accompanying learning materials, including the book, Engineering Production Grade Shiny Apps, by Colin Fay, Sébastien Rochette, Vincent Guyader, and Cervan Girard.
+
+ The {golem} package provides an opinionated framework for building production-grade shiny applications and is a part of a growing ecosystem of packages called the {golemverse}. There are lots of accompanying learning materials, including the book, Engineering Production Grade Shiny Apps, by Colin Fay, Sébastien Rochette, Vincent Guyader, and Cervan Girard.
-
-And don’t forget about Posit’s own excellent resources
-
+
And don’t forget about Posit’s own excellent resources
+
Posit/RStudio’s great instructional resources, examples, and help documentation:
- The Shiny User Showcase, a collection of Shiny apps and their source code developed by the Shiny developer community – many of these featured apps are winners or honorable mentions of the annual Shiny contest!
+
+ The Shiny User Showcase, a collection of Shiny apps and their source code developed by the Shiny developer community – many of these featured apps are winners or honorable mentions of the annual Shiny contest!
-
-Shiny Demos, a series of apps created by the Shiny developers to highlight specific features of the shiny package – these are excellent resources to turn to when you are learning how to implement a new type of widget, working on the layout of your app, and more.
+
+Shiny Demos, a series of apps created by the Shiny developers to highlight specific features of the shiny package – these are excellent resources to turn to when you are learning how to implement a new type of widget, working on the layout of your app, and more.
@@ -10219,9 +10134,14 @@
I’m excited to see what Shiny new apps you all create!
-
-
-
-
-
-
-
-
. Click that button to run your app (alternatively, run 
, to see how your app will appear when viewed in your web browser.
, appear in the top right corner of your console indicating that R is busy–this is because your R session is currently acting as your Shiny app server and listening for any user interaction with your app. Because of this, you won’t be able to run any commands in the console until you quit your app. Do so by pressing the stop button.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
and 
) to move forward and backward through your app’s reactive life cycle
, reactive expression 
, and outputs 
are Ready, meaning the calculated values are available (defaults in this case) and reactive elements have finished executing (i.e. the image and text is displayed). This Ready state is indicated by the green icons.
-
-
-
+
Start by commenting out functioning code
++
Even though this is a relatively small/simple app, there is still code that, for lack of a better term, gets in the way. After a quick assessment, my reactive scatterplot on Tab 2 appears to be working as expected. To help simplify the amount of code I need to look at, I’ll start by commenting out all UI elements (
-sliderInput&plotOutput) and server logic for building that reactive plot.+
Note: As you begin building more complex apps, you may have reactives that depend on other reactives – it’s important to think about these dependencies when commenting out parts of your app for debugging purposes.