Turn an R Markdown document into an interactive experience

R Markdown is one of my favorite things about modern R. It offers an easy way to combine text, R code, and the results of R code in a single document. And when that document is rendered as HTML, you can add some user interaction with HTML widgets like DT for tables or leaflet for maps. (If you’re not familiar with R Markdown, you can check out my R Markdown video tutorial first and then come back here.) 

But you may not know that there’s a way to amp up R Markdown interactivity even more: by adding runtime: shiny to the document header.

Shiny is a Web application framework for R. As a framework, it has a fairly specific structure. However, you can convert an R Markdown document into a Shiny app without having to follow a lot of that rigid structure. Instead, you can jump right in and start coding—without worrying about some typical Shiny tasks like ensuring all your parentheses and commas are correct within deeply nested layout functions.

In fact, even if you’re an experienced shiny developer, an R Markdown document can still be useful for shiny tasks where you don’t need a full-blown application or for quickly trying out code. It will still need a Shiny server, but if you've got RStudio and the shiny package installed, you already have one of those locally.

Let’s take a look at how runtime shiny works in R Markdown.

1. Basic R Markdown

I’ll start with a conventional, non-Shiny R Markdown document that features a searchable table of data by Massachusetts ZIP code. Users can search or sort by any table column, answering questions such as “Which ZIP codes have the highest median household income Middlesex County?” or “What ZIP codes have the priciest monthly housing?”

Sharon Machlis/IDG

This document also has a histogram showing distribution of median household incomes and text stating which ZIP codes have the highest and lowest incomes. The table is interactive, but the rest of the document is not. You can see the rendered HTML version on RStudio's RPubs.

If you’d like to follow along, you can see code for a stand-alone version of this R Markdown document—including data—on GitHub. Or, if you'd like to see how I got this demographic data into R, there's R code in this article to create your own data set (and you can tweak the code to pick another state). If you create your own version of the data, the code for a basic R Markdown document using a separate data file is also on GitHub.

Whichever R Markdown document you choose, you'll see that it's a mostly static document with some interactivity. But what if I’d like the whole document to be interactive—in this case, see the histogram and text change as well as the table? How can the user be able to select individual cities and see all information filtered to display just for those places?

One solution is to generate a page for each city—possible with an R script if you use what’s called parameterized reports. However, you can also create a single R Markdown document that functions like an interactive app.

Add Shiny interactivity

To add Shiny interactivity to a conventional R Markdown document, start by adding runtime: shiny to the document's YAML header, such as:

---
title: "Median Household Income by ZIP Code"
output: html_document
runtime: shiny
---

Once you do that and press Save, the knit icon in RStudio turns into “Run document.” Even though the output still says “html_document,” it won't be plain HTML any more. It's now a mini-Shiny application. 

Sharon Machlis/IDG

Sharon Machlis, IDG

Let users make data choices

Now I need a way for users to make their data choices. Shiny has a number of “input widgets” for this. I’ll use selectInput(), which creates a dropdown list and allows users to choose more than one item. Shiny has other widgets for radio buttons, text inputs, date selectors, and more. You can see a collection of them at RStudio’s Shiny Widgets Gallery. 

Code for my mini-app’s selectInput() dropdown list has five arguments and looks like this:

selectInput("mycities", "Choose 1 or more cities: ", 
  choices = sort(unique(markdowndata$City)), 
  selected = "Boston", multiple = TRUE)

The first argument to selectInput(), mycities is the variable name I've chosen to store whatever values the user picks. The second argument is the header text that will appear with the dropdown list. The third argument, choices, is a vector of all possible values in the dropdown list—in this case, unique values of city names in my data, sorted alphabetically. selected = Boston means the dropdown will default to Boston being the selected city (picking a default selection is optional). And, finally, multiple = TRUE allows users to choose more than one city at a time.

This code creates the HTML dropdown list. If you run that selectInput() code in your R console, it will generate HTML for the dropdown (assuming you have Shiny loaded and a data frame called markdowndata with a City column). 

Next, I need to write some R so that this dropdown actually does something.

Create dynamic variables

I’ll code this interactivity logic in two parts:

1. Create a data frame—I’ll call it mydata—that is filtered each time the user chooses a city.
2. Write code for text, histogram, and data table that will all change based on my dynamic data frame.

The most important thing to keep in mind at this point is that these objects aren't “regular” R variables anymore. They’re dynamic. They change based on user actions. And that means they work slightly differently than variables you’re probably used to.

What’s special about them? Here are the three things you need to know:

