1 Introduction

iSEE is a Bioconductor package that provides an interactive Shiny-based graphical user interface for exploring data stored in SummarizedExperiment objects (Rue-Albrecht et al. 2018). Instructions to install the package are available here. Once installed, the package can be loaded and attached to your current workspace as follows:

library(iSEE)

If you have a SummarizedExperiment object11 Or an instance of a subclass, like a SingleCellExperiment object. named se, you can launch an iSEE app by running:

iSEE(se)

In this vignette, we demonstrate this process using the allen single-cell RNA-seq data set from the scRNAseq package. However, if you want to start playing with the app immediately, you can simply run:

example(iSEE, ask=FALSE)

2 Setting up the data

The allen data set contains expression values for 379 cells from the mouse visual cortex (Tasic et al. 2016). To begin with, we load and inspect the allen object.

library(scRNAseq)
data(allen)
allen
#> class: SummarizedExperiment 
#> dim: 20908 379 
#> metadata(2): SuppInfo which_qc
#> assays(4): tophat_counts cufflinks_fpkm rsem_counts rsem_tpm
#> rownames(20908): 0610007P14Rik 0610009B22Rik ... Zzef1 Zzz3
#> rowData names(0):
#> colnames(379): SRR2140028 SRR2140022 ... SRR2139341 SRR2139336
#> colData names(22): NREADS NALIGNED ... Animal.ID passes_qc_checks_s

As provided, the allen object contains raw data and a number of quality control and experimental cell annotations, all available in colData(allen).

colnames(colData(allen))
#>  [1] "NREADS"                       "NALIGNED"                    
#>  [3] "RALIGN"                       "TOTAL_DUP"                   
#>  [5] "PRIMER"                       "PCT_RIBOSOMAL_BASES"         
#>  [7] "PCT_CODING_BASES"             "PCT_UTR_BASES"               
#>  [9] "PCT_INTRONIC_BASES"           "PCT_INTERGENIC_BASES"        
#> [11] "PCT_MRNA_BASES"               "MEDIAN_CV_COVERAGE"          
#> [13] "MEDIAN_5PRIME_BIAS"           "MEDIAN_3PRIME_BIAS"          
#> [15] "MEDIAN_5PRIME_TO_3PRIME_BIAS" "driver_1_s"                  
#> [17] "dissection_s"                 "Core.Type"                   
#> [19] "Primary.Type"                 "Secondary.Type"              
#> [21] "Animal.ID"                    "passes_qc_checks_s"

Then, we convert the provided SummarizedExperiment object to a SingleCellExperiment object and normalize the expression values with scater.

library(scater)
sce <- as(allen, "SingleCellExperiment")
counts(sce) <- assay(sce, "tophat_counts")
sce <- normalize(sce)

Next, we apply PCA and t-SNE to generate two low-dimensional representations of the cells. The dimensionality reduction results are stored in reducedDim(sce). Note that all computations (e.g., dimension reduction, clustering) must be performed before passing the object to the iSEE function.

sce <- runPCA(sce)
sce <- runTSNE(sce)
reducedDimNames(sce)
#> [1] "PCA"  "TSNE"

At this point, the sce object does not contain any annotations for the rows (i.e., features) in the data set. Thus, to prepare a fully-featured example application, we also add some gene metadata to the rowData related to the mean-variance relationship in the data.

rowData(sce)$mean_log <- rowMeans(logcounts(sce))
rowData(sce)$var_log <- apply(logcounts(sce), 1, var)

It is important to note that iSEE relies solely22 Except when dealing with custom panels. on precomputed values in the SummarizedExperiment object. This allows users to visualize any metrics of interest, but also requires them to do so before the initialization of the app. That said, it is straightforward to iteratively explore a precomputed object, take notes of new metrics to compute, close the app, store new results in the SummarizedExperiment object, and launch a new app using the updated object.

3 Launching the interface

To begin the exploration, we create an iSEE app with the SingleCellExperiment object generated above. In its simplest form, the iSEE function only requires the input object. However, iSEE applications can be extensively reconfigured using a number of optional arguments to the iSEE function.

