Compiled date: r Sys.Date()

Last edited: 2020-04-20

License: r packageDescription("iSEE")[["License"]]

knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    error = FALSE,
    warning = FALSE,
    message = FALSE,
    crop = NULL
)
stopifnot(requireNamespace("htmltools"))
htmltools::tagList(rmarkdown::html_dependency_font_awesome())
SCREENSHOT <- function(x, ...) knitr::include_graphics(x, dpi = NA)
knitr::include_graphics(path = system.file(package="iSEE", "www/iSEE.png", mustWork=TRUE))

Introduction

r Biocpkg("iSEE") is a Bioconductor package that provides an interactive Shiny-based graphical user interface for exploring data stored in SummarizedExperiment objects [@kra2018iSEE]. Instructions to install the package are available r Biocpkg("iSEE", label = "here"). Once installed, the package can be loaded and attached to your current workspace as follows:

library(iSEE)

If you have a SummarizedExperiment object^[Or an instance of a subclass, like a SingleCellExperiment object.] named se, you can launch an r Biocpkg("iSEE") app by running:

iSEE(se)

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

example(iSEE, ask=FALSE)

Setting up the data

The allen data set contains expression values for 379 cells from the mouse visual cortex [@tasic2016adult], and can be loaded directly by calling ReprocessedAllenData() and specifying the value for the assays parameter. To begin with, we assign the output of this call to an sce object and inspect it.

library(scRNAseq)
sce <- ReprocessedAllenData(assays = "tophat_counts")   # specifying the assays to speed up the example
sce

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

colnames(colData(sce))

Then, we normalize the expression values with r Biocpkg("scater").

library(scater)
sce <- logNormCounts(sce, exprs_values="tophat_counts")

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).

set.seed(1000)
sce <- runPCA(sce)
sce <- runTSNE(sce)
reducedDimNames(sce)

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 primarily on precomputed values stored in the various slots of objects derived from the SummarizedExperiment class^[Except when dealing with r Biocpkg("iSEE", vignette="custom.html", label="custom panels").]. This allows users to visualize any metrics of interest, but also requires these to be calculated and added to the object 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.

