Contents

1 Overview

The iSEE package (Rue-Albrecht et al. 2018) provides a general and flexible framework for interactively exploring SummarizedExperiment objects. However, in many cases, more specialized panels are required for effective visualization of specific data types. The iSEEu package implements a collection of such dedicated panel classes that work directly in the iSEE application and can smoothly interact with other panels. This allows users to quickly parametrize bespoke apps for their data to address scientific questions of interest. We first load in the package:

library(iSEEu)

All the panels described in this document can be deployed by simply passing them into the iSEE() function via the initial= argument, as shown in the following examples.

2 Differential expression plots

To demonstrate the use of these panels, we will perform a differential expression analysis on the airway dataset with the edgeR package. We store the resulting statistics in the rowData of the SummarizedExperiment so that it can be accessed by iSEE panels.

library(airway)
data(airway)

library(edgeR)
y <- DGEList(assay(airway), samples=colData(airway))
y <- y[filterByExpr(y, group=y$samples$dex),]
y <- calcNormFactors(y)

design <- model.matrix(~dex, y$samples)
y <- estimateDisp(y, design)
fit <- glmQLFit(y, design)
res <- glmQLFTest(fit, coef=2)

tab <- topTags(res, n=Inf)$table
rowData(airway) <- cbind(rowData(airway), tab[rownames(airway),])

The MAPlot class creates a MA plot, i.e., with the log-fold change on the y-axis and the average expression on the x-axis. Features with significant differences in each direction are highlighted and counted on the legend. Users can vary the significance threshold and apply ad hoc filters on the log-fold change. This is a subclass of the RowDataPlot so points can be transmitted to other panels as multiple row selections. Instances of this class are created like:

ma.panel <- MAPlot(PanelWidth=6L)
app <- iSEE(airway, initial=list(ma.panel))

The VolcanoPlot class creates a volcano plot with the log-fold change on the x-axis and the negative log-p-value on the y-axis. Features with significant differences in each direction are highlighted and counted on the legend. Users can vary the significance threshold and apply ad hoc filters on the log-fold change. This is a subclass of the RowDataPlot so points can be transmitted to other panels as multiple row selections. Instances of this class are created like:

vol.panel <- VolcanoPlot(PanelWidth=6L)
app <- iSEE(airway, initial=list(vol.panel))

3 Dynamically recalculated panels

To demonstrate, we will perform a quick analysis of a small dataset from the scRNAseq package. This involves computing normalized expression values and low-dimensional results using the scater package.

library(scRNAseq)
sce <- ReprocessedAllenData(assays="tophat_counts")

library(scater)
sce <- logNormCounts(sce, exprs_values="tophat_counts")
sce <- runPCA(sce, ncomponents=4)
sce <- runTSNE(sce)

The DynamicReducedDimensionPlot class creates a scatter plot with a dimensionality reduction result, namely principal components analysis (PCA), \(t\)-stochastic neighbor embedding (\(t\)-SNE) or uniform manifold and approximate projection (UMAP). It does so dynamically on the subset of points that are selected in a transmitting panel, allowing users to focus on finer structure when dealing with a heterogeneous population. Calculations are performed using relevant functions from the scater package.

# Receives a selection from a reduced dimension plot.
dyn.panel <- DynamicReducedDimensionPlot(Type="UMAP", Assay="logcounts",
    ColumnSelectionSource="ReducedDimensionPlot1", PanelWidth=6L)

# NOTE: users do not have to manually create this, just 
# copy it from the "Panel Settings" of an already open app.
red.panel <- ReducedDimensionPlot(PanelId=1L, PanelWidth=6L,
    BrushData = list(
        xmin = -45.943, xmax = -15.399, ymin = -58.560, 
        ymax = 49.701, coords_css = list(xmin = 51.009, 
            xmax = 165.009, ymin = 39.009, 
            ymax = 422.009), coords_img = list(xmin = 66.313, 
            xmax = 214.514, ymin = 50.712, 
            ymax = 548.612), img_css_ratio = list(x = 1.300, 
            y = 1.299), mapping = list(x = "X", y = "Y"), 
        domain = list(left = -49.101, right = 57.228, 
            bottom = -70.389, top = 53.519), 
        range = list(left = 50.986, right = 566.922, 
            bottom = 603.013, top = 33.155), 
        log = list(x = NULL, y = NULL), direction = "xy", 
        brushId = "ReducedDimensionPlot1_Brush", 
        outputId = "ReducedDimensionPlot1"
    )
)

app <- iSEE(sce, initial=list(red.panel, dyn.panel))

