A beginner's guide to Shiny modules

Why Modules?

Modules act like functions by wrapping up sets of Shiny UI and server elements. You may wonder why you cannot just accomplish this with the normal R functions. The reason for this is a bit technical and is explained well in Mastering Shiny. However, the technical knowledge needed to understand “why functions don’t work” should not make modules an advanced topic. If you see the value of writing functions, you are more than ready to take advantage of modules in app development.

Motivating Example

For the sake of argument, let’s pretend that we are building an airline dashboard to track travel delays against established thresholds. We have the following requirements:

• Let users pick a month of interest to visualize
• For each metric of interest, users should be able to:
  • See a time-series plot of the average daily value of the metric
  • Download a PNG of the plot
  • Read a text summary of how often the value breached the threshold
• The metrics of interest are:
  • Average departure delay
  • Average arrival delay
  • Proportion of daily flights with an arrival delay exceeding 5 minutes

Below is a preview of the final application. The full app is currently hosted in ShinyApps.io and the code available on GitHub. It would not win any beauty contests, but its simple style allows us to focus on modules in the code.

Two line graphs for departure and arrival times where we see variation compared to the average

Set-Up

library(shiny)
library(nycflights13)
library(dplyr)

## 
## Attaching package: 'dplyr'

## The following objects are masked from 'package:stats':
## 
##     filter, lag

## The following objects are masked from 'package:base':
## 
##     intersect, setdiff, setequal, union

library(ggplot2)

To understand the following explanation, it helps to familiarize yourself with the data. We filter the flights data down to a single airline and aggregate the results by day.

ua_data <-
  nycflights13::flights %>%
  filter(carrier == "UA") %>%
  mutate(ind_arr_delay = (arr_delay > 5)) %>%
  group_by(year, month, day) %>%
  summarize(
    n = n(),
    across(ends_with("delay"), mean, na.rm = TRUE)
    ) %>%
  ungroup()

## `summarise()` has grouped output by 'year', 'month'. You can override using the `.groups` argument.

head(ua_data)

## # A tibble: 6 x 7
##    year month   day     n dep_delay arr_delay ind_arr_delay
##   <int> <int> <int> <int>     <dbl>     <dbl>         <dbl>
## 1  2013     1     1   165      7.65     6.27          0.476
## 2  2013     1     2   170     12.8      7.04          0.458
## 3  2013     1     3   159      8.66    -2.76          0.357
## 4  2013     1     4   161      6.84    -9.86          0.180
## 5  2013     1     5   117      9.66     0.786         0.274
## 6  2013     1     6   137      9.79     3.53          0.409

Next, we define the plotting function that we will use to visualize a month-long timeseries of data for each metric.

viz_monthly <- function(df, y_var, threshhold = NULL) {
  
  ggplot(df) +
    aes(
      x = .data[["day"]],
      y = .data[[y_var]]
    ) +
    geom_line() +
    geom_hline(yintercept = threshhold, color = "red", linetype = 2) +
    scale_x_continuous(breaks = seq(1, 29, by = 7)) +
    theme_minimal()
}

For example, to visualize the average arrival delay by day for all of March and compare it to a threshold of 10 minutes, we can write:

ua_data %>%
  filter(month == 3) %>%
  viz_monthly("arr_delay", threshhold = 10)

One Module at a Time

Modules don’t just help organize your code; they help you organize your thinking. Given our app requirements, it might feel overwhelming where to start. Filtering the data? Making the plots? Wiring up buttons? Inevitably, when juggling many components, you’re likely to introduce a bug by copy-pasting a line with the wrong id or getting nested parentheses out of whack.

Instead, modules essentially allow your to write many simple Shiny apps and compose them together.

For example, we might decide that first we just want to focus on a very simple app: given a monthly subset of the data, a metric, and a threshold of interest. Let’s write a simple text summary of the flights performance. We now know we just need to define a UI (text_ui) with a single call to textOutput(), a server (text_server) that does a single calculation and calls renderText(). Best of all, we can immediately see whether or not our “app” works by writing a minimalist testing function (text_demo) which renders the text for a small, fake dataset.

Those steps are implemented in a file called mod-text.R:

You can find all of the code for this tutorial in this demo Shiny application repository. We can follow the same pattern to create a module for the plot itself (in the file mod-plot.R) consisting of a UI (plot_ui), a server (plot_server), and a testing function (plot_demo). This module is responsible for plotting one metric and allowing users to download the results.

Composing Modules

We now have a text module and a plot module. However, for each metric of interest, we want to produce both. We could call these two modules one-at-a-time, but we can also compose multiple modules together so that we can produce in single commands everything that we need for a given metric.

With all of the underlying plot and text module logic abstracted, our metric module definition (in the mod-metr.R file) is very clean and simple:

# metric module ----
metric_ui <- function(id) {
  
  fluidRow(
    text_ui(NS(id, "metric")),
    plot_ui(NS(id, "metric"))
  )
  
}
metric_server <- function(id, df, vbl, threshhold) {
  
  moduleServer(id, function(input, output, session) {
    
    text_server("metric", df, vbl, threshhold)
    plot_server("metric", df, vbl, threshhold)
    
  })
  
}
metric_demo <- function() {
  
  df <- data.frame(day = 1:30, arr_delay = 1:30)
  ui <- fluidPage(metric_ui("x"))
  server <- function(input, output, session) {
    metric_server("x", reactive({df}), "arr_delay", 15)
  }
  shinyApp(ui, server)
  
}

Again, we can test that these components went together as we intended by running the metric_demo() function. We see the text from our text module on top of the plot and button from our plot module:

Line graph for flight arrival times where we see how many days exceeded the average

This may be overkill for a simple app, but composing modules is very useful as your application grows in complexity. Everything you bundle into a module gives you a license to forget about how the next layer lower is implemented and frees up your mind to take on the next challenge.