1. To access the value of an input variable that store information from your user, you need the syntax input$myvarname, not simply myvarname. So, for values stored in the mycities dropdown list, use input$mycities. 
2. Objects like graphs and tables that depend on values from your user are also dynamic and need to be reactive. That’s as easy as wrapping them in a special function, but you need to remember to do it. They also can't be accessed by just their names, but require parentheses as well: a syntax like myvar() and not myvar.
3. When you display dynamic content—once again, things like a table, a map, a histogram, or even text—it needs to be rendered in a special way, usually using one of Shiny’s special render functions. The good news is that Shiny takes care of most of the functionality of monitoring for changes and calculating results. You just need to know which function to use, and then include it in your code.

This is all often easier than that may sound. Here’s how I’d create a data frame called mydata that changes each time the user selects a city with the mycities selectInput() dropdown :

mydata <- reactive({
filter(markdowndata, City %in% input$mycities)
})

The mydata object now holds a reactive expression and will change value each time the user makes a change in the dropdown list controlling mycities.

Display dynamic variables

Now I'd like to code a table using that filtered mydata data.

As you might have guessed by now, DT::datatable(mydata) won’t work. And there are two reasons why.

First, because mydata is a reactive expression, you can’t refer to it by name alone. It needs parentheses after it, such as  mydata().

But, second, DT::datatable(mydata()) won’t work as standalone code, either. You’ll get an error message something like this: 

Operation not allowed without an active reactive context. 
(You tried to do something that can only be done from inside 
a reactive expression or observer.)

You may see versions of this error message quite often when you’re first starting out. It means that you’re trying to display something dynamic using conventional R syntax.

To fix this, I need a Shiny render function. Several visualization packages have their own special Shiny render functions, including DT. Its render function is renderDT(). If I add renderDT ({  }) around the DT code and run the document again, that should work.

This is my table code:

renderDT({
  DT::datatable(mydata(), filter = 'top') %>%
    formatCurrency(4:5, digits = 0) %>%
    formatCurrency(6, currency = "", digits = 0) 
  })

Note: In addition to creating and displaying the table, this code also adds some formatting. Columns 4 and 5 show as currency, with a dollar sign and commas. The second formatCurrency() line for column 6 adds the commas to the rounded numbers without a dollar sign, since I specified "" as the currency symbol.

I can use the same mydata() reactive data frame to create a histogram, using another Shiny render function: renderPlot().

renderPlot({
ggplot2::ggplot(mydata(), aes(x = MedianHouseholdIncome)) +
  geom_histogram(binwidth = 20000, color = "black", fill = "darkgreen") +
  theme_classic() +
   xlab("") +
  ylab("")  +
   scale_x_continuous(labels = dollar)
})

That code also includes a little ggplot styling, such as choosing colors for the bar outline and fill and changing the graph's theme. The last line formats the x axis to add dollar signs and commas, and it requires the scales package.

Each one of these blocks of R code needs to be within an R Markdown R code chunk, just like any other R code chunks in a conventional Markdown document. That could look something like the code below, which also names the chunk “histo” (names are optional) and sets the width and height of my plot in inches.

```{r histo, fig.width = 3, fig.height = 2}
renderPlot({
ggplot2::ggplot(mydata(), aes(x = MedianHouseholdIncome)) +
  geom_histogram(binwidth = 20000, color = "black", fill = "darkgreen") +
  theme_classic() +
   xlab("") +
  ylab("")  +
   scale_x_continuous(labels = dollar)
})
```

If I'd like to display interactive text that changes with the user's selection, I need a Shiny render function that's named—surprise!—renderText(). You can put that inside a code chunk, or use alternative R Markdown syntax format outside of code chunks like this:

I have some plain text and then add  `r R CODE WILL BE EVALUATED HERE`

The syntax for this is one backtick followed immediately by a lower-case r, a space, the R code you want evaluated, and ending with another single backtick. So, to add a dynamic headline for the histogram, you could use code like this:

Histogram for `r renderText({input$mycities})`

This works fine for a single city. However, if there's more than one city, that code will just display the names without commas between them, such as Boston Cambridge Amherst. For public-facing code,  you'd want to pretty that up a bit, perhaps using base R's paste() function:

Histogram for `r renderText({paste(input$mycities, 
  sep = " ", collapse = ", ")})`

You can use similar code to generate text that tells users the ZIP codes with highest and lowest median incomes. For those calculations, I created one reactive data frame containing the row with the highest household income and another with the lowest.