The DifferentialStatisticsTable class dynamically computes basic differential statistics comparing assay values across groups of multiple selections in a transmitting panel. If only the active selection exists in the transmitting panel, a comparison is performed between the points in that selection and all unselected points. If saved selections are present, pairwise comparisons between the active selection and each saved selection is performed and the results are combined into a single table using the findMarkers() function from scran.

diff.panel <- DifferentialStatisticsTable(PanelWidth=8L, Assay="logcounts",
    ColumnSelectionSource="ReducedDimensionPlot1",)

# Recycling the reduced dimension panel above, adding a saved selection to
# compare to the active selection.
red.panel[["SelectionHistory"]] <- list(
    BrushData = list(
        xmin = 15.143, xmax = 57.228, ymin = -40.752, 
        ymax = 25.674, coords_css = list(xmin = 279.009, 
            xmax = 436.089, ymin = 124.009, 
            ymax = 359.009), coords_img = list(xmin = 362.716, 
            xmax = 566.922, ymin = 161.212, 
            ymax = 466.712), img_css_ratio = list(x = 1.300, 
            y = 1.299), mapping = list(x = "X", y = "Y"), 
        domain = list(left = -49.101, right = 57.228, 
            bottom = -70.389, top = 53.519), 
        range = list(left = 50.986, right = 566.922, 
            bottom = 603.013, top = 33.155), 
        log = list(x = NULL, y = NULL), direction = "xy", 
        brushId = "ReducedDimensionPlot1_Brush", 
        outputId = "ReducedDimensionPlot1"
    )
)
red.panel[["PanelWidth"]] <- 4L # To fit onto one line.

app <- iSEE(sce, initial=list(red.panel, diff.panel))

4 Gene set table

The GeneSetTable() class is a bit unusual in that its rows do not correspond to any dimension of the SummarizedExperiment. Rather, each row is a gene set (e.g., from GO or KEGG) that, upon click, transmits a multiple row selection to other panels. The multiple selection consists of all genes in the chosen gene set, allowing users to identify the positions of all genes in a pathway of interest on, say, a volcano plot. This is also a rare example of a panel that only transmits and does not receive any selections from other panels.

.setIdentifierType("ENSEMBL")
gset.tab <- GeneSetTable(Selected="GO:0002576", 
    Search="platelet", PanelWidth=6L)

# This volcano plot will highlight the genes in the selected gene set.
vol.panel <- VolcanoPlot(RowSelectionSource="GeneSetTable1",
    SelectionEffect="Color", PanelWidth=6L)

app <- iSEE(airway, initial=list(gset.tab, vol.panel))

5 App modes

iSEEu contains a number of “modes” that allow users to conveniently load an iSEE instance in one of several common configurations:

6 Contributing to iSEEu

If you want to contribute to the development of the iSEEu package, here is a quick step-by-step guide:

git clone https://github.com/[your_github_username]/iSEEu.git

That’s pretty much it!

Using example data sets

Example data sets can often be obtained from an ExperimentHub package (e.g. from the scRNAseq package for single-cell RNA-sequencing data), and should not be added to the iSEEu package.

Documenting, testing, coding style and conventions

  • If possible, please consider adding an example in the dedicated Roxygen preamble to show how to run each function
  • If possible, consider adding one or more unit tests - we use the testthat framework

We do follow some guidelines regarding the names given to variables, please abide to these for consistency with the rest of the codebase. Here are a few pointers:

  • Keep the indentation as it is in the initial functions already available (4-spaces indentation).
  • If writing text (e.g. in the vignette), please use one sentence per line - this makes git diff operations easier to check.
  • When choosing variable names, try to keep the consistency with what already is existing:
    • camelCase for modes and other functions
    • .function_name for internals
    • PanelClassName for panels
    • .genericFunction for the API
    • .scope1.scope2.name for variable names in the cached info

If you intend to understand more in depth the internals of the iSEE framework, consider checking out the bookdown resource we put together at https://isee.github.io/iSEE-book/

Looking for constants within iSEE

Many of the “global” variables that are used in several places in iSEE are defined in the constants.R script in iSEE. We suggest to use these constants rather than hardcoding (e.g.) column names in the panel specification data frames, to protect against potential future changes of the precise column names. To access a constant, use iSEE:::.constantName.

What if I need a custom panel type?

In addition to the eight standard panel types, custom panels are easily accommodated within iSEE applications. For a guide, see the corresponding vignette. For examples, see this repo.

Where can I find a comprehensive introduction to iSEE?

The iSEE package contains several vignettes detailing the main functionality. You can also take a look at this workshop. A compiled version from the Bioc2019 conference (based on Bioconductor release 3.10) is available here.

Session information

