If you’re going to be writing a lot of Shiny apps (and since you’re reading this book I hope you will be!), it’s worth investing some time in your basic workflow. Improving workflow is a good place to invest time because it tends to pay great dividends in the long run. It doesn’t just increase the proportion of your time spent writing R code, but because you see the results more quickly, it makes the process of writing Shiny apps more enjoyable, and helps your skills improve more quickly.
Objectives of chapter on Workflow
The goal of this chapter is to help you improve three important Shiny workflows:
There are two main workflows to optimize here:
Every app starts with the same six lines of R code. (The repetitive usage of code is not only for Shiny important. I have developed a huge amount of code snippets for R and even more for Markdown). For instance all the (code) boxes (e.g., Resource 5.1) you see in my notes are created by inserting templates via code snippets. In the next paragraph I will type at the beginning of the line num-resources and with SHIFT-TAB my template for a numbered resource box is created. I just have to add IDs for generating internal links and the content.
:::::{.my-resource}
:::{.my-resource-header}
:::::: {#lem-resource-text}
: Numbered Resource Title
::::::
:::
::::{.my-resource-container}
Here include text for the resource
::::
:::::Resource 5.1 : Code snippets
If you want to start a new project, go to the File menu, select “New Project” then select “Shiny Web Application”.
Here I am using my “learning-shiny” book project to develop several shiny apps. Go to the File menu, select “New File”->“Shiny Web App…”. This opens up a window to name a folder where the app.R file for the Shiny app is created. The name of the folder is essential as all Shiny apps have the same file name (app.R) if you choose (as I do) a single file app.
Here in this book I am predominantly using the {shinylive} package. Therefore I have prepared another markdown snippet.
:::{.column-page}
:::::{.my-r-code}
:::{.my-r-code-header}
:::::: {#cnj-ID-text}
: Numbered R Code Title
::::::
:::
::::{.my-r-code-container}
```{shinylive-r}
#| standalone: true
#| viewerHeight: 300
#| components: [editor, viewer]
#| layout: vertical
library(shiny)
start coding here
```
::::
:::::
:::I knew about the shortcut CMD-SHIFT-ENTER for running the current code chunk. I didn’t know that the same shortcut could be used for the shiny app. But it is a sensible generalization. What else is a shiny app as one (big) code chunk?
I didn’t know nothing about background jobs except that it is invoked by rendering the Quarto file. Actually I don’t know if it is still necessary to invoke the procedure described in Shiny apps in background jobs. The reason is that Shiny will run in the background if I enter the shortcut CMD-SHIFT-ENTER inside the Shiny app script.
There is some small change about the workflow as described in the section “Seeing your changes” in chapter 5 of the website of the Mastering Shiny book. Instead of “Write some code and press Cmd/Ctrl + S to save the file.” it works for me with “Write some code and press Cmd/Ctrl-Shift-Enter to save and run the reloaded changed file.”
Procedure 5.1 : Shiny background job
The chief disadvantage of this technique is that it’s considerably harder to debug because the app is running in a separate process.
But the general procedure to start background jobs inside the RStudio environment is very valuable for me. I could use background workflows with lengthy rendering procedures of my Quarto note books.
Resource 5.2 : Background jobs in the RStudio IDE
To call the procedure in Procedure 5.1 you have to tick the option “In Background Job” in the “Run App”-button (see Screenshot 5.2). (You see this window only in inside the script of the Shiny app.)
There are three options (see Screenshot 5.2):
With an external browser window there are is one observation I made: If you shut down the background job or restart R then the browser window is invalidated and running the app again will open a new tab in your browser. This is contrast to rendering a Quarto document showing in an external browser window. Closing this window will not show the new results in a new browser window. You have to restart R, then RStudio will open a new browser window after the rendering process is finished.
There are three main cases of problems which we’ll discuss below:
I am relatively unexperienced with R debugging. So I started with the Jenny Bryan’s talk. What follows is short summary of the talk:
Procedure 5.2 : General debugging procedures following the Jenny Brian video lecture
There are three general procedures:
back::traceback(), last_trace::rlang() is like reading a death certificate. back::traceback() is to be read from bottom to top; last_trace::rlang() is easier to read from top to bottom and has a nested view.base::options(error = utils::recover): This is like a post-mortem autopsy. This function allows the user to browse directly on any of the currently active function calls, and is suitable as an error option. When called, recover prints the list of current calls, and prompts the user to select one of them. The standard R browser is then invoked from the corresponding environment; the user can type ordinary R language expressions to be evaluated in that environment such as: utils::ls.str().base::browser() statement (or in RStudio a break point) written into the appropriate place of the code, general at the start of a function. This is like a reanimation. Stopping debugging with Q (Alternatives are base::debug() with base::undebug(), base::debugonce() or in RStudio choose Stop Debugging from the Debug menu or type the shortcut Shift-F8).RStudio has a very handy starting debugging feature where you choose to hide the traceback or to rerun it with debug.
As debugging is intimidating Jenny Bryan recommends at the end of her talk three debugging learning strategies:
R CMD check and testthat::test_check()
Only the first tip is at the moment for me easy to apply. Of the other three strategies I have already heard, but they are at the moment in my daily work behavior with R difficult to include. I will try them out when I return to develop an R package for general use.
You can’t use traceback() in Shiny because you can’t run code while an app is running. Instead, Shiny will automatically print the traceback for you.
R Code 5.1 : Example: Traceback in {shiny}
library(shiny)
f <- function(x) g(x)
g <- function(x) h(x)
h <- function(x) x * 2
ui <- fluidPage(
selectInput("n", "N", 1:10),
plotOutput("plot")
)
server <- function(input, output, session) {
output$plot <- renderPlot({
n <- f(input$n)
plot(head(cars, n))
}, res = 96)
}
shinyApp(ui, server)The following error message is faked (copied from a live shiny app), because it does not work with {shinylive}. {shinylive} produces just the same message as inside the app:
Error: non-numeric argument to binary operator
Warning: Error in *: non-numeric argument to binary operator
178: g […/app.R#4]
177: f […/app.R#3]
176: renderPlot […/app.R#13]
174: func
134: drawPlot
120: <reactive:plotObj>
100: drawReactive
87: renderFunc
86: output$plot
1: shiny::runAppI have the first three line edited so that they do not reveal my internal directory organisation.
To understand what’s going on we again start by flipping it upside down, so you can see the sequence of calls in the order they appear:
1: shiny::runApp
86: output$plot
87: renderFunc
100: drawReactive
120: <reactive:plotObj>
134: drawPlot
174: func
176: renderPlot […/app.R#13]
177: f […/app.R#3]
178: g […/app.R#4]There are three basic parts to the call stack:
shiny::runApp(), but depending on how you start the app, you might see something more complicated. For example, if you called base::source() to run the app, you might see this:1: source
3: print.shiny.appobj
5: runAppIn general, you can ignore anything before the first runApp(); this is just the setup code to get the app running.
86: output$plot
87: renderFunc
100: drawReactive
120: <reactive:plotObj>
134: drawPlot
174: funcHere, spotting output$plot is really important — that tells which of your reactives (plot) is causing the error. The next few functions are internal, and you can ignore them.
176: renderPlot […/app.R#13]
177: f […/app.R#3]
178: g […/app.R#4]This is the code called inside of renderPlot(). You can tell you should pay attention here because of the file path and line number; this lets you know that it’s your code.
If you get an error in your app but don’t see a traceback then make sure that you’re running the app using Cmd/Ctrl + Shift + Enter (or if not in RStudio, calling runApp()), and that you’ve saved the file that you’re running it from. Other ways of running the app don’t always capture the information necessary to make a traceback.
Once you’ve located the source of the error and want to figure out what’s causing it, the most powerful tool you have at your disposal is the interactive debugger. The debugger pauses execution and gives you an interactive R console where you can run any code to figure out what’s gone wrong. There are two ways to launch the debugger:
base::browser() in your source code. This is the standard R way of launching the interactive debugger, and will work however you’re running Shiny. The advantage of browser() is that because it’s R code, you can make it conditional by combining it with an if statement. This allows you to launch the debugger only for problematic inputs.if (input$value == "a") {
browser()
}
# Or maybe
if (my_reactive() < 0) {
browser()
}
If you’re using RStudio, the toolbar in Screenshot 5.5 will appear at the top of the console when you’re in the debugger. The toolbar is an easy way to remember the debugging commands that are now available to you. They’re also available outside of RStudio; you’ll just need to remember the one letter command to activate them. The three most useful commands are:
n, you’ll need to use print(n) to display its value.
As well as stepping through the code line-by-line using these tools, you’ll also write and run a bunch of interactive code to track down what’s going wrong. Debugging is the process of systematically comparing your expectations to reality until you find the mismatch. If you’re new to debugging in R, you might want to read the Debugging chapter of “Advanced R” to learn some general techniques.
Resource 5.3 : Debugging
I have collected some resources for interactive debugging in R.
I skip over the interesting and illuminating case study because reproducing the reported strategies is not educationally valuable. I would need my own problem to debug.
In the case study there are two important learnings for me:
By the way: I ran over a similar problem as reported in the case study. Instead of confusing “NA” for North America with NA I had the ISO 3166 two letter country code (alpha2) with “NA”. (See filteredc dataset to “Namibia” in opendatasoft)
The hardest type of problem to debug is when your reactives fire in an unexpected order. At this point in the book, we have relatively few tools to recommend to help you debug this issue. In the next section, you’ll learn how to create a minimal reprex which is crucial for this type of problem, and later in the book, you’ll learn more about the underlying theory, and about tools like the reactivity visualizer {reactlog} (Schloerke 2022). But for now, we’ll focus on a classic technique that’s useful here: “print” debugging.
The basic idea of print debugging is to call print() whenever you need to understand when a part of your code is evaluated, and to show the values of important variables. We call this “print” debugging (because in most languages you’d use a print function), but In R it makes more sense to use message():
base::print() is designed for displaying vectors of data so it puts quotes around strings and starts the first line with “[1]”.base::message() sends its result to “standard error”, rather than “standard output”. These are technical terms describing output streams, which you don’t normally notice because they’re both displayed in the same way when running interactively. But if your app is hosted elsewhere, then output sent to “standard error” will be recorded in the logs.I also recommend coupling message() with the glue() function from the {glue} package, which makes it easy to interleave text and values in a message.2
A final useful tool is utils::str(), which prints the detailed structure of any object. This is particularly useful if you need to double check you have the type of object that you expect.
Summarized there are three tools for print debugging at this state of the notes:
Here’s a toy app that shows off some of the basic ideas. Note how I use message() inside a reactive(): I have to perform the computation, send the message, and then return the previously computed value.
Code Collection 5.1 : Toy example with print debugging
R Code 5.2 : Toy example from the book
#| '!! shinylive warning !!': |
#| shinylive does not work in self-contained HTML documents.
#| Please set `embed-resources: false` in your metadata.
#| standalone: true
#| components: [editor, viewer]
library(shiny)
library(glue)
ui <- fluidPage(
sliderInput("x", "x", value = 1, min = 0, max = 10),
sliderInput("y", "y", value = 2, min = 0, max = 10),
sliderInput("z", "z", value = 3, min = 0, max = 10),
textOutput("total")
)
server <- function(input, output, session) {
observeEvent(input$x, {
message(glue("Updating y from {input$y} to {input$x * 2}"))
updateSliderInput(session, "y", value = input$x * 2)
})
total <- reactive({
total <- input$x + input$y + input$z
message(glue("New total is {total}"))
total
})
output$total <- renderText({
total()
})
}
shinyApp(ui, server)I can’t demonstrate printing the output inside a reactive code snippet with {shinylive} here. Only the output in the not reactive output$total will appear. So I faked the output with copy and paste from the online book:
Updating y from 2 to 2
New total is 6And if I drag the x slider to 3 I see
Updating y from 2 to 6
New total is 8
New total is 12Don’t worry if you find the results a little surprising.
Yes, in fact, this is surprising for me, as I get the new total twice! I’ll will wait to learn more about what’s going on in Chapter 8 with the help of the reactive graph diagrams mentioned in Section 3.3.3.
In the meanwhile I have in the next tab changed text and place of the messages in this toy example.
R Code 5.3 : Toy example with my own print debugging messages
library(shiny)
library(glue)
ui <- fluidPage(
sliderInput("x", "x", value = 1, min = 0, max = 10),
sliderInput("y", "y", value = 2, min = 0, max = 10),
sliderInput("z", "z", value = 3, min = 0, max = 10),
textOutput("total")
)
server <- function(input, output, session) {
observeEvent(input$x, {
updateSliderInput(session, "y", value = input$x * 2)
})
total <- reactive({
total <- input$x + input$y + input$z
message(glue("New total is x+y+z = {input$x} + {input$y} + {input$z} = {total}"))
total
})
output$total <- renderText({
total()
})
}
shinyApp(ui, server)The printing command in the total reactive is easier to understand for me. But I think the places for the message() command in the book example are on those other places to show an specific behavior of the reactivity behavior of this Shiny toy example.
> shiny::runApp('apps-05/print-debugging')
Loading required package: shiny
Listening on http://127.0.0.1:7653
# After started the app
New total is x+y+z = 1 + 2 + 3 = 6
# After dragging the x slider to 3
New total is x+y+z = 3 + 2 + 3 = 8
New total is x+y+z = 3 + 6 + 3 = 12I will shorten this section as I have already some experiences with reprexes. I will focus on those points that are not so obvious for me.
{reprex} package: In the book the usage of the {reprex} package is not mentioned. It is a very useful tool and simplifies the technical process of catching the code. I am using the {reprex} package (Bryan et al. 2024) with RStudio addins, because that makes it much comfortable to use.
This section does not mention the technical process but focuses on conceptional issues.
Typically, the most challenging part of making your app work on someone else’s computer is eliminating the use of data that’s only stored on your computer. There are four useful patterns:
Often the data you’re using is not directly related to the problem, and you can instead use a built-in dataset like mtcars or iris.
Other times, you might be able to write a little R code that creates a dataset that illustrates the problem:
mydata <- data.frame(x = 1:5, y = c("a", "b", "c", "d", "e"))
mydata#> x y
#> 1 1 a
#> 2 2 b
#> 3 3 c
#> 4 4 d
#> 5 5 edput() datasetIf both of those techniques fail, you can turn your data into code with base::dput(). For example, dput(mydata) generates the code that will recreate `mydata```:
dput(mydata)#> structure(list(x = 1:5, y = c("a", "b", "c", "d", "e")), class = "data.frame", row.names = c(NA,
#> -5L))Once you have that code, you can put this in your reprex to generate mydata:
#> x y
#> 1 1 a
#> 2 2 b
#> 3 3 c
#> 4 4 d
#> 5 5 eOften, running dput() on your original data will generate a huge amount of code, so find a subset of your data that illustrates the problem. The smaller the dataset that you supply, the easier it will be for others to help you with your problem.
If reading data from disk seems to be an irreducible part of the problem, a strategy of last resort is to provide a complete project containing both an app.R and the needed data files. The best way to provide this is as a RStudio project hosted on GitHub, but failing that, you can carefully make a zip file that can be run locally.
Make sure that you use relative paths (i.e. read.csv("my-data.csv") not read.csv("c:\\my-user-name\\files\\my-data.csv")) so that your code still works when run on a different computer.
You should also consider the reader and spend some time formatting your code so that it’s easy to read. If you adopt the tidyverse style guide, you can automatically reformat your code using the {styler} package; that quickly gets your code to a place that’s easier to read.
Creating the smallest possible reprex is particularly important for Shiny apps, which are often complicated. But — as Jenny Bryan mentioned in her talk (see Section 5.2.1) — creating a minimal reprex is both a science and an art.
: Take a final pass through your Reprex
server() that you can now remove?Again I will skip the case study, especially as I can’t demonstrate it with a {**shinylive*} chunk. But I have provided the shiny apps in the “app05” folder.
Another remark: I got slightly different error messages. For instance instead of ““Type mismatch for min, max, and value. Each must be Date, POSIXt, or number” in the first case study example I got “Error in min: invalid ‘type’ (list) of argument” with my experiment in the console.
This chapter has given you some useful workflows for developing apps, debugging problems, and getting help. These workflows might seem a little abstract and easy to dismiss because they’re not concretely improving an individual app. But I think of workflow as one of my “secret” powers: one of the reasons that I’ve been able to accomplish so much is that I devote time to analysing and improving my workflow. I highly encourage you to do the same!
The next chapter on layouts and themes is the first of a grab bag of useful techniques. There’s no need to read in sequence; feel free to skip ahead to a chapter that you need for a current app.
I will follow the advice and continue with #sec-chap09 because I need the upload of a dataset for the work on my first real Shiny app.