I also discovered that the lowest median income was being suspiciously low—$2,500 in the college-town community of Amherst, Mass.—where the median monthly housing cost is $1,215. My guess is that's a concentration of student housing, so I excluded any ZIP code with median household income of less than $5,000.

Here is code to create those two data frames:

zip_highest_income_row <- reactive({
  filter(mydata(), MedianHouseholdIncome == max(MedianHouseholdIncome, na.rm = TRUE))
})
zip_lowest_income_row <- reactive({
  filter(mydata(), MedianHouseholdIncome >= 5000) %>%
  filter(MedianHouseholdIncome == min(MedianHouseholdIncome, na.rm = TRUE))
})

This should look like typical dplyr filter() code, except that 1) each is wrapped in a reactive({ }) function, and 2) the mydata dynamic data frame which changes based on user input is referred to as mydata() and not simply mydata. 

To show the value of the first item in the zip_highest_income_row data frame's ZIP column, I can't use usual R code like zip_highest_income_row$Zip[1]. Instead,  I need to refer to the dynamic data frame with parentheses: zip_highest_income_row()$Zip[1] . And then wrap that in a Shiny render() function—in this case renderText():

ZIP code `r renderText(zip_highest_income_row()$ZipCode[1])` in
 `r renderText(zip_highest_income_row()$City[1])` 
has the highest median income in the place(s) you selected, 
`r renderText(scales::dollar(zip_highest_income_row()$MedianHouseholdIncome[1]))`. 

ZIP code `r renderText(zip_lowest_income_row()$ZipCode[1])` in
`r renderText(zip_lowest_income_row()$City[1])` has the lowest 
median income in the place(s) you selected,
`r renderText(scales::dollar(zip_lowest_income_row()$MedianHouseholdIncome[1]))`.

Run and share your Shiny app

Once you add runtime: shiny to an R Markdown, it’s not an HTML file anymore—it’s a mini Shiny application. And that means it needs a Shiny server to run.

As I mentioned earlier, anyone with R, RStudio, and the shiny package has a Shiny server on their local system. That makes it easy to share any Shiny app with fellow R users. You can send them a document by email or, more elegantly, post it online as a zipped file and use the shiny::runUrl() command. There are special runGitHub() and runGist() functions for apps on GitHub that are convenient if you use GitHub for projects, which will automatically zip additional files in your project, such as data files.

But chances are, at some point you’ll want to show your work to non-R users, and that requires a publicly accessibly Shiny server. Probably the easiest option is RStudio’s shinyapps.io service. It’s free for a few limited public apps with very light usage. Paid accounts are priced based on the number of active hours they offer for your apps. Active hours measure time the application is actively being used—one person on for an hour is the same hour as 100 people in that hour. To ensure 24x7 uptime for a couple of apps, you’d need the $1,100/year standard account with 2,000 hours.

You can also build your own Shiny server on a cloud service like AWS and installations for R and the free version of RStudio’s Shiny server software. There’s a great step-by-step tutorial by Dean Attali showing how to do so at Digital Ocean, where you can build and run a small Shiny server for just $5 per month of hosting costs without worrying about active hours. The trade-off is doing your own patching and R/library updates—and you may need a heftier virtual server than the cheapest 1G droplet for robust applications.

Add an interactive map

Finally, I'll walk you through how I added an interactive map to this document using the leaflet package.

First, you need a file with geospatial data as well as numerical data, so your app knows the shape of each ZIP code. The code below explains how create a spatial data frame using the tidycensus and sf packages.

For interactivity, I'll create a dynamic version of that spatial data, so only the selected cities show up on the map. Below is my code for doing that. It may look a little repetitive, but I'm going for readability instead of brevity. Feel free to tighten your own version.

mapdata <- reactive({
  if("All Mass" %in% input$mycities){
    ma_appdata_for_map %>%
      dplyr::select(ZipCode = GEOID, MedianHouseholdIncome = medincome, MedianMonthlyHousingCost = medmonthlyhousingcost, Population = pop, City, County = county.name, State, Lat, Long, income, housing, Pop, geometry) %>%
      mutate(
        Highlighted = "Yes"
      ) %>%
      sf::st_as_sf()
  } else {
  dplyr::filter(ma_appdata_for_map, City %in% input$mycities) %>%
  dplyr::select(ZipCode = GEOID, MedianHouseholdIncome = medincome, MedianMonthlyHousingCost = medmonthlyhousingcost, Population = pop, City, County = county.name, State, Lat, Long, income, housing, Pop, geometry) %>%
  dplyr::mutate(
    Highlighted = ifelse(City %in% input$mycities, "Yes", "No")
  ) %>%
    sf::st_as_sf()
  }
})

