Hands-on workshop recipes

Kevin Rue-Albrecht, Charlotte Soneson, Federico Marini, and Aaron Lun

December 16, 2020

Source: vignettes/recipes.Rmd

Introduction

This vignette consists of a series of (independent) hands-on recipes, aimed at exploring the capabilities of iSEE both interactively and programmatically. Each recipe consists of a short task and a screen shot of the desired appearance of the app instance that should be created. For each recipe, we provide a set of hints, as well as detailed instructions on how to solve the task both interactively (by clicking in the app) and programmatically (by directly setting up and launching the desired app instance).

For a general overview of the default iSEE panels, we refer to the overview vignette. For all the details about the panel classes and the associated slots, we refer to the help pages for the respective panel class (e.g., ?ReducedDimensionPlot).

Prepare the session

Before starting with the recipes, we need to load the required packages and the demo data set.

library(iSEE)
library(iSEEu)
library(iSEEWorkshopEuroBioc2020)
sce <- load_demo_sce("pbmc3k")
sce
#> class: SingleCellExperiment 
#> dim: 32738 2643 
#> metadata(0):
#> assays(2): counts logcounts
#> rownames(32738): MIR1302-10 FAM138A ... AC002321.2 AC002321.1
#> rowData names(21): ENSEMBL_ID Symbol_TENx ... FDR_cluster13
#>   FDR_cluster14
#> colnames(2643): Cell1 Cell2 ... Cell2699 Cell2700
#> colData names(23): Sample Barcode ... labels_fine labels_ont
#> reducedDimNames(3): PCA TSNE UMAP
#> altExpNames(0):

Recipe 1: Panel organisation

Using the pbmc3k data set, create an app that contains only a reduced dimension plot panel, a row data plot panel and a column data plot panel. The widths of the three panels should be 3, 4 and 5 units, respectively.

Hints
  • Panels can be added, removed and resized via the Organization button in the top right corner of the app.
  • To pre-specify the panels to be included in the app, use the initial argument to iSEE().
  • You can remind yourself of the list of slot names available for each panel class and their respective value using the str() function on any instance of a panel object, e.g. str(ReducedDimensionPlot()).
  • For more information about the different types of panels, see the overview vignette or the help pages for the respective panel classes.
Solution (interactively)
  • First open an application with the default set of panels. 
    • app <- iSEE(sce)
shiny::runApp(app)
  • Click on the Organization button in the top right corner of the app, and then click on Organize panels.
  • In the pop-up window that appears, click on the little x next to all the panels that you want to remove (all but the Reduced dimension plot 1, Column data plot 1 and Row data plot 1).
  • Drag and drop the remaining three panel names in the correct order.
  • For each panel, set the correct panel width by modifying the value in the Width dropdown menu.
  • Click Apply settings.

Solution (programmatically)

app <- iSEE(sce, initial = list(
  ReducedDimensionPlot(PanelWidth = 3L),
  RowDataPlot(PanelWidth = 4L),
  ColumnDataPlot(PanelWidth = 5L)
))

Recipe 2: Data parameters configuration - selecting columns to display

Using the pbmc3k data set, visualize the cell type assignment against the cluster membership, with the aim to identify the predominant cell type in each cluster. In this case, since both cell annotations are categorical, iSEE will generate a so called Hinton plot.

Hints
  • Column (in this case cell) annotations can be visualized using a ColumnDataPlot panel.
  • The cluster labels are available in the Cluster column of colData(sce).
  • The cell type assignments are available in the labels_fine column of colData(sce) (more coarse-grained assignments are provided in the labels_main column).
  • iSEE will automatically determine the plot type depending on the type of selected variables.
Solution (interactively)
  • First open an application with a single ColumnDataPlot panel spanning the full application window) 
    • app <- iSEE(sce, initial = list(ColumnDataPlot(PanelWidth = 12L)))
