1.1 Structure of a Shiny App

Shiny apps have two components:

• a user interface script
• a server script

The user interface (UI) script controls the layout and appearance of your app. It is defined in a source file named ui.R. Below is the ui.R script for the Hello Shiny example.

library(shiny)

# Define UI for application that draws a histogram
shinyUI(fluidPage(

  # Application title
  titlePanel("Hello Shiny!"),

  # Sidebar with a slider input for the number of bins
  sidebarLayout(
    sidebarPanel(
      sliderInput("bins",
                  "Number of bins:",
                  min = 1,
                  max = 50,
                  value = 30)
    ),

    # Show a plot of the generated distribution
    mainPanel(
      plotOutput("distPlot")
    )
  )
))

The server.R script contains the instructions that your computer needs to build the app. Here is the server.R file for the Hello Shiny example.

library(shiny)

# Define server logic required to draw a histogram
shinyServer(function(input, output) {

  # Expression that generates a histogram. The expression is
  # wrapped in a call to renderPlot to indicate that:
  #
  #  1) It is "reactive" and therefore should be automatically
  #     re-executed when inputs change
  #  2) Its output type is a plot

  output$distPlot <- renderPlot({
    x    <- faithful[, 2]  # Old Faithful Geyser data
    bins <- seq(min(x), max(x), length.out = input$bins + 1)

    # draw the histogram with the specified number of bins
    hist(x, breaks = bins, col = 'darkgray', border = 'white')
  })

})

At one level, the Hello Shiny server script is very simple. It does some calculations and then plots a histogram with the requested number of bins.

However, you’ll also notice that most of the script is wrapped in a call to renderPlot. The comment above the function explains a bit about this, but if you find it confusing, don’t worry. We’ll cover this concept in much more detail soon.

Play with the Hello Shiny app and review it’s source code. Try to develop a feel for how the app works. Your R session will be busy while the Hello Shiny app is active, so you will not be able to run any R commands. R is monitoring the app and executing the app’s reactions. To get your R session back, hit escape or click the stop sign icon (found in the upper right corner of the RStudio console panel).

1.2 Running an App

Every Shiny app has the same structure: two R scripts saved together in a directory. At a minimum, an app has ui.R and server.R files, and you can create an app by making a new directory and saving the ui.R and server.R file inside it. Each Shiny app will need its own unique directory.

You can run a Shiny app by giving the name of its directory to the function runApp. For example, if your app is in a directory called my_app, run it with the following code:

library(shiny)
runApp("my_app")

Note: The first argument of runApp is the file path from your working directory to the app’s directory. The code above assumes that the app directory is in your working directory; in such case, the file path is just the name of the directory.

In case you are wondering, the Hello Shiny app’s files are stored in a special system directory designed to work with the runExample call. Alternatively, you can also launch that app by calling

runApp(system.file(package="shiny", "examples", "01_hello"))

1.3 Your turn

Create your first Shiny app named my_app. For this, start RStudio and from the File menu choose New Project… > New Directory > Shiny Web Application. As the Directory name enter the desired name my_app. The project will start with ui.R and server.R containing the familiar code from the Hello Shiny app.

To launch your app, run in the R console:

library(shiny)
runApp()

Alternatively, you can click the Run App button (at the top of the editor), or or use the keyboard shortcut: Control+Shift+Enter on Windows/Linux, or Command+Shift+Enter on MAC.

RStudio will launch the app in a new window by default, but you can also choose to have the app launch in a dedicated viewer pane, or in your external web browser. Make your selection by clicking the icon next to Run App.

Make some changes to your app:

1. Change the title to “Hello World!”.
2. Set the minimum value of the slider bar to 5.
3. Change the histogram color from "darkgray" to "skyblue".

When you are ready, launch your app again. Your new app should match the image below.

2.1 Layout

The Shiny ui.R script uses the function fluidPage to create a display that automatically adjusts to the dimensions of your user’s browser window. You lay out the app by placing elements in the fluidPage function.

For example, the ui.R script below creates a user interface that has a title panel and then a sidebar layout, which includes a sidebar panel and a main panel. Note that these elements are placed within the fluidPage function.

# ui.R

shinyUI(fluidPage(
  titlePanel("title panel"),

  sidebarLayout(
    sidebarPanel("sidebar panel"),
    mainPanel("main panel")
  )
))

titlePanel and sidebarLayout are the two most popular elements to add to fluidPage. They create a basic Shiny app with a sidebar. sidebarLayout always takes two arguments:

• sidebarPanel function output
• mainPanel function output

These functions place content in either the sidebar or the main panels.

titlePanel and sidebarLayout create a basic layout for your Shiny app, but you can also create more advanced designs. For example, navbarPage creates a multi-page user interface that includes a navigation bar. You can also divide the page into equally spaced regions using splitLayout, or you can use fluidRow and column to build a grid-based layout. For an overview, see the Shiny cheat sheet.

2.2 HTML Content

You can add content to your Shiny app by placing it inside a *Panel function. For example, the app above displays a character string in each of its panels. The words “sidebar panel” appear in the sidebar panel, because we added the string to the sidebarPanel function, i.e. sidebarPanel("sidebar panel"). The same is true for the text in the title panel and the main panel.

To add more advanced content, use one of Shiny’s HTML tag functions. These functions parallel common HTML5 tags. As an example, let’s try out creating headers.

h1("My title")

## <h1>My title</h1>

# ui.R

shinyUI(fluidPage(
  titlePanel("My Shiny App"),
  sidebarLayout(
    sidebarPanel(),
    mainPanel(
      h1("First level title"),
      h2("Second level title"),
      h3("Third level title"),
      h4("Fourth level title"),
      h5("Fifth level title"),
      h6("Sixth level title")
    )
  )
))

2.3 Other tags

We have demonstrated how to use the header tag functions, but there are many more tag functions for you to use. shiny::tags contains a list of 110 functions, each of which builds a specific HTML tag. If you are familiar with HTML, you will recognize these tags by their names.

names(tags)

##   [1] "a"           "abbr"        "address"     "area"        "article"    
##   [6] "aside"       "audio"       "b"           "base"        "bdi"        
##  [11] "bdo"         "blockquote"  "body"        "br"          "button"     
##  [16] "canvas"      "caption"     "cite"        "code"        "col"        
##  [21] "colgroup"    "command"     "data"        "datalist"    "dd"         
##  [26] "del"         "details"     "dfn"         "div"         "dl"         
##  [31] "dt"          "em"          "embed"       "eventsource" "fieldset"   
##  [36] "figcaption"  "figure"      "footer"      "form"        "h1"         
##  [41] "h2"          "h3"          "h4"          "h5"          "h6"         
##  [46] "head"        "header"      "hgroup"      "hr"          "html"       
##  [51] "i"           "iframe"      "img"         "input"       "ins"        
##  [56] "kbd"         "keygen"      "label"       "legend"      "li"         
##  [61] "link"        "mark"        "map"         "menu"        "meta"       
##  [66] "meter"       "nav"         "noscript"    "object"      "ol"         
##  [71] "optgroup"    "option"      "output"      "p"           "param"      
##  [76] "pre"         "progress"    "q"           "ruby"        "rp"         
##  [81] "rt"          "s"           "samp"        "script"      "section"    
##  [86] "select"      "small"       "source"      "span"        "strong"     
##  [91] "style"       "sub"         "summary"     "sup"         "table"      
##  [96] "tbody"       "td"          "textarea"    "tfoot"       "th"         
## [101] "thead"       "time"        "title"       "tr"          "track"      
## [106] "u"           "ul"          "var"         "video"       "wbr"

To create a tag, run an element of tags as a function. For instance, to create a div tag, use:

tags$div()

##<div></div>

You can call some of the most popular tags with helper functions that make accessing them easier. For example, the function code is a wrapper for tags$code and creates text formatted as computer code. Other available helper functions are: a, br, code, div, em, h1, h2, h3, h4, h5, h6, hr, img, p, pre, span, and strong. The names of the rest of tag functions conflict with the names of native R functions, so you will need to call them with the tags$ syntax.

3.1 Adding widgets

You can add widgets to the user interface in the same way that you add other types of HTML content by placing a widget function in sidebarPanel or mainPanel in your ui.R file.

Each widget function requires several arguments. The first two arguments for each widget are

• A Name for the widget. The user will not see this name, but you can use it to access the widget’s value. The name should be a character string.
• A label. This label will appear with the widget in your app. It should be a character string, but it can be an empty string "".

The remaining arguments vary from widget to widget, depending on what the widget needs to do its job. You can find the exact arguments required by a widget on the widget function’s help page, e.g., ?selectInput.

The code below makes the app pictured above. Change the ui.R script of my_app to match it, and then relaunch the app. Play with each widget to get a feel for what it does. Experiment with changing the values of the widget functions and observe the effects.

