From 028931315e42a7c5955290691392546f4a25f68f Mon Sep 17 00:00:00 2001 From: Federico Marini Date: Mon, 29 Apr 2024 17:08:59 +0200 Subject: [PATCH] first stub at all vignette components --- vignettes/about_this_workshop_00.Rmd | 86 ++++ vignettes/bonus_content_04.Rmd | 87 ++++ vignettes/iSEE_overview_02.Rmd | 460 +++++++++++++++++++++ vignettes/iSEE_quickrecipes.Rmd | 0 vignettes/iSEE_quickrecipes_03.Rmd | 590 +++++++++++++++++++++++++++ vignettes/iUSEiSEE_01.Rmd | 368 +++++++++++++++++ 6 files changed, 1591 insertions(+) create mode 100644 vignettes/about_this_workshop_00.Rmd create mode 100644 vignettes/bonus_content_04.Rmd create mode 100644 vignettes/iSEE_overview_02.Rmd delete mode 100644 vignettes/iSEE_quickrecipes.Rmd create mode 100644 vignettes/iSEE_quickrecipes_03.Rmd create mode 100644 vignettes/iUSEiSEE_01.Rmd diff --git a/vignettes/about_this_workshop_00.Rmd b/vignettes/about_this_workshop_00.Rmd new file mode 100644 index 0000000..26e5529 --- /dev/null +++ b/vignettes/about_this_workshop_00.Rmd @@ -0,0 +1,86 @@ +--- +title: "iUSEiSEE - About this workshop" +author: Federico Marini^[marinif@uni-mainz.de] +output: + html_document: + theme: cosmo + toc: yes + toc_float: yes + number_sections: true +vignette: > + %\VignetteIndexEntry{00. About this workshop} + %\VignettePackage{iUSEiSEE} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +editor_options: + chunk_output_type: console +bibliography: iUSEiSEErefs.bib +--- + + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +suppressPackageStartupMessages({ + library("BiocStyle") +}) +``` + + + + +# Description + +The iSEE package is a flexible, powerful and extendible application to explore any dataset stored in SummarizedExperiment objects, including single cell and spatially resolved data. + +iSEE enables a multitude of panels to gain in-depth insight in your data; it does so combining interactivity and reproducibility, and providing an ideal companion to CELLxGENE for deeper dives into data. + +This package demo provides an overview of the functionality of the `r Biocpkg("iSEE")` Bioconductor package, and is intended as an appetizer to more. + +# Pre-requisites + +* Familiarity with single-cell sequencing data (ideally scRNA-seq) +* Familiarity with the SummarizedExperiment/SingleCellExperiment class, or +alternatively the Seurat or AnnData frameworks - basically, any of the widely used +ecosystem for working with/storing/processing single cell data +* Familiarity with single-cell data visualizations and representations + +# Participation + +Participants will be able to follow along in the live coding parts of the demo. + +# _R_ / _Bioconductor_ packages used + +* `iSEE`: https://bioconductor.org/packages/iSEE +* `iSEEde`: https://bioconductor.org/packages/iSEEde +* `iSEEindex`: https://bioconductor.org/packages/iSEEindex +* `iSEEpathways`: https://bioconductor.org/packages/iSEEpathways +* `iSEEhub`: https://bioconductor.org/packages/iSEEhub + + + + + + + + + +# Workshop goals and objectives + +## Learning goals + +* Outline the features of iSEE, built upon the RStudio Shiny framework +* Utilize interactive GUI components and layouts to efficiently extract information from biological data sets +* Describe how to construct interactive apps and custom panels +* Demonstrate how these package can smoothly be integrated into and enhance existing workflows for the datasets at hand + +## Learning objectives + +* Set up a local environment for running iSEE apps +* Interact with components of the iSEE user interface to visually inspect and discuss various data sets +* Identify and locate configurable aspects of iSEE apps +* Practice interactive visualization over a single-cell RNA-sequencing workflow +* Imagine use cases and future developments for interactive visualization as part of computational workflows +* Design and create iSEE instances for collections of datasets diff --git a/vignettes/bonus_content_04.Rmd b/vignettes/bonus_content_04.Rmd new file mode 100644 index 0000000..6b6d444 --- /dev/null +++ b/vignettes/bonus_content_04.Rmd @@ -0,0 +1,87 @@ +--- +title: "iUSEiSEE - Bonus content" +author: Federico Marini^[marinif@uni-mainz.de] +output: + html_document: + theme: cosmo + toc: yes + toc_float: yes + number_sections: true +vignette: > + %\VignetteIndexEntry{04. Bonus content} + %\VignettePackage{iUSEiSEE} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +editor_options: + chunk_output_type: console +bibliography: iUSEiSEErefs.bib +--- + + + +```{r setup, include=FALSE} +knitr::opts_chunk$set( + echo = TRUE, + cache = FALSE, + collapse = TRUE, + comment = "#>", + crop = NA +) +suppressPackageStartupMessages({ + library("BiocStyle") + library("iSEE") +}) +htmltools::tagList(rmarkdown::html_dependency_font_awesome()) +``` + +```{r, eval=!exists("SCREENSHOT"), include=FALSE} +SCREENSHOT <- function(x, ...) knitr::include_graphics(x) +``` + + +# Moar iSEE things + +This vignette contains some examples on even more `iSEE`-things. + +We will use the following packages throughout its content (make sure to have them installed if you want to run it interactively) + +```{r pkgs} +library("iSEE") +library("iSEEfier") +library("iSEEu") +library("iSEEindex") +``` + + + +## iSEE a challenge: let's reproduce any figure! + +TODO + +## iSEEfier + +TODO + +Najla :) + +## iSEEindex + +TODO + +## iSEEde and iSEEpathways + +TODO + +This one is from the demo of the 2023 workshop + +## Tours: help and storytelling + +TODO + +# Session info {-} + +```{r} +sessionInfo() +``` + +# References {-} diff --git a/vignettes/iSEE_overview_02.Rmd b/vignettes/iSEE_overview_02.Rmd new file mode 100644 index 0000000..b4adbdc --- /dev/null +++ b/vignettes/iSEE_overview_02.Rmd @@ -0,0 +1,460 @@ +--- +title: "iUSEiSEE - An overview of iSEE" +author: Federico Marini^[marinif@uni-mainz.de] +output: + html_document: + theme: cosmo + toc: yes + toc_float: yes + number_sections: true +vignette: > + %\VignetteIndexEntry{02. Overview of iSEE} + %\VignettePackage{iUSEiSEE} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +editor_options: + chunk_output_type: console +bibliography: iUSEiSEErefs.bib +--- + + + +```{r setup, include=FALSE} +knitr::opts_chunk$set( + echo = TRUE, + cache = FALSE, + collapse = TRUE, + comment = "#>", + crop = NA +) +suppressPackageStartupMessages({ + library("BiocStyle") + library("iSEE") +}) +htmltools::tagList(rmarkdown::html_dependency_font_awesome()) +``` + +```{r, eval=!exists("SCREENSHOT"), include=FALSE} +SCREENSHOT <- function(x, ...) knitr::include_graphics(x) +``` + + +# Introduction + +This vignette provides an overview of the graphical interface of `r Biocpkg("iSEE")` applications. +To follow along, make sure that you launch the default `r Biocpkg("iSEE")` instance as described in the next code block at the start of the [following section](#default-app). + +Note that in the default configuration, the panels do not look exactly like the ones shown in the screenshots that you will see below. +For example, data points are not immediately colored, and the default annotation variables displayed by each panel may differ. +The [hands-on recipes](recipes.html) workshop of this workshop will demonstrate how to modify the content of the panels, and how they are displayed. + +Note that for simplicity, we typically refer to a `SummarizedExperiment` in this workshop; however, `r Biocpkg("iSEE")` works seamlessly for objects of any class extending `SummarizedExperiment` as well (e.g., `SingleCellExperiment`, `DESeqDataSet`). +That said, some types of panels -- such as the `r .fullName(ReducedDimensionPlot())` -- are only available for objects that contain a `reducedDim` slot (in particular, `SingleCellExperiment` objects); the basic `SummarizedExperiment` class does not contain this slot. +In this workshop, we refer to the rows of the `SummarizedExperiment` object as 'features' (these can be genes, transcripts, genomic regions, etc) and to the columns as 'samples' (which, in our example data set, are single cells). + +# The default iSEE app {#default-app} + +Using the demonstration data set, we can launch an `r Biocpkg("iSEE")` instance for exploring this data set using the `iSEE()` function without any further argument. +This will produce an app using the default configuration; that is, the app instance will include one panel of each built-in class for which the relevant information is available in the `SummarizedExperiment` object. + +```{r, message=FALSE} +library("iSEE") +sce_location <- system.file("datasets", "sce_pbmc3k.RDS", package = "iUSEiSEE") +sce_location +sce <- readRDS(sce_location) +app <- iSEE(sce) +``` + +```{r runApp, eval=FALSE} +shiny::runApp(app) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-initial.png", delay=20) +``` + +The main argument to the `iSEE()` function is a `SummarizedExperiment` object, or an object of any class extending `SummarizedExperiment` (such as `SingleCellExperiment`, in this case). +No other restrictions are made on the type of data stored in the object, and `r Biocpkg("iSEE")` can be used for interactive visualization of many different types of data. +It is also worth noting that for various types of data, Bioconductor packages provides functionality for directly importing quantifications generated by external software packages into a `SummarizedExperiment` object. +For example, the `r Biocpkg("DropletUtils")` package can read quantifications from the 10x Genomics CellRanger pipeline for single-cell RNA-seq data, and the `r Biocpkg("tximeta")` package can be used to read data from transcript quantification pipelines into a `SummarizedExperiment` object. + +While we will not make explicit use of it in this workshop, we note that it is also possible to call `iSEE()` without providing a `SummarizedExperiment` object. +In that case, the user will be prompted to upload such an object, serialized into a `.rds` file. +It is also possible to import a specification of the initial panel setup. + +```{r} +app <- iSEE() +``` + +```{r, eval=FALSE} +shiny::runApp(app) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-no-se.png", delay=10) +``` + +# The built-in panel types {#user-interface} + +## The panel hierarchy + +The `r Biocpkg("iSEE")` user interface (UI) consists of a number of panels, each displaying the data provided in the `SummarizedExperiment` from a specific perspective. +There are 8 standard panel types; 6 plot panels and 2 table panels, all showcased in the figure shown at the start of the [previous section](#default-app). +In the default configuration, one panel of each type is included when launching the `r Biocpkg("iSEE")` user interface. +However, users are free to rearrange, resize, remove or add panels freely, as demonstrated in the separate vignette of [workshop recipes](recipes.html). +We provide a brief overview of each panel type in the following subsections. + +In addition to the 8 standard panel types included in `r Biocpkg("iSEE")`, users can create custom panels (both plots and tables). +Moreover, the `r Biocpkg("iSEEu")` (iSEE universe) package contains additional panel types. +The creation and configuration of custom panels is also demonstrated in a series of [workshop advanced recipes](recipes.html). + +Specifically, `r Biocpkg("iSEE")` panels are implemented as a hierarchy of S4 classes. +Only _concrete_ classes (orange) may be instantiated as panels in the user interface; while _virtual_ classes (grey) provide functionality shared by families of panels (e.g., sample-oriented plots, feature-oriented tables). + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/panel-classes.png", dpi = 180) +``` + + + +## `r .fullName(ReducedDimensionPlot())` {#reddimplot} + +The reduced dimension plot can display any reduced dimension representation that is present in the `reducedDim` slot of the `SingleCellExperiment` object. + +Note that this slot is not defined for the base `SummarizedExperiment` class, in which case the user interface does not allow the inclusion of panels of this type. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(ReducedDimensionPlot( + PanelWidth = 12L, + Type = "TSNE", ColorBy = "Column data", + ColorByColumnData = "Cluster" +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-reduceddimensionplot.png", delay=10) +``` + +## `r .fullName(ColumnDataPlot())` {#coldataplot} + +The column data plot can display one or two of the provided column annotations (from the `colData` slot). +Depending on the class of the selected annotations, the panel shows either a scatter plot, a violin plot, or a Hinton diagram [@Hinton1991-hintondiagram; @Bremner1994-hintonplots]. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(ColumnDataPlot( + PanelWidth = 12L, + XAxis = "Column data", XAxisColumnData = "Cluster", + YAxis = "log10_total" +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-columndataplot.png", delay=10) +``` + +## `r .fullName(RowDataPlot())` {#rowdataplot} + +Analogous to the [column data plot](#coldataplot) above, the row data plot displays one or two of the provided row annotations (from the `rowData` slot). +Depending on the class of the selected annotations, the panel displays either a scatter plot, a violin plot, or a Hinton plot. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(RowDataPlot( + PanelWidth = 12L, XAxis = "Row data", + YAxis = "detected", XAxisRowData = "log10_total" +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-rowdataplot.png", delay=10) +``` + +## `r .fullName(ComplexHeatmapPlot())` {#heatmap} + +The complex heatmap panel displays, for any assay, the observed values for a subset of the features across the samples. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(ComplexHeatmapPlot( + PanelWidth = 12L, Assay = "logcounts", CustomRows = TRUE, + CustomRowsText = c("CD14", "CD27", "CD52", "CD68", "CD19", "CD4"), + ColumnData = "Cluster", AssayCenterRows = TRUE +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-complexheatmapplot.png", delay=10) +``` + +## `r .fullName(FeatureAssayPlot())` {#featassayplot} + +The feature assay plot displays the observed values for one feature across the samples. +It is also possible to plot the observed values for two features, in a scatter plot. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(FeatureAssayPlot( + PanelWidth = 12L, XAxis = "Column data", + XAxisColumnData = "Cluster", YAxisFeatureName = "CD27", + Assay = "logcounts", ColorBy = "Column data", + ColorByColumnData = "Cluster" +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-featureassayplot.png", delay=10) +``` + +## `r .fullName(SampleAssayPlot())` {#sampassayplot} + +Analogous to the [`r .fullName(FeatureAssayPlot())`](#featassayplot) above, the `r .fullName(SampleAssayPlot())` shows the observed values for all features, for one of the samples. +It is also possible to plot the observed values for two samples, in a scatter plot. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(SampleAssayPlot( + PanelWidth = 12L, XAxis = "Sample name", + XAxisSampleName = "Cell1", YAxisSampleName = "Cell2", + PointSize = 2 +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-sampleassayplot.png", delay=10) +``` + +## `r .fullName(RowDataTable())` {#rowdatatable} + +The row data table displays all information provided in the `rowData` slot of the `SummarizedExperiment` object, leveraging the interactivity provided by the `r CRANpkg("DT")` package. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(RowDataTable(PanelWidth = 12L))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-rowdatatable.png", delay=10) +``` + +## `r .fullName(ColumnDataTable())` {#coldatatable} + +Analogous to the [`r .fullName(RowDataTable())`](#rowdatatable) above, the column data table displays all information provided in the `colData` slot of the `SummarizedExperiment` object. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(ColumnDataTable(PanelWidth = 12L))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-columndatatable.png", delay=10) +``` + +# Collapsible boxes with display controls {#collapsible-boxes} + +## Data parameters {#data-parameters-box} + +Each plot panel type has a `Data parameters` collapsible box. +This box has different content for each panel type, but in all cases it lets the user control the data that is displayed in the plot. + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(ColumnDataPlot( + PanelWidth = 12L, DataBoxOpen = TRUE, + XAxis = "Column data", XAxisColumnData = "Cluster", + YAxis = "log10_total" +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-columndataplot-dataparameters.png", delay=10) +``` + +## Visual parameters {#visual-parameters-box} + +In contrast to the `Data parameters` collapsible box that lets users control _what_ is displayed in the plot, the `Visual parameters` box lets users control _how_ the information is displayed. + +This collapsible box contains the controls to change the size, shape, opacity, and color of the points, to facet the plot by any available categorical annotation, to subsample points for increased speed of plot rendering, and to control how legends are displayed. + +```{r, message=FALSE, echo=FALSE} +app <- iSEE(sce, initial = list(ColumnDataPlot( + PanelWidth = 12L, VisualBoxOpen = TRUE, + XAxis = "Column data", XAxisColumnData = "Cluster", + YAxis = "log10_total", + VisualChoices = c("Color", "Point", "Facet", "Shape", "Size", "Text") +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-columndataplot-visualparameters.png", delay=10) +``` + +## Selection parameters {#selection-parameter-box} + +The `Selection parameters` collapsible box provides controls to transfer selections of points (features or samples) between panels. + +We demonstrate examples of point transmission in the separate vignette of [workshop recipes](recipes.html) + +```{r, message=FALSE, echo = FALSE} +app <- iSEE(sce, initial = list(ReducedDimensionPlot( + PanelWidth = 12L, SelectionBoxOpen = TRUE, + Type = "TSNE", ColorBy = "Column data", + ColorByColumnData = "Cluster" +))) +``` + +```{r, echo=FALSE, out.width='100%'} +SCREENSHOT("images/isee-reduceddimensionplot-selectionparameters.png", delay=10) +``` + +# Additional controls {#additional-controls} + +At the top-right corner of the iSEE application, users can find additional controls for reproducibility, configuration, and help. + +```{r, echo = FALSE, eval = TRUE} +panel_organization_fig <- "images/PanelOrganization.png" +export_fig <- "images/Export.png" +documentation_fig <- "images/Documentation.png" +additional_info_fig <- "images/AdditionalInfo.png" +``` + +| | | | +|--------------|:----------:|----------------------------------------| +| Organization | `r knitr::include_graphics(panel_organization_fig, dpi = 180)` | [Organize panels](#organize-panels)
[Examine panel chart](#examine-panel-chart) | +| Export | `r knitr::include_graphics(export_fig, dpi = 180)` | [Download panel output](#download-output)
[Extract R code](#extract-r-code)
[Display panel settings](#display-panel-settings) | +| Documentation | `r knitr::include_graphics(documentation_fig, dpi = 180)` | [Quick tour](#quick-tour)
[Open the vignette](#browse-vignettes) | +| Additional info | `r knitr::include_graphics(additional_info_fig, dpi = 180)` | [About this session](#app-session-info)
[About iSEE](#about-isee) | + +## Organize panels {#organize-panels} + +As mentioned above, the default behaviour of the `iSEE()` function is to launch an instance of the user interface that displays one panel of each of the standard types (provided the underlying data is available, e.g. for reduced dimension plots the `reducedDim` slot is required). +However, in some cases it is desirable to have multiple panels of the same type, and/or exclude some panel types. + +In order to accommodate such situations, users can add, remove, change the order of and resize all panels via the `Organization` menu in the top-right corner. + +Clicking in the selectize box listing all current panels will present you with a drop-down menu from which you can choose additional panels to add. +Similarly, panels can be removed by clicking on the icon associated with the panel name. + +Each panel can be individually resized by changing the width and height. +Note that the total width of a row in the interface is 12 units. +When the width of a panel is greater than the space available, the panel is moved to a new row. + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/panel-organization.png", dpi = 180) +``` + +## Linking panels and transmitting point selections {#examine-panel-chart} + +When exploring data, it is often useful to be able to select a subset of points and investigate different aspects of their characteristic features. +In `r Biocpkg("iSEE")`, this can be achieved by _selecting_ points in one panel, and _transmitting_ this selection to one or more other panels. + +The brushing and point selection can also be programmatically preconfigured. + +The button `Examine panel chart` display a graph that reports any active point transmission between panels in the app. + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/panel-graph.png", dpi = 180) +``` + +## Download panel output {#download-output} + +The `Download panel output` button opens a modal window listing all the current panels in the app. +Checkboxes allow users to select any subset of panels to export. +Finally, clicking the `Download` button in that modal will prompt the app to save plots to PDF files, tables to CSV files, package the set of files in a ZIP archive that users can download and save on their computer. + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/panel-download.png", dpi = 180) +``` + +## Extract R code {#extract-r-code} + +The fact that data exploration is done interactively is no reason to forego reproducibility! +To this end, `r Biocpkg("iSEE")` lets you export the exact R code used to create each of the currently visible plots. + +Importantly, the script reported by `r Biocpkg("iSEE")` contains a short preamble needed to set up variable names that are used in individual panels, including active brushes used to transfer point selections. + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/code-tracker.png", dpi = 180) +``` + +## Display panel settings {#display-panel-settings} + +It can take a great amount of time to achieve a satisfactory panel configuration. +To avoid the need to manually organize the panels each time the app is opened, `r Biocpkg("iSEE")` offers the possibility to export code that can be reused later to +programmatically specify how the app is initialized, as well as to inspect and export the current panel settings for future use. + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/panel-settings.png", dpi = 180) +``` + +## Quick tour {#quick-tour} + +One important aspect of visualization is the ability to share your insights with others. +A powerful way of easily getting people unfamiliar with your data up to speed is to provide a walkthrough of the interface and the different types of plots that are displayed. +With `r Biocpkg("iSEE")`, this can be achieved using _tours_. +To configure a tour, you need to create a text file with two columns; named `element` and `intro`, with the former describing the UI element to highlight in each step, and the latter providing the descriptive text that will be displayed. + +Clicking the `Quick tour` button launches an interactive tour of the interface using the `r BiocStyle::CRANpkg("rintrojs")` package, highlighting specific elements of the user interface, labeled with information and instructions guiding users through panels and tasks specific to individual apps. + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/quick-tour.png", dpi = 180) +``` + +You can see a live example of a more complex tour in action, visit . +The code used to create this app and the associated tour is available from . + +## Open the vignette {#browse-vignettes} + +The user interface navigation bar also includes this button to open the introductory vignette to `r Biocpkg("iSEE")` in your we browser. + +Depending on the version of `r Biocpkg("iSEE")` that you are using, this will adaptively lead you to a locally built vignette present on your computer, or the _release_ or the _devel_ version of the Bioconductor package landing page, e.g. <`r BiocStyle::Biocpkg("iSEE", vignette = "basic.html", label = paste("Bioconductor", BiocManager::version()))`>. + +## Session information {#app-session-info} + +This button displays the output of `sessionInfo()`, which is a useful piece of information to report when reporting an issue with an app. + +```{r, echo=FALSE, out.width='100%'} +knitr::include_graphics("images/session-info.png", dpi = 180) +``` + +## About iSEE {#about-isee} + +This button provides information about the authors of `r Biocpkg("iSEE")`, as well as citation information. + +If you use this package, please use the following citation information: + +> 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}, +} +``` + +# Additional resources {#additional-resources} + +A lot of materials have been developed, from the first use of `r Biocpkg("iSEE")` to contributions of new panel classes in separate downstream packages. + +* The bookdown book on _Extending iSEE_: https://isee.github.io/iSEE-book/ +* Bioconductor landing page: https://bioconductor.org/packages/iSEE/ +* Publication (F1000Research, 2018): https://f1000research.com/articles/7-741/v1 +* Deployed examples: https://marionilab.cruk.cam.ac.uk/, code at https://github.com/iSEE/iSEE2018 + * Further deployments in the https://github.com/iSEE/iSEE_instances repo + * `r Biocpkg("iSEE")` in production: http://www.teichlab.org/singlecell-treg +* Custom panel examples: https://github.com/iSEE/iSEE_custom +* Development version (bug reports etc): https://github.com/iSEE/iSEE + +# Session info {-} + +```{r} +sessionInfo() +``` + +# References {-} diff --git a/vignettes/iSEE_quickrecipes.Rmd b/vignettes/iSEE_quickrecipes.Rmd deleted file mode 100644 index e69de29..0000000 diff --git a/vignettes/iSEE_quickrecipes_03.Rmd b/vignettes/iSEE_quickrecipes_03.Rmd new file mode 100644 index 0000000..074cb58 --- /dev/null +++ b/vignettes/iSEE_quickrecipes_03.Rmd @@ -0,0 +1,590 @@ +--- +title: "iUSEiSEE - The iSEE cookbook" +author: Federico Marini^[marinif@uni-mainz.de] +output: + html_document: + theme: cosmo + toc: yes + toc_float: yes + number_sections: true +vignette: > + %\VignetteIndexEntry{03. The iSEE cookbook} + %\VignettePackage{iUSEiSEE} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +editor_options: + chunk_output_type: console +bibliography: iUSEiSEErefs.bib +--- + + + +```{r setup, include=FALSE} +knitr::opts_chunk$set( + echo = TRUE, + cache = FALSE, + collapse = TRUE, + comment = "#>", + crop = NA +) +suppressPackageStartupMessages({ + library("BiocStyle") + library("iSEE") +}) +htmltools::tagList(rmarkdown::html_dependency_font_awesome()) +``` + +```{r, eval=!exists("SCREENSHOT"), include=FALSE} +SCREENSHOT <- function(x, ...) knitr::include_graphics(x) +``` + + +# Introduction + +This vignette consists of a series of (independent) hands-on recipes, aimed at exploring the capabilities of `r Biocpkg("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](overview.html). +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. + +```{r, message=FALSE} +library("iSEE") +library("iSEEu") + +sce_location <- system.file("datasets", "sce_pbmc3k.RDS", package = "iUSEiSEE") +sce_location +sce <- readRDS(sce_location) +sce +``` + +# The cookbook + +What follows is a list of 11 small self contained recipes, that try to address one specific aim - and provide accordingly a simple, targeted solution. + +## 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](overview.html) or the help pages for the respective panel classes.
    • +
+
+ +
+Solution (interactively) +
    +
  • First open an application with the default set of panels.
    • +```{r, eval = FALSE} +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) +```{r} +app <- iSEE(sce, initial = list( + ReducedDimensionPlot(PanelWidth = 3L), + RowDataPlot(PanelWidth = 4L), + ColumnDataPlot(PanelWidth = 5L) +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_01.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +app <- iSEE(sce, list( + ColumnDataPlot(PanelWidth = 12L, XAxis = "Column data", + YAxis = "labels_fine", XAxisColumnData = "Cluster") +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_02.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +app <- iSEE(sce, initial = list( + ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE"), + ReducedDimensionPlot(PanelWidth = 6L, Type = "UMAP") +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_03.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +app <- iSEE(sce, initial = list( + FeatureAssayPlot(PanelWidth = 12L, XAxis = "Column data", + YAxisFeatureName = "CD74", XAxisColumnData = "Cluster") +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_04.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +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") +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_05.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +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") +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_06.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +app <- iSEE(sce, initial = list( + ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE", + PointSize = 0.5), + ReducedDimensionPlot(PanelWidth = 6L, Type = "TSNE", + PointSize = 3, PointAlpha = 0.2) +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_07.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +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") +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_08.png", delay=20) +``` + +## 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)
    • +```{r, eval = FALSE} +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) +```{r} +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") +)) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_09.png", delay=20) +``` + +## 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) +```{r} +app <- modeReducedDim(sce, colorBy = "labels_main") +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_10.png", delay=20) +``` + +## 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) +```{r} +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) +``` +
+ +```{r, echo=FALSE} +SCREENSHOT("images/recipe_11.png", delay=20) +``` + +# Session info {-} + +```{r} +sessionInfo() +``` + +# References {-} diff --git a/vignettes/iUSEiSEE_01.Rmd b/vignettes/iUSEiSEE_01.Rmd new file mode 100644 index 0000000..19ce50e --- /dev/null +++ b/vignettes/iUSEiSEE_01.Rmd @@ -0,0 +1,368 @@ +--- +title: "iUSEiSEE - The iSEE package for efficient, interactive, and reproducible exploration of data" +author: Federico Marini^[marinif@uni-mainz.de] +output: + html_document: + theme: cosmo + toc: yes + toc_float: yes + number_sections: true +vignette: > + %\VignetteIndexEntry{01. iUSEiSEE} + %\VignettePackage{iUSEiSEE} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +editor_options: + chunk_output_type: console +bibliography: iUSEiSEErefs.bib +--- + + + +```{r setup, include = FALSE} +knitr::opts_chunk$set( + echo = TRUE, + cache = FALSE, + collapse = TRUE, + comment = "#>", + crop = NA +) +suppressPackageStartupMessages({ + library("BiocStyle") + library("iSEE") +}) +``` + + +# `iUSEiSEE`: a masterclass-level workshop on iSEE + +The iSEE package is a flexible, powerful and extendible application to explore any dataset stored in SummarizedExperiment objects, including single cell and spatially resolved data. + +This workshop and associated workshop package contain all the materials you might need to have a full experience and learn how to use iSEE, hands on, starting from the basics and making your way up to the more advanced features. + +This vignette contains a compact version of the more extended material of all other detailed vignettes. +Feel free to use this as a compact index for the rest! + +In brief, you will... + +* Install all required packages and software +* Go get some data +* See how easy it is to run `iSEE` +* Obtain a quick overview of the panels and the user interface +* Get to know the more advanced features of `iSEE` +* Be able to use `iSEE` on your own data (and maybe even deploy that!) + +Ready? Let's go! + +# Installing and loading the required packages + +To run the content presented in this demo, run this following chunk in your R environment. + +```{r eval = FALSE} +library("BiocManager") +BiocManager::install("imbeimainz/iUSEiSEE") + +``` + +We start by loading the packages that will be used during the demo. + +```{r, message=FALSE, warning=FALSE} +library("SingleCellExperiment") +library("iSEE") +library("TENxPBMCData") + +library("iSEEu") +library("iSEEde") +library("iSEEpathways") +library("iSEEhub") +library("iSEEindex") +``` + +All of these would be loaded if you run + +```{r} +library("iUSEiSEE") +``` + +You can also clone this repository (https://imbeimainz.github.io/iUSEiSEE) locally by `git clone` - it makes it easy to follow along this vignette! + +# Let's go get us some data! + +We will start very much *in medias res*, assuming that this might be the ideal point where you have processed your data - early or late phase - and now want to have the BEST look at that. + +Navigate to https://zenodo.org/records/10084595 and download the data (it contains the three objects you might be "coming from"). +Unpack the archive you downloaded in the `datasets` subfolder of the `vignette` folder. + +We included a `SingleCellExperiment` object on a processed version for the PBMC3k dataset, many of you can somehow be familiar with this. + +Let's load the dataset in our environment: + +```{r} +sce_pbmc3k <- readRDS( + file = system.file("datasets", "sce_pbmc3k.RDS", package = "iUSEiSEE") +) + +sce_pbmc3k +``` + + +# As easy as saying `iSEE(sce)`! + +Who of you is investing a fair amount/lot of time in doing proper data exploration? + +Who of you is familiar with the beautiful CellxGene tool? + +Who of you dreamed to do even more on your data? + +I have a quiz for you - have a look at this, for example: + +http://shiny.imbei.uni-mainz.de:3838/iSEE_Tonsils_CD4Tcells/ + +```{r, echo=FALSE} +knitr::include_graphics("images/ss_Tcells.png") +``` + +
+Question 1 +How many lines of code are required to realize this? + +A) 4-5 +B) 250-300 +C) 7500-10000 +
+ + +
+Question 2 +How many of these lines had to be typed by a human? + +A) 4-5 +B) 250-300 +C) 7500-10000 +
+ +So, yes, I will show you that is as easy as that: + +```{r, eval=FALSE} +library("iSEE") +iSEE(sce_pbmc3k) +``` + +Let's run this together and see what we have got in store. + + + + + + + + +Schedule: + +- go get the dataset +- overview on the iSEE interface as a whole + - panels + - controls + - all ui elements + + +- the iSEE challenge: let's reproduce any figure? +- + + + + + + + + + + + + + + + +# Quick tour of the panels + +What typical visualizations people would you use to represent and explore your datasets? + +Each panel has some essential content: + +* Data parameters +* Visual parameters +* Selection parameters + +Let's have a closer look at that on the Reduced Dimension Plot 1 panel. + +If you have no idea of what a panel can "normally" do, look for the question mark icon, that will start a tiny tour on its functionality. + +# Additional UI functionality + +iSEE also has some additional controls, grouped into the header bar, let's have a look at them: + +* Organization buttons +* Export buttons +* Documentation buttons +* Extra info buttons + +With this, we can... + +- reorganize the panel layout - add, remove, re-order +- extract the code to exactly reproduce the outputs, 1:1 +- store (and re-utilize) the panel settings +- generate at once an archive with all/selected parts of the panel outputs +- start a tour on the content displayed - yes, you can very much tell a story with iSEE! + +# In depth exploration of data - iSEE's main functionality + +## You can control pretty much everything in a plot + +Coloring by, faceting, zooming, hovering! +Make a wish! + +## You can link any panel to any other panel + +Brush selection, lasso selection, select the receiving panel, iterate! +Read out information, see the panel transmission graph. + +## You can use tables to navigate panels + +Search and select, transmit, receive, iterate! + +## Configuring your iSEE instance + +Panels: add, move, remove; exporting the `initial` configuration, reloading it + +## Reproducibility for the win! + +A magic wand: two clicks away from all the R code you need; export all outputs, save individual images + +## Sharing is caring, and so is telling a story + +Start the tour, highlighting elements; make your data really explorable! + +# Custom panels & the iSEE universe + +A couple of additional things you can do with custom panels (and this is just an appetizer!): + +* Custom panels: perform some extra steps +* Multiple selection and "DE on the fly" +* Check out `r Biocpkg("iSEEu")` for more +* Spatial data? We can already handle that with a workaround! See https://moffittlab.connect.hms.harvard.edu/merfish/merfish_homepage.html for an example + +# Got data? + +## Got single cell data? + +You might have got the gist: + +```{r, eval=FALSE} +sce <- sce_pbmc3k # Load your data in some manner +library("iSEE") +iSEE(sce) +``` + +So, yes, we mighe be down to THREE lines of code. + +## Got some special feature in your data? + +Maybe `r Biocpkg("iSEEu")` can be the place to find already that piece of functionality! + +## Got bulk? + +Have a look at the functionality provided by + +* `r Biocpkg("iSEEde")` +* `r Biocpkg("iSEEpathways")` + +These can be ideal companions for exploring DE results. + +`r Biocpkg("iSEEde")` and `r Biocpkg("iSEEpathways")` are two new Bioconductor packages that provide `r Biocpkg("iSEE")` panels specifically aimed towards exploration of differential expression and pathway analysis results. +More precisely, `r Biocpkg("iSEEde")` provides the `VolcanoPlot`, `MAPlot`, `LogFCLogFCPlot` and `DETable` panels. + +## Got many datasets? + +Have a look at the functionality provided by + +* `r Biocpkg("iSEEhub")` +* `r Biocpkg("iSEEindex")` + +The `r Biocpkg("iSEEhub")` package provides a custom landing page for an `r Biocpkg("iSEE")` application interfacing with the Bioconductor `r Biocpkg("ExperimentHub")`. +The landing page allows users to browse the ExperimentHub, select a data set, download and cache it, and import it directly into an iSEE app. + +`r Biocpkg("iSEEindex")` provides an interface to **any** collection of data sets within a single iSEE web-application. +The main functionality of this package is to define a custom landing page allowing app maintainers to list a custom collection of data sets that users can select from and directly load objects into an iSEE web application. + +> One iSEE instance to ~~rule~~ exlore them all... + +A more elaborate example is available at [https://rehwinkellab.shinyapps.io/ifnresource/](https://rehwinkellab.shinyapps.io/ifnresource/). +The source can be found at [https://github.com/kevinrue/IFNresource](https://github.com/kevinrue/IFNresource). + + + + + + + +Potential use cases can include: + +* An app to present and explore the different datasets in your next publication +* An app to explore collection of datasets collaboratively, in consortium-like initiatives +* An app to mirror and enhance the content of e.g. the CellxGene data portal +* Got any ideas on how to use iSEE for such deployments? + +# Interoperability + +"Wait, I got Seurat/Anndata objects". + +The single cell communities got you covered: + +## From Seurat... + +```{r eval=FALSE} +library("Seurat") + +seurat_object <- readRDS("datasets/seurat_pbmc3k.RDS") +sce_from_seurat <- Seurat::as.SingleCellExperiment( + seurat_object +) +sce_from_seurat + + +iSEE(sce_from_seurat) +``` + +## From AnnData... + +... which is basically able to serve any dataset available throught the CELLxGENE Data Portal! + +```{r eval=FALSE} +library("zellkonverter") + +sce_from_anndata <- zellkonverter::readH5AD(file = "datasets/anndata_pbmc3k.h5ad") +sce_from_anndata + +iSEE(sce_from_anndata) +``` + +An example could be... + +https://cellxgene.cziscience.com/e/c7856243-c59a-4b70-8ce7-25b94c2d9da1.cxg/ + + +# I want moaaaaar on iSEE! + +For more extensive descriptions of the different parts of the interface, we refer to the [overview](https://isee.github.io/iSEEWorkshopEuroBioc2020/articles/overview.html) vignette in a previous, extended workshop on `r Biocpkg("iSEE")`. + +Additional material can also be found at these other repositories: + +* https://isee.github.io/iSEEWorkshop2020/ +* https://isee.github.io/iSEEWorkshopEuroBioc2020/ +* https://isee.github.io/iSEEDemoEuroBioC2023/ + +# Session info {-} + +```{r} +sessionInfo() +```