shiny::runApp(app)
  • In the ColumnDataPlot panel, click to expand the Data parameters collapsible box.
  • Under Column of interest (Y-axis), select the label column (e.g., labels_fine).
  • Under X-axis, select Column data, and under Column of interest (X-axis), select Cluster.

Solution (programmatically)

app <- iSEE(sce, list(
    ColumnDataPlot(PanelWidth = 12L, XAxis = "Column data",
                   YAxis = "labels_fine", XAxisColumnData = "Cluster")
))

Recipe 3: Data parameters configuration - displaying multiple reduced dimension representations

Using the pbmc3k data set, display both the tSNE and UMAP representations next to each other.

Hints
  • Reduced dimension representations can be displayed using ReducedDimensionPlot panels.
  • The reduced dimension representations in the SingleCellExperiment object can be accessed by name (reducedDimNames(sce) lists the available representations).
Solution (interactively)
  • First open an application with two ReducedDimensionPlot panels, each spanning half the application window) 
    • app <- iSEE(sce, initial = list(ReducedDimensionPlot(PanelWidth = 6L),
                                ReducedDimensionPlot(PanelWidth = 6L)))
shiny::runApp(app)
  • In the first ReducedDimensionPlot panel, click to expand the Data parameters collapsible box.
  • In the Type selection box, choose TSNE.
  • In the second ReducedDimensionPlot panel, repeat the procedure but instead select UMAP.

Solution (programmatically)

app <- iSEE(sce, initial = list(
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE"),
    ReducedDimensionPlot(PanelWidth = 6L, Type = "UMAP")
))

Recipe 4: Data parameters configuration - displaying the expression of a specific gene across clusters

Using the pbmc3k data set, plot the distribution of the logcount values for the gene CD74 in each of the clusters.

Hints
  • Gene expression values can be displayed using a FeatureAssayPlot panel.
  • To select a gene, specify the ID provided as row names in the SingleCellExperiment.
Solution (interactively)
  • First open an application with a FeatureAssayPlot panel, spanning the full application window) 
    • app <- iSEE(sce, initial = list(FeatureAssayPlot(PanelWidth = 12L)))
shiny::runApp(app)
  • In the FeatureAssayPlot panel, click to expand the Data parameters collapsible box.
  • Under Y-axis feature, type or select CD74.
  • Under X-axis, select Column data, and under Column of interest (X-axis), select Cluster.

Solution (programmatically)

app <- iSEE(sce, initial = list(
    FeatureAssayPlot(PanelWidth = 12L, XAxis = "Column data",
                     YAxisFeatureName = "CD74", XAxisColumnData = "Cluster")
))

Recipe 5: Visual parameters configuration - coloring reduced dimension representations by cell annotation

Using the pbmc3k data set, display two tSNE representations next to each other. In the first one, color the cells by the cluster label. In the second one, color the cells by the log10 of the total UMI count (log10_total column of colData(sce)).

Hints
  • Reduced dimension representations can be displayed using ReducedDimensionPlot panels.
  • The reduced dimension representations in the SingleCellExperiment object can be accessed by name (reducedDimNames(sce) lists the available representations).
  • The cluster labels are available in the Cluster column of colData(sce).
  • Point attributes can be accessed in the Visual parameters collapsible box. To display or hide the possible options, check the corresponding checkboxes (Color, Shape, Size, Point).
Solution (interactively)
  • First open an application with two ReducedDimensionPlot panels, each spanning half the application window) 
    • app <- iSEE(sce, initial = list(ReducedDimensionPlot(PanelWidth = 6L),
                                ReducedDimensionPlot(PanelWidth = 6L)))
shiny::runApp(app)
  • In each ReducedDimensionPlot panel, click to expand the Data parameters collapsible box and under Type, choose TSNE.
  • In the first ReducedDimensionPlot panel, click to expand the Visual parameters collapsible box.
  • Make sure that the Color checkbox is ticked.
  • Under Color by, select Column data.
  • In the dropdown menu that appears, select Cluster.
  • In the second ReducedDimensionPlot panel, repeat the procedure but instead select log10_total.