# ui.R

shinyUI(fluidPage(
  titlePanel("Basic widgets"),
  
  fluidRow(
    
    column(3,
      h3("Buttons"),
      actionButton("action", label = "Action"),
      br(),
      br(), 
      submitButton("Submit")),
    
    column(3,
      h3("Single checkbox"),
      checkboxInput("checkbox", label = "Choice A", value = TRUE)),
    
    column(3, 
      checkboxGroupInput("checkGroup", 
        label = h3("Checkbox group"), 
        choices = list("Choice 1" = 1, "Choice 2" = 2, "Choice 3" = 3),
        selected = 1)),
    
    column(3, 
      dateInput("date", label = h3("Date input"), value = "2014-01-01"))   
  ),
  
  fluidRow(
    
    column(3,
      dateRangeInput("dates", label = h3("Date range"))),
    
    column(3,
      fileInput("file", label = h3("File input"))),
    
    column(3, 
      h3("Help text"),
      helpText("Note: help text isn't a true widget,", 
        "but it provides an easy way to add text to",
        "accompany other widgets.")),
    
    column(3, 
      numericInput("num", label = h3("Numeric input"), value = 1))   
  ),
    
  fluidRow(
    
    column(3,
      radioButtons("radio", label = h3("Radio buttons"),
        choices = list("Choice 1" = 1, "Choice 2" = 2, "Choice 3" = 3), selected = 1)),
    
    column(3,
      selectInput("select", label = h3("Select box"), 
        choices = list("Choice 1" = 1, "Choice 2" = 2, "Choice 3" = 3), selected = 1)),
    
    column(3, 
      sliderInput("slider1", label = h3("Sliders"), min = 0, max = 100, value = 50),
      sliderInput("slider2", "", min = 0, max = 100, value = c(25, 75))
      ),
    
    column(3, 
      textInput("text", label = h3("Text input"), value = "Enter text..."))   
  )

))

4.1 Displaying R output in Shiny

For the MA plot to appear in our Shiny app, we need to:

• Add the plot to the user interface definition in ui.R.
• Tell Shiny how to render the plot in server.R.

# ui.R

size = 450

shinyUI(fluidPage(
  titlePanel("MA plot explorer"),

  splitLayout(cellWidths=size,
    plotOutput("plotma", width=size, height=size)
  )
  
))

# server.R

library(DESeq2)

load("data.rda")
res <- results(dds)

ymax <- 5

shinyServer(function(input, output) {
  
  # MA-plot
  output$plotma <- renderPlot({
    par( mar=c(5,5,3,2), cex.main=1.5, cex.lab=1.35 )
    plotMA( res, ylim=c(-ymax, ymax) )
  })
  
})

4.2 Reactive output using widget values

At this stage, when you launch your app, it will just display a static MA plot. The function plotMA has an argument alpha setting the significance level for thresholding adjusted p-values. We will now extend the app by adding a slider widget controlling this parameter.

First, let’s add a slider widget below our plot output:

# ui.R

size = 450

shinyUI(fluidPage(
  titlePanel("MA plot explorer"),

  splitLayout(cellWidths=size,
    plotOutput("plotma", width=size, height=size)
  ),
  splitLayout(cellWidths=size,
    sliderInput("alpha", "Adjusted p-value treshold",
                min=0, max=0.2, value=0.1, step=0.001, width=size)
  )
  
))

The slider allows to select values in the range from 0 to 0.2 in steps of 0.001, and we have set its width to match the size of the plot above it.

You can make the plot reactive by asking Shiny to call the slider value when it builds the plot. Let’s look at how to do this.

Take a look at the first line of code in server.R. Do you notice that the unnamed function mentions two arguments, namely input and output? You already saw that output is a list-like object that stores instructions for building the R objects in your app.

input is a second list-like object. It stores the current values of all of the widgets in your app. These values will be saved under the widgets’ names from ui.R.

So for example, our app has one widget named "alpha", whose value will be stored in input$alpha. Shiny automatically makes an object reactive if the object uses an input value. In order to make the MA plot reactive, substitute in your server.R script the line containing the call to plotMA by the following one:

plotMA( res, ylim=c(-ymax, ymax), alpha=input$alpha )

When you are ready updating the ui.R and server.R files, launch your Shiny app. The plot should redraw instantly as you move the slider.

