Skip to contents

The following is an example of usage of the widget in a Shiny app.

First, install the dependencies:

install.packages("shiny")
install.packages("devtools")
devtools::install_github("vitessce/vitessce-r")
devtools::install_github('satijalab/seurat-data')

Next, create an output element in the UI with vitessce_output and a corresponding server response with render_vitessce.

The value for the output_id parameter in the vitessce_output function should match the key for the result of render_vitessce in the server.

library(shiny)
library(vitessce)
library(SeuratData)

SeuratData::InstallData("pbmc3k")
data("pbmc3k.final")
force(pbmc3k.final)

ui <- fluidPage(
  "Vitessce in a Shiny app",
  vitessce_output(output_id = 'vitessce_visualization', height = "600px"),
)

server <- function(input, output, session) {
  output$vitessce_visualization <- render_vitessce(expr = {
    vc <- VitessceConfig$new("My config")
    dataset <- vc$add_dataset("My dataset")
    dataset <- dataset$add_object(SeuratWrapper$new(pbmc3k.final))
    scatterplot <- vc$add_view(dataset, Component$SCATTERPLOT, mapping = "pca")
    vc$layout(scatterplot)
    vc$widget()
  })
}

shinyApp(ui, server)

When running the Shiny app, the Vitessce widget will take a few seconds to appear on the screen. We plan to optimize the internal widget data preparation and conversion functions to reduce this delay.

Shiny apps on remote servers

When running a Shiny app on a remote server, you will need to use the base_url parameter of the vc$widget() function. When a value for base_url is provided, the default http://localhost base URL will be overridden, allowing the client of the Shiny app to be running on a different computer than the Shiny server.

You also may want to serve the Vitessce widget data files through a custom static web server rather than the built-in R plumber web server (either for security or scalability reasons). To do so, be sure to set the parameter out_dir when calling the SeuratWrapper$new() constructor. This will allow you to specify the output directory for the converted Vitessce data files. Then, you can set the parameter serve to FALSE in vc$widget() to prevent the built-in plumber server from starting when you launch the widget.

For example, if you know that your Shiny server will be running at http://example.com/shiny and you want to turn off the plumber server, then you would call vc$widget(base_url = "http://example.com/shiny", serve = FALSE).

The following example demonstrates swapping out the Vitessce widget's built-in server for Shiny's addResourcePath:

library(shiny)
library(vitessce)
library(SeuratData)

SeuratData::InstallData("pbmc3k")
data("pbmc3k.final")
force(pbmc3k.final)

OUT_DIR <- "./my_vitessce_files"

ui <- fluidPage(
  "Vitessce in a Shiny app",
  vitessce_output(output_id = 'vitessce_visualization', height = "600px"),
)

server <- function(input, output, session) {
  addResourcePath("vitessce", OUT_DIR)
  output$vitessce_visualization <- render_vitessce(expr = {
    vc <- VitessceConfig$new("My config")
    dataset <- vc$add_dataset("My dataset")
    dataset <- dataset$add_object(SeuratWrapper$new(pbmc3k.final, out_dir = OUT_DIR))
    scatterplot <- vc$add_view(dataset, Component$SCATTERPLOT, mapping = "pca")
    vc$layout(scatterplot)
    
    BASE_URL <- paste0(
      session$clientData$url_protocol,
      "//",
      session$clientData$url_hostname,
      ":",
      session$clientData$url_port,
      "/vitessce"
    )

    vc$widget(serve = FALSE, base_url = BASE_URL)
  })
}

shinyApp(ui, server)

Style issues

By default, Shiny includes CSS from bootstrap in all apps. The bootstrap styles (font sizes in particular) can interfere with the styles for the Vitessce widget.

One solution is add CSS to reset the font sizes for the root element of the Shiny app:

library(shiny)
library(vitessce)
library(SeuratData)

SeuratData::InstallData("pbmc3k")
data("pbmc3k.final")
force(pbmc3k.final)

ui <- fluidPage(
  tags$head(
    tags$style(HTML("
      html, body {
        font-size: inherit;
      }
    "))
  ),
  "Vitessce in a Shiny app",
  vitessce_output(output_id = 'vitessce_visualization', height = "600px"),
)

server <- function(input, output, session) {
  output$vitessce_visualization <- render_vitessce(expr = {
    vc <- VitessceConfig$new("My config")
    dataset <- vc$add_dataset("My dataset")
    dataset <- dataset$add_object(SeuratWrapper$new(pbmc3k.final))
    scatterplot <- vc$add_view(dataset, Component$SCATTERPLOT, mapping = "pca")
    vc$layout(scatterplot)
    vc$widget()
  })
}

shinyApp(ui, server)