Solution (programmatically)

app <- iSEE(sce, initial = list(
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         ColorBy = "Column data",
                         ColorByColumnData = "Cluster"),
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         ColorBy = "Column data",
                         ColorByColumnData = "log10_total")
))

Recipe 6: Visual parameters configuration - coloring reduced dimension representations by gene expression

Using the pbmc3k data set, display two tSNE representations next to each other. In the first one, color the cells by the logcounts expression level of CD3D. In the second one, color the cells by the logcounts expression level of CD79B.

Hints
  • Reduced dimension representations can be displayed using ReducedDimensionPlot panels.
  • The reduced dimension representations in the SingleCellExperiment object can be accessed by name (reducedDimNames(sce) lists the available representations).
  • To select a gene, specify the ID provided as row names in the SingleCellExperiment.
  • Point attributes can be accessed in the Visual parameters collapsible box. To display or hide the possible options, check the corresponding checkboxes (Color, Shape, Size, Point).
Solution (interactively)
  • First open an application with two ReducedDimensionPlot panels, each spanning half the application window) 
    • app <- iSEE(sce, initial = list(ReducedDimensionPlot(PanelWidth = 6L),
                                ReducedDimensionPlot(PanelWidth = 6L)))
shiny::runApp(app)
  • In each ReducedDimensionPlot panel, click to expand the Data parameters collapsible box and under Type, choose TSNE.
  • In the first ReducedDimensionPlot panel, click to expand the Visual parameters collapsible box.
  • Make sure that the Color checkbox is ticked.
  • Under Color by, select Feature name.
  • In the dropdown menu that appears, select or type CD3D.
  • In the second ReducedDimensionPlot panel, repeat the procedure but instead select CD79B.

Solution (programmatically)

app <- iSEE(sce, initial = list(
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         ColorBy = "Feature name",
                         ColorByFeatureName = "CD3D"),
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         ColorBy = "Feature name",
                         ColorByFeatureName = "CD79B")
))

Recipe 7: Visual parameters configuration - changing the size and opacity of points

Using the pbmc3k data set, display two tSNE representations next to each other. In the first one, set the point size to 0.5. In the second one, set the point size to 3 and the opacity to 0.2.

Hints
  • Reduced dimension representations can be displayed using ReducedDimensionPlot panels.
  • The reduced dimension representations in the SingleCellExperiment object can be accessed by name (reducedDimNames(sce) lists the available representations).
  • Point attributes can be accessed in the Visual parameters collapsible box. To display or hide the possible options, check the corresponding checkboxes (Color, Shape, Size, Point).
Solution (interactively)
  • First open an application with two ReducedDimensionPlot panels, each spanning half the application window) 
    • app <- iSEE(sce, initial = list(ReducedDimensionPlot(PanelWidth = 6L),
                                ReducedDimensionPlot(PanelWidth = 6L)))
shiny::runApp(app)
  • In each ReducedDimensionPlot panel, click to expand the Data parameters collapsible box and under Type, choose TSNE.
  • In the first ReducedDimensionPlot panel, click to expand the Visual parameters collapsible box.
  • Make sure that the Size checkbox is ticked.
  • Under Size by, select None.
  • In the text box underneath, type 0.5.
  • In the second ReducedDimensionPlot panel, click to expand the Visual parameters collapsible box.
  • Make sure that the Size and Point checkboxes are ticked.
  • Under Size by, select None.
  • In the text box underneath, type 3.
  • Under Point opacity, drag the slider to 0.2.

Solution (programmatically)

app <- iSEE(sce, initial = list(
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         PointSize = 0.5),
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         PointSize = 3, PointAlpha = 0.2)
))

Recipe 8: Selection configuration

Using the pbmc3k data set, display the expression (logcounts) of CD3D across the assigned clusters, as well as a tSNE representation colored by the cluster label. Select all cells with a logcount expression value of CD3D between (approximately) 0.5 and 4, and highlight these in the tSNE plot by means of transparency.