The reactive function should be familiar by now. My if and else statements take into account whether the user has chosen All Mass or just individual cities. For any choice but All Mass, I filter for just the selected cities. In both cases I'm using a conventional dplyr select() function to choose which columns I want in the map, making sure to include Lat for latitude, Long for longitude, and geometry that holds the ZIP code polygon shape files. The last line in each if() code section makes sure the results are an sf (simple features) geospatial object. While I didn't need that code on my local Mac, the app worked better on shinyapps.io when I included it.

Now it’s time to work on map colors. I'll set up two reactive color palettes for my leaflet map, one for income and the other for housing costs. In both cases I use greens, but you could choose any you'd like. 

incomepal <- reactive({
  leaflet::colorNumeric(palette = "Greens", 
    domain = mapdata()$MedianHouseholdIncome)
})
housingpal <- reactive({
  leaflet::colorNumeric(palette = "Greens", 
    domain = mapdata()$MedianMonthlyHousingCost)
})

I want these to be reactive, too, so they change based on user selections. The domain argument defines the values that the palette will be displaying. In the first case, it’s my reactive mapdata object's MedianHouseholdIncome column—with mapdata coded as mapdata() since it's reactive; in the second case, it's the MedianMonthlyHousingCost column.

I'll also set up exactly how I want my popup text to appear. This can take a mixture of HTML (the <br /> is an HTML line break) and data frame columns. While you can certainly use base R’s paste() or paste0() functions, I find the glue package much easier when dealing with more than one variable mixed in with text. You can see below that I just need to enclose variables I want evaluated within curly braces. Of course, the popup text needs to be reactive as well, so it, too, changes with the user’s selection.

mypopups <- reactive({
  glue::glue("ZIP Code: {mapdata()$ZipCode}<br />Median Household Income: {mapdata()$income}<br />Median Monthly Housing Cost: {mapdata()$housing}<br />Population: {mapdata()$Pop}<br />City: {mapdata()$City}<br />County: {mapdata()$County}")
})

Finally, code for the leaflet map itself.

leaflet::renderLeaflet({
  leaflet(mapdata()) %>%
   addProviderTiles("CartoDB.Positron") %>%
    addPolygons(fillColor = ~incomepal()(mapdata()$MedianHouseholdIncome),
              fillOpacity = 0.7, 
              weight = 1.0, 
              color = "black",
              smoothFactor = 0.2,
              popup = mypopups(),
              group = "Household Income"
  ) %>%
      addPolygons(fillColor = ~housingpal()(mapdata()$MedianMonthlyHousingCost),
              fillOpacity = 0.7, 
              weight = 0.2, 
              color = "black",
              smoothFactor = 0.2,
              popup = mypopups(),
              group = "Housing Costs"
  ) %>%
  addLayersControl(
      baseGroups=c("Household Income", "Housing Costs"),
      position = "bottomleft",
      options = layersControlOptions(collapsed = FALSE)
      ) 
})

renderLeaflet() is the Shiny render function that will display the dynamic dataviz relying on the dynamic mapdata object. Inside that function is "regular" leaflet mapping code. The first line, leaflet(mapdata()), creates an R leaflet object from the reactive mapdata object. It is using the leaflet package, which is an R wrapper to the leaflet.js library. Next line adds a style of background map tiles from CartoDB.

The addPolygons() function tells leaflet how to display the ZIP code polygons. I want it colored by the MideanHouseholdIncome column using the income palette I set up earlier, incomepal. Most of the rest of those arguments are styling. The popup argument sets the popup text to be the mypopups object I created earlier, and the group argument gives a name to the map layer.

I add another similar layer for median monthly housing costs. And, finally, the addLayersControl() puts a clickable legend for each layer at the bottom left.

Sharon Machlis/IDG

If you'd like to learn more about mapping in R with leaflet, see my tutorial “Create maps in R in 10 (fairly) easy steps.”

The final R markdown file

You can see the final R Markdown file on GitHub. If you look carefully at the code, you may notice a few additions. I added All Mass to the selectInput() dropdown list choice vector, so that code is now

selectInput("mycities", "Choose 1 or more cities: ", 
choices = c("All Mass", sort(unique(markdowndata$City))), 
multiple = TRUE, selected = "Boston")