Putting it all together

Finally, we are ready to write our complete application in a file called flights-app.R:

viz_monthly <- function(df, y_var, threshhold = NULL) {
  
  ggplot(df) +
    aes(
      x = .data[["day"]],
      y = .data[[y_var]]
    ) +
    geom_line() +
    geom_hline(yintercept = threshhold, color = "red", linetype = 2) +
    scale_x_continuous(breaks = seq(1, 29, by = 7)) +
    theme_minimal()
}

# text module ----
text_ui <- function(id) {
  
  fluidRow(
    textOutput(NS(id, "text"))
  )
  
}

text_server <- function(id, df, vbl, threshhold) {
  
  moduleServer(id, function(input, output, session) {
    
    n <- reactive({sum(df()[[vbl]] > threshhold)})
    output$text <- renderText({
      paste("In this month", 
            vbl, 
            "exceeded the average daily threshhold of",
            threshhold,
            "a total of", 
            n(), 
            "days")
    })
    
  })
  
}

text_demo <- function() {
  
  df <- data.frame(day = 1:30, arr_delay = 1:30)
  ui <- fluidPage(text_ui("x"))
  server <- function(input, output, session) {
    text_server("x", reactive({df}), "arr_delay", 15)
  }
  shinyApp(ui, server)
}
  
# plot module ----
plot_ui <- function(id) {
  
  fluidRow(
    column(11, plotOutput(NS(id, "plot"))),
    column( 1, downloadButton(NS(id, "dnld"), label = ""))
  )
  
}

plot_server <- function(id, df, vbl, threshhold = NULL) {
  
  moduleServer(id, function(input, output, session) {
    
    plot <- reactive({viz_monthly(df(), vbl, threshhold)})
    output$plot <- renderPlot({plot()})
    output$dnld <- downloadHandler(
      filename = function() {paste0(vbl, '.png')},
      content = function(file) {ggsave(file, plot())}
    )
    
  })
}

plot_demo <- function() {
  
  df <- data.frame(day = 1:30, arr_delay = 1:30)
  ui <- fluidPage(plot_ui("x"))
  server <- function(input, output, session) {
    plot_server("x", reactive({df}), "arr_delay")
  }
  shinyApp(ui, server)
}

# metric module ----
metric_ui <- function(id) {
  
  fluidRow(
    text_ui(NS(id, "metric")),
    plot_ui(NS(id, "metric"))
  )
  
}

metric_server <- function(id, df, vbl, threshhold) {
  
  moduleServer(id, function(input, output, session) {
    
    text_server("metric", df, vbl, threshhold)
    plot_server("metric", df, vbl, threshhold)
    
  })
  
}

metric_demo <- function() {
  
  df <- data.frame(day = 1:30, arr_delay = 1:30)
  ui <- fluidPage(metric_ui("x"))
  server <- function(input, output, session) {
    metric_server("x", reactive({df}), "arr_delay", 15)
  }
  shinyApp(ui, server)
  
}

# load libraries ----
library(nycflights13)
library(shiny)
library(ggplot2)
library(dplyr)
# data prep ----
ua_data <-
  nycflights13::flights %>%
  filter(carrier == "UA") %>%
  mutate(ind_arr_delay = (arr_delay > 5)) %>%
  group_by(year, month, day) %>%
  summarize(
    n = n(),
    across(ends_with("delay"), mean, na.rm = TRUE)
    ) %>%
  ungroup()
# full application ----
ui <- fluidPage(
  
  titlePanel("Flight Delay Report"),
  
  sidebarLayout(
  sidebarPanel = sidebarPanel(
    selectInput("month", "Month", 
                choices = setNames(1:12, month.abb),
                selected = 1
    )
  ),
  mainPanel = mainPanel(
    h2(textOutput("title")),
    h3("Average Departure Delay"),
    metric_ui("dep_delay"),
    h3("Average Arrival Delay"),
    metric_ui("arr_delay"),
    h3("Proportion Flights with >5 Min Arrival Delay"),
    metric_ui("ind_arr_delay")
  )
)
)
server <- function(input, output, session) {
  
  output$title <- renderText({paste(month.abb[as.integer(input$month)], "Report")})
  df_month <- reactive({filter(ua_data, month == input$month)})
  metric_server("dep_delay", df_month, vbl = "dep_delay", threshhold = 10)
  metric_server("arr_delay", df_month, vbl = "arr_delay", threshhold = 10)
  metric_server("ind_arr_delay", df_month, vbl = "ind_arr_delay", threshhold = 0.5)
  
}
shinyApp(ui, server)

You can find all of the code for this tutorial in this demo Shiny application repository.

Notice how few lines of code this file requires to create all of our components and interactions! We’ve eliminated much of the dense code, nesting, and potential duplication we might have encountered if trying to write our application without modules. The top-level code is accessible, semantic, and declarative. It is easy to understand the intent of each line and which pieces of UI and server logic are responsible for which components.

Not all modules are made alike, and in this walk-through I chose simple tasks to demonstrate. Note that our modules consume a reactive variable (data) from the environment, but they do not attempt to alter the global environment or exchange information between them. Modules that simply consume reactives are the easiest way to start out.

Note from the Editor: Emily’s winning entry displays several characteristics of good technical writing. She is laser focused on her audience: R users who have some Shiny experience but who are not familiar with modules. Emily’s prose is direct, simple, informal and engaging. Reading it, I feel as if Emily is beside me showing me how things work, and that she cares about me understanding it. Emily’s code is spacious, and laid out to be read by others. And maybe not so obvious on the first reading, Emily’s writing is disciplined. It is clear that she knows a lot more about things than she has has put into the post, but is working under self imposed constraints in pursuit of clarity.