Hints
  • Reduced dimension representations can be displayed using ReducedDimensionPlot panels.
  • The reduced dimension representations in the SingleCellExperiment object can be accessed by name (reducedDimNames(sce) lists the available representations).
  • Gene expression values can be displayed using a FeatureAssayPlot panel.
  • To select a gene, specify the ID provided as row names in the SingleCellExperiment.
  • Transmission of selections is set up in the Selection parameters collapsible box.
  • Points can be selected by clicking and dragging the mouse to draw a rectangle around them, or by repeatedly clicking to make a lasso (free-form) selection.
Solution (interactively)
  • First open an application with one FeatureAssayPlot panel and one ReducedDimensionPlot panel, each spanning half the application window) 
    • app <- iSEE(sce, initial = list(FeatureAssayPlot(PanelWidth = 6L),
                                ReducedDimensionPlot(PanelWidth = 6L)))
shiny::runApp(app)
  • In the FeatureAssayPlot panel, click to expand the Data parameters collapsible box and under Y-axis feature, type or select CD3D.
  • Under X-axis, select Column data, and under X-axis column data, select Cluster.
  • In the FeatureAssayPlot panel, use the mouse to drag a rectangle around all points with a logcount expression value (y-axis) between approximately 0.5 and 4.
  • In the ReducedDimensionPlot panel, click to expand the Data parameters collapsible box and under Type, choose TSNE.
  • In the ReducedDimensionPlot panel, further click to expand the Visual parameters collapsible box, make sure that the Color checkbox is ticked. Under Color by, select Column data. In the dropdown menu that appears, type or select Cluster.
  • In the ReducedDimensionPlot panel, click to expand the Selection parameters collapsible box.
  • Under Receive column selection from, select Feature assay plot 1.
  • Under Selection effect, make sure that Transparent is chosen.

Solution (programmatically)

app <- iSEE(sce, initial = list(
    FeatureAssayPlot(PanelWidth = 6L, 
                     BrushData = list(xmin = 0, xmax = 15, 
                                      ymin = 0.5, ymax = 4, 
                       mapping = list(x = "X", y = "Y", group = "GroupBy"), 
                       direction = "xy", 
                       brushId = "FeatureAssayPlot1_Brush", 
                       outputId = "FeatureAssayPlot1"),
                     XAxis = "Column data", 
                     XAxisColumnData = "Cluster", YAxisFeatureName = "CD3D"),
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         ColorBy = "Column data",
                         ColorByColumnData = "Cluster",
                         SelectionEffect = "Transparent", 
                         ColumnSelectionSource = "FeatureAssayPlot1")
))

Recipe 9: Verifying the cell type identity of clusters

Using the pbmc3k data set, create a scatter plots displaying the (logcounts) expression values of CD79A vs CD74, as well as a Hinton plot of the cluster and cell type assignment annotations. Select the cells co-expressing CD79A and CD74 in the scatter plot. Which cell type/cluster(s) do these correspond to (color these points in the Hinton plot)?

Hints
  • Gene expression values can be displayed using a FeatureAssayPlot panel.
  • To select a gene, specify the ID provided as row names in the SingleCellExperiment.
  • Column (in this case cell) annotations can be visualized using a ColumnDataPlot panel.
  • The cluster labels are available in the Cluster column of colData(sce). Coarse-grained cell type labels are available in the labels_main column.
  • Transmission of selections is set up in the Selection parameters collapsible box.
  • Points can be selected by clicking and dragging the mouse to draw a rectangle around them, or by repeatedly clicking to make a lasso (free-form) selection.
Solution (interactively)
  • First open an application with one FeatureAssayPlot panel and one ColumnDataPlot panel, each spanning half of the application window) 
    • app <- iSEE(sce, initial = list(FeatureAssayPlot(PanelWidth = 6L),
                                ColumnDataPlot(PanelWidth = 6L)))