app <- iSEE(sce)

The runApp function launches the app in our browser.

shiny::runApp(app)

By default, the app starts with a dashboard that contains one panel or table of each type. By opening the collapsible panels named “Data parameters”, “Visual parameters”, and “Selection parameters” under each plot, we can control the content and appearance of each panel.

Now, look in the upper right corner for a question mark icon (), and click on the hand button () for an introductory tour. This will perform an interactive tour of the app, based on the rintrojs package (Ganz 2016). During this tour, you will be taken through the different components of the iSEE user interface and learn the basic usage mechanisms by doing small actions guided by the tutorial: the highlighted elements will be responding to your actions, while the rest of the UI will be shaded. You can move forward and backward along the tour by clicking on the “Next”/“Back” buttons, or also using the arrow keys. You can even jump to a particular step by clicking on its circle. To exit the tour, either click on “Skip”, or simply click outside of the highlighted UI element.

Once you are done generating plots, click on the wrench icon () in the upper right corner, and click on the magic wand button () to display R code that you can export and directly re-use in your R session. This will open a modal popup where the R code used to generate the plots is displayed in a shinyAce-based text editor. Select parts or all of it to copy-and-paste it into your analysis script/Rmarkdown file. However, note that the order in which the code blocks are reported is important if you have linked panels to one another, as the panels sending point selections must be executed before those that receive the corresponding selection.

4 Description of the user interface

5 Description of iSEE functionality

6 FAQ

Q: Can you implement a ‘Copy to clipboard’ button in the code editor?

A: This is not necessary, as one can click anywhere in the code editor and instantly select all the code using a keyboard shortcut that depends on your operating system.

Q: When brushing with a transparency effect, it seems that data points in the receiving plot are not made transparent/subsetted correctly.

A: What you see is an artefact of overplotting: in areas excessively dense in points, transparency ceases to be an effective visual effect.

Q: Brushing on violin or square plots doesn’t seem to select anything.

A: For violin plots, points will be selected only if the brushed area includes the center of the x-tick, i.e., the center of the violin plot. This is intentional as it allows easy selection of all points in complex grouped violin plots. Indeed, the location of a specific point on the x-axis has no meaning. The same logic applies to the square plots, where only the center of each square needs to be selected to obtain all the points in the square.

Q: I’d like to try iSEE but I can’t install it/I just want a quick peek. Is there something you can do?

A: We set up an instance of iSEE running on the allen dataset at this address: http://shiny.imbei.uni-mainz.de:3838/iSEE. A range of interactive tours showcasing a variety of data types is also available here: https://github.com/LTLA/iSEE2018. Please keep in mind this is only for demonstration purposes, yet those instances show how you or your system administrator can setup iSEE for analyzing and/or sharing your SummarizedExperiment/SingleCellExperiment precomputed object.

7 Additional information

Bug reports can be posted on the Bioconductor support site or raised as issues in the iSEE GitHub repository. The GitHub repository also contains the development version of the package, where new functionality is added over time. The authors appreciate well-considered suggestions for improvements or new features, or even better, pull requests.

If you use iSEE for your analysis, please cite it as shown below:

citation("iSEE")
#> 
#> Rue-Albrecht K, Marini F, Soneson C, Lun ATL (2018). "iSEE:
#> Interactive SummarizedExperiment Explorer." _F1000Research_, *7*,
#> 741. doi: 10.12688/f1000research.14966.1 (URL:
#> https://doi.org/10.12688/f1000research.14966.1).
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Article{,
#>     title = {iSEE: Interactive SummarizedExperiment Explorer},
#>     author = {Kevin Rue-Albrecht and Federico Marini and Charlotte Soneson and Aaron T. L. Lun},
#>     publisher = {F1000 Research, Ltd.},
#>     journal = {F1000Research},
#>     year = {2018},
#>     month = {Jun},
#>     volume = {7},
#>     pages = {741},
#>     doi = {10.12688/f1000research.14966.1},
#>   }