# Saving and reloading so we don't have to run it again later.
# This requires that NO OTHER VIGNETTE is alphabetically ordered before this one.
saveRDS(file="sce.rds", sce)

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, r Biocpkg("iSEE") applications can be extensively r Biocpkg("iSEE", vignette="configure.html", label="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)
SCREENSHOT("screenshots/basic-demo.png")

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 r CRANpkg("rintrojs") package [@ganz2016rintrojs]. During this tour, you will be taken through the different components of the r Biocpkg("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 export 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 r CRANpkg("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.

Description of the user interface

Header

The layout of the r Biocpkg("iSEE") user interface uses the r CRANpkg("shinydashboard") package. The dashboard header contains four dropdown menus.

The first icon in the dashboard header is the "Organization" menu, which is identified by an icon displaying multiple windows (). This menu contains two items:

The second icon in the dashboard header is the "Export" dropdown menu, which is identified by a download icon () and contains:

The "Documentation" dropdown menu is accessible through the question mark icon (), which contains:

The "Additional Information" dropdown menu is accessible through the information icon (), and contains:

Body

Overview of panel types

The main element in the body of r Biocpkg("iSEE") is the combination of panels, generated (and optionally linked to one another) according to your actions. There are currently eight standard panel types that can be generated with r Biocpkg("iSEE"):

In addition, custom panel types can be defined as described in a r Biocpkg("iSEE", vignette="custom.html", label="separate dedicated vignette"). The panels and models in the r Biocpkg("iSEEu") package provide additional flexibility.

For each standard plot panel, three different sets of parameters will be available in collapsible boxes:

Reduced dimension plots

If a SingleCellExperiment object is supplied to the iSEE function, reduced dimension results are extracted from the reducedDim slot. Examples include low-dimensional embeddings from principal components analysis (PCA) or t-distributed stochastic neighbour embedding (t-SNE) [@van2008visualizing]. These results are used to construct a two-dimensional Reduced dimension plot where each point is a sample, to facilitate efficient exploration of high-dimensional datasets. The "Data parameters" control the reducedDim slot to be displayed, as well as the two dimensions to plot against each other.

Note that this builtin panel does not compute reduced dimension embeddings; they must be precomputed and available in the object provided to the iSEE function. Nevertheless, custom panels - such as the r Biocpkg("iSEEu") DynamicReducedDimensionPlot can be developed and used to enable such features.

Column data plots {#coldataplot}

A Column data plot visualizes sample metadata stored in the SummarizedExperiment column metadata. Different fields can be used for the x- and y-axes by selecting appropriate values in the "Data parameters" box. This plot can assume various forms, depending on the nature of the data on the x- and y-axes:

Note that an x-axis setting of "None" is considered to be categorical with a single level.

Feature assay plots

A Feature assay plot visualizes the assayed values (e.g., gene expression) for a particular feature (e.g., gene) across the samples on the y-axis. This usually results in a (grouped) violin plot, if the x-axis is set to "None" or a categorical variable; or a scatter plot, if the x-axis is another continuous variable^[That said, if there are categorical values for the assayed values, these will be handled as described in the column data plots.].

Gene selection for the y-axis can be achieved by using a linked row data table in another panel. Clicking on a row in the table automatically changes the assayed values plotted on the y-axis. Alternatively, the row name can be directly entered as text that corresponds to an entry of rownames(se)^[This is not effective if se does not contain row names.].

The x-axis covariate can also be selected from the plotting parameters. This can be "None", sample metadata, or the assayed values of another feature (also identified using a linked table or via text). The measurement units are selected as one of the assays(se), which is applied to both the X and Y axes.

Obviously, any other assayed value for any feature can be visualized in this manner, not limited to the expression of genes. The only requirement for this type of panel is that the observations can be stored as a matrix in the SummarizedExperiment object.

Row data plots

A Row data plot allows the visualization of information stored in the rowData slot of a SummarizedExperiment object. Its behavior mirrors the implementation for the Column data plot, and correspondingly this plot can assume various forms depending on whether the data are categorical or continuous.

Sample assay plots

A Sample assay plot visualizes the assayed values (e.g., gene expression) for a particular sample (e.g., cell) across the features on the y-axis.

This usually results in a (grouped) violin plot, if the x-axis is set to "None" or a categorical variable (e.g., gene biotype); or a scatter plot, if the x-axis is another continuous variable.

Notably, the x-axis covariate can also be set to:

Row data tables

A Row data table contains the values of the rowData slot for the SingleCellExperiment/SummarizedExperiment object. If none are available, a column named Present is added and set to TRUE for all features, to avoid issues with DT::datatable and an empty DataFrame. Typically, these tables are used to link to other plots to determine the features to use for plotting or coloring. However, they can also be used to retrieve gene-specific annotation on the fly by specifying the annotFun parameter, e.g. using the annotateEntrez or annotateEnsembl functions, provided in r Biocpkg("iSEE"). Alternatively, users can create a customized annotation function; for more details on this, please consult the manual pages ?annotateEntrez and ?annotateEnsembl.

Column data tables

A Column data table contains the values of the colData slot for the SingleCellExperiment/SummarizedExperiment object. Its behavior mirrors the implementation for the Row data table. Correspondingly, if none are available, a column named Present is added and set to TRUE for all samples, to avoid issues with DT::datatable and an empty DataFrame. Typically, these tables are used to link to other plots to determine the samples to use for plotting or coloring.

Heat maps

Heat map panels provide a compact overview of the data for multiple features in the form of color-coded matrices. These correspond to the assays stored in the SummarizedExperiment object, where features (e.g., genes) are the rows and samples are the columns.

User can select features (rows) to display from the selectize widget (which supports autocompletion), or also via other panels, like row data plots or row data tables. In addition, users can rapidly import custom lists of feature names using a modal popup that provides an Ace editor where they can directly type of paste feature names, and a file upload button that accepts text files containing one feature name per line. Users should remember to click the "Apply" button before closing the modal, to update the heat map with the new list of features.

The "Suggest feature order" button clusters the rows, and also rearranges the elements in the selectize according to the clustering. It is also possible to choose which assay type is displayed ("logcounts" being the default choice, if available). Samples in the heat map can also be annotated, simply by selecting relevant column metadata. A zooming functionality is also available, restricted to the y-axis (i.e., allowing closer inspection on the individual features included).

Description of iSEE functionality

Coloring plots by sample attributes

Column-based plots are the reduced dimension, feature assay and column data plots, where each data point represents a sample. Here, data points can be colored in different ways:

For row-based plots (i.e., the sample assay and row data plots), each data point represents a feature. Like the column-based plots, data points can be colored by:

Fine control of the color maps is possible through the ExperimentColorMap class, see r Biocpkg("iSEE", vignette="ecm.html", label="this vignette") for more details.

Controlling point aesthetics

Data points can be set to different shapes according to categorical factors in colData(se) (for column-based plots) or rowData(se) (for row-based plots). This is achieved by checking the "Shape" box to reveal the shape-setting options. The size and opacity of the data points can be modified via the options available by checking the "Point" box. This may be useful for aesthetically pleasing visualizations when the number of points is very large or small.

Faceting

Each point-based plot can be split into multiple facets using the options in the "Facet" checkbox. Users can facet by row and/or column, using categorical factors in colData(se) (for column-based plots) or rowData(se) (for row-based plots). This provides a convenient way to stratify points in a single plot by multiple factors of interest. Note that point selection can only occur within a single facet at a time; points cannot be selected across facets.

Zooming in and out

Zooming in is possible by first selecting a region of interest in a plot using the brush (drag and select); double-clicking on the brushed area then zooms into the selected area. To zoom out to the original plot, simply double-click at any location in the plot.

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 r Biocpkg("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/iSEE/iSEE2018. Please keep in mind this is only for demonstration purposes, yet those instances show how you or your system administrator can setup r Biocpkg("iSEE") for analyzing and/or sharing your SummarizedExperiment/SingleCellExperiment precomputed object.

Q: I would like to use r Biocpkg("iSEE") with my Seurat object, how do I do?

A: The r BiocStyle::CRANpkg("Seurat") package provides as.SingleCellExperiment() to coerce Seurat objects to SingleCellExperiment objects. This conversion includes assays, cell metadata, feature metadata, and dimensionality reduction results. You can then use the SingleCellExperiment object as usual.

Additional information

Bug reports can be posted on the Bioconductor support site or raised as issues in the r Githubpkg("iSEE/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 r Biocpkg("iSEE") for your analysis, please cite it as shown below:

citation("iSEE")

Session Info {.unnumbered}

sessionInfo()

References {.unnumbered}



csoneson/iSEE documentation built on Jan. 19, 2024, 5:58 p.m.