shiny::runApp(app)
  • In the FeatureAssayPlot panel, click to expand the Data parameters collapsible box.
  • Under Y-axis feature, type or select CD79A.
  • Under X-axis, select Feature name, and under X-axis feature, type or select CD74.
  • In the ColumnDataPlot panel, click to expand the Data parameters collapsible box.
  • Under Column of interest (Y-axis), type or select labels_main.
  • Under X-axis, select Column data, and under Column of interest (X-axis), select Cluster.
  • In the FeatureAssayPlot panel, use the mouse to drag a rectangle around all points co-expressing CD79A and CD74.
  • In the ColumnDataPlot panel, click to expand the Selection parameters collapsible box.
  • Under Receive column selection from, select Feature assay plot 1.
  • Under Selection effect, make sure that Color is chosen.

Solution (programmatically)

app <- iSEE(sce, initial = list(
    FeatureAssayPlot(PanelWidth = 6L, XAxis = "Feature name",
                     YAxisFeatureName = "CD79A", 
                     XAxisFeatureName = "CD74",
                     BrushData = list(
                       xmin = 0.3, xmax = 7, 
                       ymin = 0.3, ymax = 7, 
                       mapping = list(x = "X", y = "Y", colour = "ColorBy"), 
                       direction = "xy", brushId = "FeatureAssayPlot1_Brush", 
                       outputId = "FeatureAssayPlot1")),
    ColumnDataPlot(PanelWidth = 6L, XAxis = "Column data", 
                   YAxis = "labels_main", 
                   XAxisColumnData = "Cluster",
                   ColumnSelectionSource = "FeatureAssayPlot1",
                   SelectionEffect = "Color")
))

Recipe 10: Using modes from iSEEu

Using the pbmc3k data set, load iSEEu and use the modeReducedDim mode to open an app displaying all the reduced dimension representations stored in the SingleCellExperiment object. Color the representations by the cell type assignment.

Hints
  • The cell type assignments are available in the labels_fine column of colData(sce) (more coarse-grained assignments are provided in the labels_main column).
  • The annotation to color by can be specified when calling iSEEu::modeReducedDim().

Solution (programmatically)

app <- modeReducedDim(sce, colorBy = "labels_main")

Recipe 11 - Including a tour

Using the pbmc3k data set, display two tSNE representations next to each other. In the first one, color the cells by the logcounts expression level of CD3D. In the second one, color the cells by the logcounts expression level of CD79B. Also include a small tour that starts with a welcome message, next walks through the two panels, giving an informative message for each, and finally ends with a concluding message to the user.

Hints
  • Reduced dimension representations can be displayed using ReducedDimensionPlot panels.
  • The reduced dimension representations in the SingleCellExperiment object can be accessed by name (reducedDimNames(sce) lists the available representations).
  • To select a gene, specify the ID provided as row names in the SingleCellExperiment.
  • Point attributes can be accessed in the Visual parameters collapsible box. To display or hide the possible options, check the corresponding checkboxes (Color, Shape, Size, Point).
  • Tours are provided via the tour argument to iSEE().
  • A tour is defined by a two-column data frame, with columns named element and intro. The element column contains the names of UI elements, prefixed by a hash sign. More details, including how to find the name of a particular UI elements, can be found in the Configuring iSEE apps vignette of iSEE.

Solution (programmatically)

tour <- data.frame(
    element = c(
        "#Welcome",
        "#ReducedDimensionPlot1",
        "#ReducedDimensionPlot2",
        "#Conclusion"),
    intro = c(
        "Welcome to this tour!",
        "This is the first reduced dimension plot",
        "And here is the second one",
        "Thank you for taking this tour!"),
    stringsAsFactors = FALSE)

app <- iSEE(sce, initial = list(
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         ColorBy = "Feature name",
                         ColorByFeatureName = "CD3D"),
    ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE",
                         ColorBy = "Feature name",
                         ColorByFeatureName = "CD79B")), 
    tour = tour)