And then I tweaked several other lines of code to give a different option if All Mass is selected, such as creating a dynamic variable selected_places that will say "Massachusetts" if "All Mass" is one of the selected cities.

selected_places <- reactive({
  if("All Mass" %in% input$mycities){
  "Massachusetts"
} else {
  paste(input$mycities, 
  sep = " ", collapse = ", ")
}
})

Note also the new YAML header:

---
title: "Median Household Income by ZIP Code"
output: html_document
resource_files:
   - mamarkdowndata.rdata
   - zip_mass_appdata_for_map.rds
runtime: shiny
---

That resources_files: option says that this document requires two other files in order to run, mamarkdowndata.rdata and zip_mass_appdata_for_map.rds. This lets shinyapps.io know those files need to be uploaded along with the main R Markdown document when deploying a file with  rsconnect::deployDoc("docname.Rmd").

You can see this interactive R Markdown document with Shiny in action at https://idgrapps.shinyapps.io/runtimeshiny/. It may take a little while to load, since I didn't attempt to optimize this code for speed. RStudio has some resources if you want to learn about speeding up Shiny apps.

How is this different from a 'real' Shiny app?

This super-charged-with-Shiny R Markdown document differs from a full-fledged Shiny app in a few key ways.

1. A Shiny app needs to be in one file called app.R or two files ui.R and server.R. The app can source additional files with other names, but that file-naming structure is absolute. In a one-file app.R app, sections are needed for the ui (user interface, which defines what the user sees and interacts with) and the server.

2. Shiny app layouts are built around the Bootstrap page grid framework. You can see more about layout structure at RStudio's Shiny application layout guide.

3. Most dynamic components that you want to render, including things like graphs and tables, need to be specifically placed somewhere on the page with additional Output functions and definitions. For example, an interactive leaflet map would need code such as leafletOutput("mymap") somewhere in the ui to tell the app where it should display,  in addition to server code such as 

output$mymap <- renderLeaflet({ #MAP CODE HERE }) 

to define the logic behind generating the map.

Here is an example of a Shiny app.R file for this app's histogram and table:

library("shiny")
library("dplyr")
library("ggplot2")
library("DT")
options(scipen = 999)
load("mamarkdowndata.rdata") # loads variable markdowndata
ma_appdata_for_map <- readRDS("zip_mass_appdata_for_map.rds")
# Define UI 
ui <- fluidPage(
    # Application title
    titlePanel("Income and Housing Costs by ZIP Code"),
    # Sidebar 
    sidebarLayout(
        sidebarPanel(
        selectInput("mycities", "Choose 1 or more Massachusetts places: ", choices = c("All Mass", sort(unique(markdowndata$City))), multiple = TRUE, selected = "Boston"),
        br(),
        strong("Note: some cities may have more than one place name for ZIP codes. For example, Allston, Brighton, Dorchester, and several other neighborhoods are not included in ZIP code place name \"Boston\".")
        ),
        # Show histogram
        mainPanel(
           h4(htmlOutput("histogramHeadline")),
           plotOutput("myhistogram"),
           br(),
           h4(htmlOutput("tableHeadline")),
           DTOutput("mytable")
        )
    )
)
# Define server logic required to draw a histogram
server <- function(input, output) {
    mydata <- reactive({
        if("All Mass" %in% input$mycities){
            markdowndata
        } else {
            filter(markdowndata, City %in% input$mycities)
        }
    })
    selected_places <- reactive({
        if("All Mass" %in% input$mycities){
            "Massachusetts"
        } else {
            paste(input$mycities, 
                  sep = " ", collapse = ", ")
        }
    })
    output$histogramHeadline <- renderUI({
        paste("Histogram for", selected_places(), " income data")
    })
    output$tableHeadline <- renderUI({
        paste("Data for", selected_places())
    })
    output$myhistogram <- renderPlot({
        ggplot(mydata(), aes(x = MedianHouseholdIncome)) +
            geom_histogram(binwidth = 20000, color = "black", fill = "darkgreen") +
            theme_classic() +
            xlab("") +
            ylab("")  +
            scale_x_continuous(labels = dollar)
})
   output$mytable <- renderDT({
       DT::datatable(mydata(), filter = 'top') %>%
           formatCurrency(4:5, digits = 0) %>%
           formatCurrency(6, currency = "", digits = 0)
   })
}
# Run the application 
shinyApp(ui = ui, server = server)

You can find out more about building these kind of Shiny apps at RStudio's Shiny intro tutorials.

For more R tips, head to the Do More With R video page on InfoWorld or the Do More With R playlist on YouTube.