sessionInfo()
## R version 4.0.0 (2020-04-24)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.4 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.11-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.11-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [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] scater_1.16.0               ggplot2_3.3.0              
##  [3] scRNAseq_2.2.0              edgeR_3.30.0               
##  [5] limma_3.44.1                airway_1.8.0               
##  [7] iSEEu_1.0.1                 iSEE_2.0.0                 
##  [9] SingleCellExperiment_1.10.1 SummarizedExperiment_1.18.1
## [11] DelayedArray_0.14.0         matrixStats_0.56.0         
## [13] Biobase_2.48.0              GenomicRanges_1.40.0       
## [15] GenomeInfoDb_1.24.0         IRanges_2.22.1             
## [17] S4Vectors_0.26.0            BiocGenerics_0.34.0        
## [19] BiocStyle_2.16.0           
## 
## loaded via a namespace (and not attached):
##   [1] Rtsne_0.15                    ggbeeswarm_0.6.0             
##   [3] colorspace_1.4-1              rjson_0.2.20                 
##   [5] ellipsis_0.3.0                circlize_0.4.9               
##   [7] XVector_0.28.0                BiocNeighbors_1.6.0          
##   [9] GlobalOptions_0.1.1           clue_0.3-57                  
##  [11] DT_0.13                       bit64_0.9-7                  
##  [13] interactiveDisplayBase_1.26.0 AnnotationDbi_1.50.0         
##  [15] splines_4.0.0                 knitr_1.28                   
##  [17] jsonlite_1.6.1                cluster_2.1.0                
##  [19] dbplyr_1.4.3                  png_0.1-7                    
##  [21] shinydashboard_0.7.1          shiny_1.4.0.2                
##  [23] BiocManager_1.30.10           compiler_4.0.0               
##  [25] httr_1.4.1                    assertthat_0.2.1             
##  [27] Matrix_1.2-18                 fastmap_1.0.1                
##  [29] BiocSingular_1.4.0            later_1.0.0                  
##  [31] htmltools_0.4.0               tools_4.0.0                  
##  [33] rsvd_1.0.3                    igraph_1.2.5                 
##  [35] gtable_0.3.0                  glue_1.4.0                   
##  [37] GenomeInfoDbData_1.2.3        dplyr_0.8.5                  
##  [39] rappdirs_0.3.1                Rcpp_1.0.4.6                 
##  [41] vctrs_0.2.4                   nlme_3.1-147                 
##  [43] ExperimentHub_1.14.0          DelayedMatrixStats_1.10.0    
##  [45] rintrojs_0.2.2                xfun_0.13                    
##  [47] stringr_1.4.0                 irlba_2.3.3                  
##  [49] mime_0.9                      miniUI_0.1.1.1               
##  [51] lifecycle_0.2.0               shinyAce_0.4.1               
##  [53] AnnotationHub_2.20.0          zlibbioc_1.34.0              
##  [55] scales_1.1.0                  colourpicker_1.0             
##  [57] promises_1.1.0                RColorBrewer_1.1-2           
##  [59] ComplexHeatmap_2.4.2          yaml_2.2.1                   
##  [61] curl_4.3                      gridExtra_2.3                
##  [63] memoise_1.1.0                 stringi_1.4.6                
##  [65] RSQLite_2.2.0                 BiocVersion_3.11.1           
##  [67] BiocParallel_1.22.0           shape_1.4.4                  
##  [69] rlang_0.4.6                   pkgconfig_2.0.3              
##  [71] bitops_1.0-6                  evaluate_0.14                
##  [73] lattice_0.20-41               purrr_0.3.4                  
##  [75] htmlwidgets_1.5.1             bit_1.1-15.2                 
##  [77] tidyselect_1.0.0              magrittr_1.5                 
##  [79] bookdown_0.18                 R6_2.4.1                     
##  [81] DBI_1.1.0                     pillar_1.4.4                 
##  [83] withr_2.2.0                   mgcv_1.8-31                  
##  [85] RCurl_1.98-1.2                tibble_3.0.1                 
##  [87] crayon_1.3.4                  shinyWidgets_0.5.1           
##  [89] BiocFileCache_1.12.0          rmarkdown_2.1                
##  [91] viridis_0.5.1                 GetoptLong_0.1.8             
##  [93] locfit_1.5-9.4                grid_4.0.0                   
##  [95] blob_1.2.1                    digest_0.6.25                
##  [97] xtable_1.8-4                  httpuv_1.5.2                 
##  [99] munsell_0.5.0                 beeswarm_0.2.3               
## [101] viridisLite_0.3.0             vipor_0.4.5                  
## [103] shinyjs_1.1

References

Rue-Albrecht, Kevin, Federico Marini, Charlotte Soneson, and Aaron T. L. Lun. 2018. “ISEE: Interactive Summarizedexperiment Explorer.” F1000Research 7 (June). F1000 Research, Ltd.:741. https://doi.org/10.12688/f1000research.14966.1.