Session info

sessionInfo()
#> R Under development (unstable) (2020-11-26 r79513)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 20.04.1 LTS
#> 
#> Matrix products: default
#> BLAS/LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.8.so
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=C             
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> attached base packages:
#> [1] parallel  stats4    stats     graphics  grDevices utils     datasets 
#> [8] methods   base     
#> 
#> other attached packages:
#>  [1] iSEEWorkshopEuroBioc2020_0.0.1 iSEEu_1.3.0                   
#>  [3] iSEE_2.3.3                     SingleCellExperiment_1.13.3   
#>  [5] SummarizedExperiment_1.21.1    Biobase_2.51.0                
#>  [7] GenomicRanges_1.43.1           GenomeInfoDb_1.27.3           
#>  [9] IRanges_2.25.5                 S4Vectors_0.29.6              
#> [11] BiocGenerics_0.37.0            MatrixGenerics_1.3.0          
#> [13] matrixStats_0.57.0             BiocStyle_2.19.1              
#> 
#> loaded via a namespace (and not attached):
#>  [1] nlme_3.1-150           bitops_1.0-6           fs_1.5.0              
#>  [4] RColorBrewer_1.1-2     rprojroot_2.0.2        tools_4.1.0           
#>  [7] R6_2.5.0               DT_0.16                vipor_0.4.5           
#> [10] mgcv_1.8-33            colorspace_2.0-0       GetoptLong_1.0.5      
#> [13] tidyselect_1.1.0       compiler_4.1.0         textshaping_0.2.1     
#> [16] Cairo_1.5-12.2         shinyjs_2.0.0          desc_1.2.0            
#> [19] DelayedArray_0.17.5    colourpicker_1.1.0     scales_1.1.1          
#> [22] pkgdown_1.6.1          systemfonts_0.3.2      stringr_1.4.0         
#> [25] digest_0.6.27          rmarkdown_2.6          XVector_0.31.1        
#> [28] pkgconfig_2.0.3        htmltools_0.5.0        fastmap_1.0.1         
#> [31] htmlwidgets_1.5.3      rlang_0.4.9            GlobalOptions_0.1.2   
#> [34] shiny_1.5.0            shape_1.4.5            generics_0.1.0        
#> [37] jsonlite_1.7.2         dplyr_1.0.2            RCurl_1.98-1.2        
#> [40] magrittr_2.0.1         GenomeInfoDbData_1.2.4 Matrix_1.2-18         
#> [43] Rcpp_1.0.5             munsell_0.5.0          lifecycle_0.2.0       
#> [46] stringi_1.5.3          yaml_2.2.1             rintrojs_0.2.2        
#> [49] zlibbioc_1.37.0        grid_4.1.0             promises_1.1.1        
#> [52] ggrepel_0.8.2          shinydashboard_0.7.1   crayon_1.3.4          
#> [55] miniUI_0.1.1.1         lattice_0.20-41        splines_4.1.0         
#> [58] circlize_0.4.11        knitr_1.30             ComplexHeatmap_2.7.1  
#> [61] pillar_1.4.7           igraph_1.2.6           rjson_0.2.20          
#> [64] glue_1.4.2             evaluate_0.14          BiocManager_1.30.10   
#> [67] png_0.1-7              vctrs_0.3.5            httpuv_1.5.4          
#> [70] gtable_0.3.0           purrr_0.3.4            clue_0.3-58           
#> [73] assertthat_0.2.1       ggplot2_3.3.2          xfun_0.19             
#> [76] mime_0.9               xtable_1.8-4           later_1.1.0.1         
#> [79] viridisLite_0.3.0      ragg_0.4.0             tibble_3.0.4          
#> [82] memoise_1.1.0          cluster_2.1.0          shinyWidgets_0.5.4    
#> [85] ellipsis_0.3.1         shinyAce_0.4.1