Shiny tracks which outputs depend on which widgets. When a user changes a widget, Shiny will rebuild all of the outputs that depend on this widget, using the new value of the widget. As a result, the rebuilt objects will be completely up-to-date.

This is how you create reactivity with Shiny, by connecting the values of input to the objects in output. Shiny takes care of all of the other details.

4.3 Reactivity

Finally, we will make the MA plot clickable allowing to select a gene, and add the counts plot for the selected gene.

We start by adding the counts plot next to the MA plot, so that the ui.R script matches the following:

# ui.R

size = 450

shinyUI(fluidPage(
  titlePanel("MA plot explorer"),

  splitLayout(cellWidths=size,
    plotOutput("plotma", click="plotma_click", width=size, height=size),
    plotOutput("plotcounts", width=size, height=size)
  ),
  splitLayout(cellWidths=size,
    sliderInput("alpha", "Adjusted p-value treshold",
                min=0, max=0.2, value=0.1, step=0.001, width=size)
  )
  
))

Notice the additional click argument to the plotOutput function of the MA plot. If set to a value like plotma_click, the plot will send coordinates to the server whenever it is clicked. This value will be accessible via input$plotma_click and will contain a named list with x and y elements indicating the mouse position. We will use the input$plotma_click coordinates to resolve the nearest gene in the MA plot.

Let’s get back to our server.R script. In order to be able to resolve which point in the MA plot was the closest one to the click, we create the t.data.scaled object containing points in normalized coordinates. We will use that object to find the closest point in terms of euclidean distance.

# server.R

library(DESeq2)

load("data.rda")
res <- results(dds)

ymax <- 5

# this object will be used to locate points from click events.
data <- with(res, cbind(baseMean, log2FoldChange))
data[,2] <- pmin(ymax, pmax(-ymax, data[,2]))
scale <- c(diff(range(data[,1])), 2*ymax)
t.data.scaled <- t(data)/scale

shinyServer(function(input, output) {
  
  current = reactiveValues(idx = NULL)
  
  observe({
    xy = c(input$plotma_click$x, input$plotma_click$y)
    if (!is.null(xy)) {
      ## find index of the closest point
      sqdists <- colMeans( (t.data.scaled - xy/scale )^2 )
      current$idx <- which.min(sqdists)
    }
  })
  
  # MA-plot
  output$plotma <- renderPlot({
    par( mar=c(5,5,3,2), cex.main=1.5, cex.lab=1.35 )
    plotMA( res, ylim=c(-ymax, ymax), alpha=input$alpha )
    # add a circle around the selected point
    idx = current$idx
    if (!is.null(idx)) points( data[idx,1], data[idx,2], col="dodgerblue", cex=3, lwd=3 )
  })
  
  # counts plot for the selected gene
  output$plotcounts <- renderPlot({
    par( mar=c(5,5,3,2), cex.main=1.5, cex.lab=1.35 )
    # update only when idx changes
    idx = current$idx
    if (!is.null(idx)) plotCounts( dds, idx, intgroup=c("dex") )
  })

})

Apart from the updated renderPlot functions responsible for plotting, there are some other important additions to our Shiny app. Namely, we have used a reactiveValues object and an observer to streamline the app.

4.4 Dependencies

What happens if you click on the MA plot?

This will make both plots drawn by renderPlot out of date, even though they don’t depend directly on input$plotma_click. Shiny will know that they became outdated and will redraw the plots because it keeps track of which reactive values an output object depends on. Shiny will automatically re-build an object if an reactive/input value in the object’s render* function changes.

5.1 Share as R files

Anyone with R can run your Shiny app. They will need a copy of your server.R and ui.R files, as well as any supplementary materials used in your app (e.g., www folders or any helper R scripts). The user can place these files into an app directory and launch the app in R with the same commands you used on your computer, e.g. runApp.

Additionally, Shiny provides three built in commands that make it easy to use files that are hosted online: runUrl, runGitHub, and runGist.

runUrl( "<the weblink>" )

runGitHub( "<your user name>/<your repository name>" ) 

runGist("3239667")

5.2 Share as a web page

All of the above methods share the same limitation: they require your user to have R and Shiny installed on their computer. However, Shiny creates the perfect opportunity to share output with people who do not have R (and have no intention of getting it). Your Shiny app happens to be one of the most widely used communication tools in the world: a web page. If you host the app at its own URL, users can visit the app (and not need to worry about code).

RStudio offers three ways to host your Shiny app as a web page:

• Shinyapps.io
• Shiny Server, and
• Shiny Server Pro