An introduction to the iSEE interface
iSEE 2.19.1
Compiled date: 2024-12-02
Last edited: 2020-04-20
License: MIT + file LICENSE
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
object1 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)
The allen
data set contains expression values for 379 cells from the mouse visual cortex (Tasic et al. 2016), 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
#> class: SingleCellExperiment
#> dim: 20816 379
#> metadata(2): SuppInfo which_qc
#> assays(1): tophat_counts
#> rownames(20816): 0610007P14Rik 0610009B22Rik ... Zzef1 Zzz3
#> rowData names(0):
#> colnames(379): SRR2140028 SRR2140022 ... SRR2139341 SRR2139336
#> colData names(22): NREADS NALIGNED ... Animal.ID passes_qc_checks_s
#> reducedDimNames(0):
#> mainExpName: endogenous
#> altExpNames(1): ERCC
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))
#> [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 normalize the expression values with 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)
#> [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 primarily on precomputed values stored in the various slots of objects derived from the SummarizedExperiment
class2 Except when dealing with 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.
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 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 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.
The layout of the iSEE user interface uses the 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:
?shiny::column
).
In contrast, panel height is defined in pixels (see ?shiny::plotOutput
).The second icon in the dashboard header is the “Export” dropdown menu, which is identified by a download icon () and contains:
sessionInfo()
commands for best tracking of your environment), and store it in your analysis report/script.
This code can then be further edited to finalize the plots (e.g., for publication).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:
sessionInfo()
function in a modal popup window.
This is particularly useful for reproducing or reporting the environment, especially when reporting errors or unexpected behaviors.The main element in the body of 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 iSEE:
In addition, custom panel types can be defined as described in a separate dedicated vignette. The panels and models in the iSEEu package provide additional flexibility.
For each standard plot panel, three different sets of parameters will be available in collapsible boxes:
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) (Van der Maaten and Hinton 2008).
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 iSEEu DynamicReducedDimensionPlot
can be developed and used to enable such features.
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:
"Other"
box to see the available options.Note that an x-axis setting of “None” is considered to be categorical with a single level.
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 variable3 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)
4 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.
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.
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:
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 iSEE.
Alternatively, users can create a customized annotation function; for more details on this, please consult the manual pages ?annotateEntrez
and ?annotateEnsembl
.
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 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).
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:
"None"
in the radio button).
This results in data points of a constant user-specified color.colData(se)
can be used.
The plot automatically adjusts the scale to use based on whether the chosen column is continuous or categorical.assays
from which values are extracted.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:
"None"
, yielding data points of fixed color.rowData(se)
.Fine control of the color maps is possible through the ExperimentColorMap
class, see this vignette for more details.
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.
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 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.
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/iSEE/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.
Q: I would like to use iSEE with my Seurat
object, how do I do?
A: The 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.
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")
#> To cite package 'iSEE' in publications use:
#>
#> Rue-Albrecht K, Marini F, Soneson C, Lun ATL (2018). "iSEE:
#> Interactive SummarizedExperiment Explorer." _F1000Research_, *7*,
#> 741. doi:10.12688/f1000research.14966.1
#> <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},
#> }
sessionInfo()
#> R Under development (unstable) (2024-10-21 r87258)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.21-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB 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
#>
#> time zone: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] scater_1.35.0 ggplot2_3.5.1
#> [3] scuttle_1.17.0 scRNAseq_2.21.0
#> [5] iSEE_2.19.1 SingleCellExperiment_1.29.1
#> [7] SummarizedExperiment_1.37.0 Biobase_2.67.0
#> [9] GenomicRanges_1.59.1 GenomeInfoDb_1.43.2
#> [11] IRanges_2.41.1 S4Vectors_0.45.2
#> [13] BiocGenerics_0.53.3 generics_0.1.3
#> [15] MatrixGenerics_1.19.0 matrixStats_1.4.1
#> [17] BiocStyle_2.35.0
#>
#> loaded via a namespace (and not attached):
#> [1] splines_4.5.0 later_1.4.1 BiocIO_1.17.1
#> [4] bitops_1.0-9 filelock_1.0.3 tibble_3.2.1
#> [7] XML_3.99-0.17 lifecycle_1.0.4 httr2_1.0.7
#> [10] doParallel_1.0.17 lattice_0.22-6 ensembldb_2.31.0
#> [13] alabaster.base_1.7.2 magrittr_2.0.3 sass_0.4.9
#> [16] rmarkdown_2.29 jquerylib_0.1.4 yaml_2.3.10
#> [19] httpuv_1.6.15 DBI_1.2.3 RColorBrewer_1.1-3
#> [22] abind_1.4-8 zlibbioc_1.53.0 Rtsne_0.17
#> [25] AnnotationFilter_1.31.0 RCurl_1.98-1.16 rappdirs_0.3.3
#> [28] circlize_0.4.16 GenomeInfoDbData_1.2.13 ggrepel_0.9.6
#> [31] irlba_2.3.5.1 alabaster.sce_1.7.0 codetools_0.2-20
#> [34] DelayedArray_0.33.3 DT_0.33 tidyselect_1.2.1
#> [37] shape_1.4.6.1 UCSC.utils_1.3.0 ScaledMatrix_1.15.0
#> [40] viridis_0.6.5 shinyWidgets_0.8.7 BiocFileCache_2.15.0
#> [43] GenomicAlignments_1.43.0 jsonlite_1.8.9 GetoptLong_1.0.5
#> [46] BiocNeighbors_2.1.1 iterators_1.0.14 foreach_1.5.2
#> [49] tools_4.5.0 Rcpp_1.0.13-1 glue_1.8.0
#> [52] gridExtra_2.3 SparseArray_1.7.2 xfun_0.49
#> [55] mgcv_1.9-1 dplyr_1.1.4 HDF5Array_1.35.2
#> [58] gypsum_1.3.0 shinydashboard_0.7.2 withr_3.0.2
#> [61] BiocManager_1.30.25 fastmap_1.2.0 rhdf5filters_1.19.0
#> [64] fansi_1.0.6 shinyjs_2.1.0 digest_0.6.37
#> [67] rsvd_1.0.5 R6_2.5.1 mime_0.12
#> [70] colorspace_2.1-1 listviewer_4.0.0 RSQLite_2.3.8
#> [73] utf8_1.2.4 rtracklayer_1.67.0 httr_1.4.7
#> [76] htmlwidgets_1.6.4 S4Arrays_1.7.1 pkgconfig_2.0.3
#> [79] gtable_0.3.6 blob_1.2.4 ComplexHeatmap_2.23.0
#> [82] XVector_0.47.0 htmltools_0.5.8.1 bookdown_0.41
#> [85] ProtGenerics_1.39.0 rintrojs_0.3.4 clue_0.3-66
#> [88] scales_1.3.0 alabaster.matrix_1.7.3 png_0.1-8
#> [91] knitr_1.49 rjson_0.2.23 nlme_3.1-166
#> [94] curl_6.0.1 shinyAce_0.4.3 cachem_1.1.0
#> [97] rhdf5_2.51.0 GlobalOptions_0.1.2 BiocVersion_3.21.1
#> [100] parallel_4.5.0 miniUI_0.1.1.1 vipor_0.4.7
#> [103] AnnotationDbi_1.69.0 restfulr_0.0.15 pillar_1.9.0
#> [106] grid_4.5.0 alabaster.schemas_1.7.0 vctrs_0.6.5
#> [109] promises_1.3.2 BiocSingular_1.23.0 dbplyr_2.5.0
#> [112] beachmat_2.23.2 xtable_1.8-4 cluster_2.1.6
#> [115] beeswarm_0.4.0 evaluate_1.0.1 GenomicFeatures_1.59.1
#> [118] cli_3.6.3 compiler_4.5.0 Rsamtools_2.23.1
#> [121] rlang_1.1.4 crayon_1.5.3 ggbeeswarm_0.7.2
#> [124] viridisLite_0.4.2 alabaster.se_1.7.0 BiocParallel_1.41.0
#> [127] munsell_0.5.1 Biostrings_2.75.1 lazyeval_0.2.2
#> [130] colourpicker_1.3.0 Matrix_1.7-1 ExperimentHub_2.15.0
#> [133] bit64_4.5.2 Rhdf5lib_1.29.0 KEGGREST_1.47.0
#> [136] shiny_1.9.1 alabaster.ranges_1.7.0 AnnotationHub_3.15.0
#> [139] fontawesome_0.5.3 igraph_2.1.1 memoise_2.0.1
#> [142] bslib_0.8.0 bit_4.5.0