diff --git a/DESCRIPTION b/DESCRIPTION index 78fe4ee..537cdf8 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: ShinyCell Type: Package Title: Shiny Interactive Web Apps for Single-Cell Data -Version: 1.0.1 +Version: 1.1.0 Author: John F. Ouyang Maintainer: John F. Ouyang Description: Shiny apps for interactive exploration of single-cell data @@ -13,6 +13,7 @@ Depends: data.table (>= 1.12.2), Matrix (>= 1.2-17), hdf5r (>= 1.2.0), + reticulate (>= 1.13), R.utils (>= 2.8.0), ggplot2 (>= 3.3.0), grid , diff --git a/README.md b/README.md index 28216e7..6449449 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,3 @@ ---- -output: - pdf_document: default - html_document: default ---- # ShinyCell package `ShinyCell` is a R package that allows users to create interactive Shiny-based web applications to visualise single-cell data via (i) visualising cell diff --git a/docs/1aesthetics.html b/docs/1aesthetics.html new file mode 100644 index 0000000..c4eda42 --- /dev/null +++ b/docs/1aesthetics.html @@ -0,0 +1,1668 @@ + + + + + + + + + + + + + + +1aesthetics + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+
+
+
+
+ +
+ + + + + + + +

Here, we present a detailed walkthrough on how ShinyCell can be used to create a Shiny app from single-cell data objects. In particular, we will focus on how users can customise what metadata is to be included, their labels and colour palettes. A live version of the shiny app generated here can be found at shinycell1.ddnetbio.com.

+

To demonstrate, we will use single-cell data (Seurat object) containing intermediates collected during the reprogramming of human fibroblast into induced pluripotent stem cells using the RSeT media condition, taken from Liu, Ouyang, Rossello et al. Nature (2020). The Seurat object can be downloaded here.

+
+

Load data and create ShinyCell configuration

+

First, we will load the Seurat object and run createConfig() to create a ShinyCell configuration scConf. The scConf is a data.table containing (i) the single-cell metadata to display on the Shiny app, (ii) ordering of factors / categories for categorical metadata e.g. library / cluster and (iii) colour palette associated with each metadata. Thus, scConf acts as an “instruction manual” to build the Shiny app without modifying the original single-cell data.

+
library(Seurat)
+library(ShinyCell)
+
+# Create ShinyCell config
+getExampleData()                       # Download example dataset (~200 MB)
+seu <- readRDS("readySeu_rset.rds")
+scConf = createConfig(seu)
+

To visualise the contents of the Shiny app prior to building the actual app, we can run showLegend() to display the legends associated with all the single-cell metadata. This allows users to visually inspect which metadata to be shown on the Shiny app. This is useful for identifying repetitive metadata and checking how factors / categories for categorical metadata will look in the eventual Shiny app. Categorical metadata and colour palettes are shown first, followed by continuous metadata which are shown collectively.

+
showLegend(scConf)
+

+
+
+

Add / remove / modify metadata and colour palette

+

It is possible to modify scConf directly but this might be prone to error. Thus, we provided numerous convenience functions to modify scConf and ultimately the Shiny app. In this example, we note that the orig.ident and library as well as RNA_snn_res.0.5 and cluster metadata are similar. To exclude metadata from the Shiny app, we can run delMeta(). Furthermore, we can modify how the names of metadata appear by running modMetaName(). In this case, we changed the names of some metadata to make them more meaningful.

+

By default, colours for categorical metadata are generated by interpolating colours from the “Paired” colour palette in the RColorBrewer package. To modify the colour palette, we can run modColours(). Here, we changed the colours for the library metadata to match that in the publication. It is also possible to modify the labels for each category via modLabels(). For example, we changed the labels for the library metadata from upper case to lower case. After modifying scConf, it is reccomended to run showLegend() to inspect the changes made.

+
# Delete excessive metadata and rename some metadata
+scConf = delMeta(scConf, c("orig.ident", "RNA_snn_res.0.5", "phase"))
+scConf = modMetaName(scConf, 
+                     meta.to.mod = c("nUMI", "nGene", "pctMT", "pctHK"), 
+                     new.name = c("No. UMIs", "No. detected genes",
+                                  "% MT genes", "% HK genes"))
+showLegend(scConf)
+
+# Modify colours and labels
+scConf = modColours(scConf, meta.to.mod = "library", 
+                    new.colours= c("black", "darkorange", "blue", "pink2"))
+scConf = modLabels(scConf, meta.to.mod = "library", 
+                   new.labels = c("fm", "pr", "nr", "rr"))
+showLegend(scConf)
+

+
+
+

Change order of appearance of metadata and defaults

+

Apart from showLegend(), users can also run showOrder() to display the order in which metadata will appear in the dropdown menu when selecting which metadata to plot in the Shiny app. A table will be printed showing the actual name of the metadata in the single-cell object and the display name in the Shiny app. The metadata type (either categorical or continuous) is also provided with the number of categories “nlevels”. Finally, the “default” column indicates which metadata are the primary and secondary default.

+
showOrder(scConf)
+

+

Here, we introduce a few more functions that might be useful in modifying the Shiny app. Users can add metadata back via addMeta(). The newly added metadata (in this case, the phase metadata) is appended to the bottom of the list as shown by showOrder(). Next, we can reorder the order in which metadata appear in the dropdown menu in the Shiny app via reorderMeta(). Here, we shifted the phase metadata up the list. Finally, users can change the default metadata to plot via modDefault(). Again, it is reccomended to run showOrder() frequently to check how the metadata is changed.

+
# Add metadata back, reorder, default
+scConf = addMeta(scConf, "phase", seu) 
+showOrder(scConf)
+scConf = reorderMeta(scConf, scConf$ID[c(1:5,22,6:21)])
+showOrder(scConf)
+scConf = modDefault(scConf, "library", "identity")
+showOrder(scConf)
+

+
+
+

Generate Shiny app

+

After modifying scConf to one’s satisfaction, we are almost ready to build the Shiny app. Prior to building the Shiny app, users can run checkConfig() to check if the scConf is ready. This is especially useful if users have manually modified the scConf. Users can also add a footnote to the Shiny app and one potential use is to include the reference for the dataset. Here, we provide an example of including the citation as the Shiny app footnote.

+
# Build shiny app
+checkConfig(scConf, seu)
+footnote = paste0(
+  'strong("Reference: "), "Liu X., Ouyang J.F., Rossello F.J. et al. ",',
+  'em("Nature "), strong("586,"), "101-107 (2020) ",',
+  'a("doi:10.1038/s41586-020-2734-6",',
+  'href = "https://www.nature.com/articles/s41586-020-2734-6",',
+  'target="_blank"), style = "font-size: 125%;"'
+)
+

Now, we can build the shiny app! A few more things need to be specified here. In this example, the Seurat object uses Ensembl IDs and we would like to convert them to more user-friendly gene symbols in the Shiny app. ShinyCell can do this conversion (for human and mouse datasets) conveniently by specifying gene.mapping = TRUE. If your dataset is already in gene symbols, you can leave out this argument to not perform the conversion. Furthermore, ShinyCell uses the “RNA” assay and “data” slot in Seurat objects as the gene expression data. If you have performed any data integration and would like to use the integrated data instead, please specify gex.assay = "integrated. Also, default genes to plot can be specified where default.gene1 and default.gene2 corresponds to the default genes when plotting gene expression on reduced dimensions while default.multigene contains the default set of multiple genes when plotting bubbleplots or heatmaps. If unspecified, ShinyCell will automatically select some genes present in the dataset as default genes.

+
makeShinyApp(seu, scConf, gene.mapping = TRUE, 
+             gex.assay = "RNA", gex.slot = "data",
+             shiny.title = "ShinyCell Tutorial",
+             shiny.dir = "shinyApp/", shiny.footnotes = footnote,
+             default.gene1 = "NANOG", default.gene2 = "DNMT3L",
+             default.multigene = c("ANPEP","NANOG","ZIC2","NLGN4X","DNMT3L",
+                                   "DPPA5","SLC7A2","GATA3","KRT19"))
+

Under the hood, makeShinyApp() does two things: generate (i) the data files required for the Shiny app and (ii) the code files, namely server.R and ui.R. The generated files can be found in the shinyApp/ folder. To run the app locally, use RStudio to open either server.R or ui.R in the shiny app folder and click on “Run App” in the top right corner. The shiny app can also be deployed via online platforms e.g. shinyapps.io or hosted via Shiny Server. The shiny app look like this, containing five tabs. Cell information and gene expression are plotted on UMAP in the first tab while two different cell information / gene expression are plotted on UMAP in the second / third tab respectively. Violin plot or box plot of cell information or gene expression distribution can be found in the fourth tab. Lastly, a bubbleplot or heatmap can be generated in the fifth tab. A live version of the shiny app can be found at shinycell1.ddnetbio.com.

+

With the Shiny app, users can interactively explore their single-cell data, varying the cell information / gene expression to plot. Furthermore, these plots can be exported into PDF / PNG for presentations / publications. Users can also click on the “Toggle graphics controls” or “Toggle plot controls” to fine-tune certain aspects of the plots e.g. point size.

+

+
+ + + +
+
+ +
+ + + + + + + + + + + + + + + + diff --git a/docs/1aesthetics.md b/docs/1aesthetics.md new file mode 100644 index 0000000..c55c34f --- /dev/null +++ b/docs/1aesthetics.md @@ -0,0 +1,214 @@ +--- +title: | + | Tutorial for changing ShinyCell aesthetics and other settings +author: | + | John F. Ouyang +date: "Jan 2021" +output: + html_document: + toc: true + toc_depth: 2 + toc_float: + collapsed: false + pdf_document: default +fontsize: 12pt +pagetitle: "1aesthetics" +--- + + +Here, we present a detailed walkthrough on how `ShinyCell` can be used to +create a Shiny app from single-cell data objects. In particular, we will focus +on how users can customise what metadata is to be included, their labels and +colour palettes. A live version of the shiny app generated here can be found at +[shinycell1.ddnetbio.com](http://shinycell1.ddnetbio.com). + +To demonstrate, we will use single-cell data (Seurat object) containing +intermediates collected during the reprogramming of human fibroblast into +induced pluripotent stem cells using the RSeT media condition, taken from +[Liu, Ouyang, Rossello et al. Nature (2020)]( +https://www.nature.com/articles/s41586-020-2734-6). The Seurat object can be +[downloaded here](http://files.ddnetbio.com/hrpiFiles/readySeu_rset.rds). + + +## Load data and create ShinyCell configuration +First, we will load the Seurat object and run `createConfig()` to create a +ShinyCell configuration `scConf`. The `scConf` is a data.table containing (i) +the single-cell metadata to display on the Shiny app, (ii) ordering of factors +/ categories for categorical metadata e.g. library / cluster and (iii) colour +palette associated with each metadata. Thus, `scConf` acts as an "instruction +manual" to build the Shiny app without modifying the original single-cell data. + +``` r +library(Seurat) +library(ShinyCell) + +# Create ShinyCell config +getExampleData() # Download example dataset (~200 MB) +seu <- readRDS("readySeu_rset.rds") +scConf = createConfig(seu) +``` + +To visualise the contents of the Shiny app prior to building the actual app, +we can run `showLegend()` to display the legends associated with all the +single-cell metadata. This allows users to visually inspect which metadata to +be shown on the Shiny app. This is useful for identifying repetitive metadata +and checking how factors / categories for categorical metadata will look in +the eventual Shiny app. Categorical metadata and colour palettes are shown +first, followed by continuous metadata which are shown collectively. + +``` r +showLegend(scConf) +``` + +![](../images/detailed-leg1.png) + + +## Add / remove / modify metadata and colour palette +It is possible to modify `scConf` directly but this might be prone to error. +Thus, we provided numerous convenience functions to modify `scConf` and +ultimately the Shiny app. In this example, we note that the `orig.ident` and +`library` as well as `RNA_snn_res.0.5` and `cluster` metadata are similar. To +exclude metadata from the Shiny app, we can run `delMeta()`. Furthermore, we +can modify how the names of metadata appear by running `modMetaName()`. In +this case, we changed the names of some metadata to make them more meaningful. + +By default, colours for categorical metadata are generated by interpolating +colours from the "Paired" colour palette in the RColorBrewer package. To +modify the colour palette, we can run `modColours()`. Here, we changed the +colours for the library metadata to match that in the publication. It is also +possible to modify the labels for each category via `modLabels()`. For +example, we changed the labels for the library metadata from upper case to +lower case. After modifying `scConf`, it is reccomended to run `showLegend()` +to inspect the changes made. + +``` r +# Delete excessive metadata and rename some metadata +scConf = delMeta(scConf, c("orig.ident", "RNA_snn_res.0.5", "phase")) +scConf = modMetaName(scConf, + meta.to.mod = c("nUMI", "nGene", "pctMT", "pctHK"), + new.name = c("No. UMIs", "No. detected genes", + "% MT genes", "% HK genes")) +showLegend(scConf) + +# Modify colours and labels +scConf = modColours(scConf, meta.to.mod = "library", + new.colours= c("black", "darkorange", "blue", "pink2")) +scConf = modLabels(scConf, meta.to.mod = "library", + new.labels = c("fm", "pr", "nr", "rr")) +showLegend(scConf) +``` + +![](../images/detailed-leg2.png) + + +## Change order of appearance of metadata and defaults +Apart from `showLegend()`, users can also run `showOrder()` to display the +order in which metadata will appear in the dropdown menu when selecting which +metadata to plot in the Shiny app. A table will be printed showing the actual +name of the metadata in the single-cell object and the display name in the +Shiny app. The metadata type (either categorical or continuous) is also +provided with the number of categories "nlevels". Finally, the "default" +column indicates which metadata are the primary and secondary default. + +``` r +showOrder(scConf) +``` + +![](../images/detailed-ord1.png) + +Here, we introduce a few more functions that might be useful in modifying the +Shiny app. Users can add metadata back via `addMeta()`. The newly added +metadata (in this case, the phase metadata) is appended to the bottom of the +list as shown by `showOrder()`. Next, we can reorder the order in which +metadata appear in the dropdown menu in the Shiny app via `reorderMeta()`. +Here, we shifted the phase metadata up the list. Finally, users can change the +default metadata to plot via `modDefault()`. Again, it is reccomended to run +`showOrder()` frequently to check how the metadata is changed. + +``` r +# Add metadata back, reorder, default +scConf = addMeta(scConf, "phase", seu) +showOrder(scConf) +scConf = reorderMeta(scConf, scConf$ID[c(1:5,22,6:21)]) +showOrder(scConf) +scConf = modDefault(scConf, "library", "identity") +showOrder(scConf) +``` + +![](../images/detailed-ord2.png) + + +## Generate Shiny app +After modifying `scConf` to one's satisfaction, we are almost ready to build +the Shiny app. Prior to building the Shiny app, users can run `checkConfig()` +to check if the `scConf` is ready. This is especially useful if users have +manually modified the `scConf`. Users can also add a footnote to the Shiny app +and one potential use is to include the reference for the dataset. Here, we +provide an example of including the citation as the Shiny app footnote. + +``` r +# Build shiny app +checkConfig(scConf, seu) +footnote = paste0( + 'strong("Reference: "), "Liu X., Ouyang J.F., Rossello F.J. et al. ",', + 'em("Nature "), strong("586,"), "101-107 (2020) ",', + 'a("doi:10.1038/s41586-020-2734-6",', + 'href = "https://www.nature.com/articles/s41586-020-2734-6",', + 'target="_blank"), style = "font-size: 125%;"' +) +``` + +Now, we can build the shiny app! A few more things need to be specified here. +In this example, the Seurat object uses Ensembl IDs and we would like to +convert them to more user-friendly gene symbols in the Shiny app. `ShinyCell` +can do this conversion (for human and mouse datasets) conveniently by +specifying `gene.mapping = TRUE`. If your dataset is already in gene symbols, +you can leave out this argument to not perform the conversion. Furthermore, +`ShinyCell` uses the "RNA" assay and "data" slot in Seurat objects as the gene +expression data. If you have performed any data integration and would like to +use the integrated data instead, please specify `gex.assay = "integrated`. +Also, default genes to plot can be specified where `default.gene1` and +`default.gene2` corresponds to the default genes when plotting gene expression +on reduced dimensions while `default.multigene` contains the default set of +multiple genes when plotting bubbleplots or heatmaps. If unspecified, +`ShinyCell` will automatically select some genes present in the dataset as +default genes. + +``` r +makeShinyApp(seu, scConf, gene.mapping = TRUE, + gex.assay = "RNA", gex.slot = "data", + shiny.title = "ShinyCell Tutorial", + shiny.dir = "shinyApp/", shiny.footnotes = footnote, + default.gene1 = "NANOG", default.gene2 = "DNMT3L", + default.multigene = c("ANPEP","NANOG","ZIC2","NLGN4X","DNMT3L", + "DPPA5","SLC7A2","GATA3","KRT19")) +``` + +Under the hood, `makeShinyApp()` does two things: generate (i) the data files +required for the Shiny app and (ii) the code files, namely `server.R` and +`ui.R`. The generated files can be found in the `shinyApp/` folder. To run the +app locally, use RStudio to open either `server.R` or `ui.R` in the shiny app +folder and click on "Run App" in the top right corner. The shiny app can also +be deployed via online platforms e.g. [shinyapps.io](https://www.shinyapps.io/) +or hosted via Shiny Server. The shiny app look like this, containing five tabs. +Cell information and gene expression are plotted on UMAP in the first tab while +two different cell information / gene expression are plotted on UMAP in the +second / third tab respectively. Violin plot or box plot of cell information or +gene expression distribution can be found in the fourth tab. Lastly, a +bubbleplot or heatmap can be generated in the fifth tab. +A live version of the shiny app can be found at +[shinycell1.ddnetbio.com](http://shinycell1.ddnetbio.com). + +With the Shiny app, users can interactively explore their single-cell data, +varying the cell information / gene expression to plot. Furthermore, these +plots can be exported into PDF / PNG for presentations / publications. Users +can also click on the "Toggle graphics controls" or "Toggle plot controls" to +fine-tune certain aspects of the plots e.g. point size. + +![](../images/detailed-shiny1.png) +![](../images/detailed-shiny2.png) +![](../images/detailed-shiny3.png) +![](../images/detailed-shiny4.png) +![](../images/detailed-shiny5.png) + + diff --git a/docs/2multi.html b/docs/2multi.html new file mode 100644 index 0000000..2a642d9 --- /dev/null +++ b/docs/2multi.html @@ -0,0 +1,1655 @@ + + + + + + + + + + + + + + +2multi + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+
+
+
+
+ +
+ + + + + + + +

Users might want to include multiple single-cell datasets into a single Shiny app and ShinyCell provides this functionality. We will demonstrate how to create a shiny app containing two single-cell datasets. A live version of the shiny app generated here can be found at shinycell2.ddnetbio.com.

+

To further change the aesthetics and ordering of metadata, please refer to the Tutorial for changing ShinyCell aesthetics and other settings.

+
+

Load data and create ShinyCell configuration

+

For the first example dataset, we will use scRNA-seq data (Seurat object) containing intermediates collected during reprogramming of human fibroblast into induced pluripotent stem cells using the RSeT media condition, which can be downloaded here. For the second example dataset, we will use scRNA-seq of day 21 reprogramming intermediates from the same publication, which can be downloaded here. After downloading the data, we will begin by loading the required libraries.

+
library(Seurat)
+library(ShinyCell)
+getExampleData("multi")      # Download multiple example datasets (~400 MB)
+
+
+

Configure settings for each dataset

+

To create a multi-dataset Shiny app, we need to configure the settings for each dataset separately. We will do so for the first dataset as follows. A ShinyCell configuration scConf1 is created, followed by modifying various aspects of the Shiny app e.g. removing excessive metadata, modifying the display names of metadata and modifying the colour palettes. For a more detailed explanation on how to customise the shiny app, refer to Tutorial for changing ShinyCell aesthetics and other settings. We then run makeShinyFiles() to generate the files related to the first dataset. Notice that we specified shiny.prefix = "sc1" and this prefix is used to identify that the files contain single-cell data related to the first dataset. The remaining arguments are the same as explained in the Tutorial for changing ShinyCell aesthetics and other settings.

+
seu <- readRDS("readySeu_rset.rds")
+scConf1 = createConfig(seu)
+scConf1 = delMeta(scConf1, c("orig.ident", "RNA_snn_res.0.5"))
+scConf1 = modMetaName(scConf1, meta.to.mod = c("nUMI", "nGene", "pctMT", "pctHK"), 
+                      new.name = c("No. UMIs", "No. detected genes",
+                                   "% MT genes", "% HK genes"))
+scConf1 = modColours(scConf1, meta.to.mod = "library", 
+                     new.colours= c("black", "darkorange", "blue", "pink2"))
+makeShinyFiles(seu, scConf1, gex.assay = "RNA", gex.slot = "data",
+               gene.mapping = TRUE, shiny.prefix = "sc1",
+               shiny.dir = "shinyAppMulti/",
+               default.gene1 = "NANOG", default.gene2 = "DNMT3L",
+               default.multigene = c("ANPEP","NANOG","ZIC2","NLGN4X","DNMT3L",
+                                     "DPPA5","SLC7A2","GATA3","KRT19"),
+               default.dimred = c("UMAP_1", "UMAP_2"))
+

We then repeat the same procedure for the second dataset to generate the files required for the Shiny app. Notice that we used a different prefix here shiny.prefix = "sc2".

+
seu <- readRDS("readySeu_d21i.rds")
+scConf2 = createConfig(seu)
+scConf2 = delMeta(scConf2, c("orig.ident", "RNA_snn_res.0.5"))
+scConf2 = modMetaName(scConf2, meta.to.mod = c("nUMI", "nGene", "pctMT", "pctHK"), 
+                      new.name = c("No. UMIs", "No. detected genes",
+                                   "% MT genes", "% HK genes"))
+scConf2 = modColours(scConf2, meta.to.mod = "library", 
+                     new.colours= c("black", "blue", "purple"))
+makeShinyFiles(seu, scConf2, gex.assay = "RNA", gex.slot = "data",
+               gene.mapping = TRUE, shiny.prefix = "sc2",
+               shiny.dir = "shinyAppMulti/",
+               default.gene1 = "GATA3", default.gene2 = "DNMT3L",
+               default.multigene = c("ANPEP","NANOG","ZIC2","NLGN4X","DNMT3L",
+                                     "DPPA5","SLC7A2","GATA3","KRT19"),
+               default.dimred = c("UMAP_1", "UMAP_2"))
+
+
+

Generate code for Shiny app

+

We can the proceed to the final part where we generate the code for the Shiny app using the makeShinyCodesMulti() function. To specify that two datasets will be included in this Shiny app, we input the prefixes of the two datasets shiny.prefix = c("sc1", "sc2"). Also, users need to specify section headers for each dataset via the shiny.headers argument. The remaining arguments are the same as explained in the Tutorial for changing ShinyCell aesthetics and other settings.

+
footnote = paste0(
+  'strong("Reference: "), "Liu X., Ouyang J.F., Rossello F.J. et al. ",',
+  'em("Nature "), strong("586,"), "101-107 (2020) ",',
+  'a("doi:10.1038/s41586-020-2734-6",',
+  'href = "https://www.nature.com/articles/s41586-020-2734-6",',
+  'target="_blank"), style = "font-size: 125%;"'
+)
+makeShinyCodesMulti(
+  shiny.title = "Multi-dataset Tutorial", shiny.footnotes = footnote,
+  shiny.prefix = c("sc1", "sc2"),
+  shiny.headers = c("RSeT reprogramming", "Day 21 intermediates"), 
+  shiny.dir = "shinyAppMulti/")
+

Now, we have both the data and code for the Shiny app and we can run the Shiny app. Each dataset can be found in their corresponding tabs and clicking on the tab creates a dropdown to change the type of plot to display on the Shiny app. This tutorial can be easily expanded to include three or more datasets. Users simply have to create the corresponding data files for each dataset and finally generate the code for the Shiny app. A live version of the shiny app can be found at shinycell2.ddnetbio.com.

+

+
+ + + +
+
+ +
+ + + + + + + + + + + + + + + + diff --git a/docs/2multi.md b/docs/2multi.md new file mode 100644 index 0000000..d6ba498 --- /dev/null +++ b/docs/2multi.md @@ -0,0 +1,138 @@ +--- +title: | + | Tutorial for creating a ShinyCell app containing several single-cell datasets +author: | + | John F. Ouyang +date: "Jan 2021" +output: + html_document: + toc: true + toc_depth: 2 + toc_float: + collapsed: false + pdf_document: default +fontsize: 12pt +pagetitle: "2multi" +--- + +Users might want to include multiple single-cell datasets into a single Shiny +app and `ShinyCell` provides this functionality. We will demonstrate how to +create a shiny app containing two single-cell datasets. A live version of the +shiny app generated here can be found at [shinycell2.ddnetbio.com]( +http://shinycell2.ddnetbio.com). + +To further change the aesthetics and ordering of metadata, please refer to the +[Tutorial for changing ShinyCell aesthetics and other settings]( +https://htmlpreview.github.io/?https://github.com/SGDDNB/ShinyCell/blob/master/docs/1aesthetics.html). + + +## Load data and create ShinyCell configuration +For the first example dataset, we will use scRNA-seq data (Seurat object) +containing intermediates collected during reprogramming of human fibroblast +into induced pluripotent stem cells using the RSeT media condition, which can +be [downloaded here](http://files.ddnetbio.com/hrpiFiles/readySeu_rset.rds). +For the second example dataset, we will use scRNA-seq of day 21 reprogramming +intermediates from the same publication, which can be +[downloaded here](http://files.ddnetbio.com/hrpiFiles/readySeu_d21i.rds). +After downloading the data, we will begin by loading the required libraries. + +``` r +library(Seurat) +library(ShinyCell) +getExampleData("multi") # Download multiple example datasets (~400 MB) +``` + + +## Configure settings for each dataset +To create a multi-dataset Shiny app, we need to configure the settings for +each dataset separately. We will do so for the first dataset as follows. A +ShinyCell configuration `scConf1` is created, followed by modifying various +aspects of the Shiny app e.g. removing excessive metadata, modifying the +display names of metadata and modifying the colour palettes. For a more +detailed explanation on how to customise the shiny app, refer to +[Tutorial for changing ShinyCell aesthetics and other settings]( +https://htmlpreview.github.io/?https://github.com/SGDDNB/ShinyCell/blob/master/docs/1aesthetics.html). +We then run `makeShinyFiles()` to generate the files related to the first +dataset. Notice that we specified `shiny.prefix = "sc1"` and this prefix is +used to identify that the files contain single-cell data related to the first +dataset. The remaining arguments are the same as explained in the +[Tutorial for changing ShinyCell aesthetics and other settings]( +https://htmlpreview.github.io/?https://github.com/SGDDNB/ShinyCell/blob/master/docs/1aesthetics.html). + +``` r +seu <- readRDS("readySeu_rset.rds") +scConf1 = createConfig(seu) +scConf1 = delMeta(scConf1, c("orig.ident", "RNA_snn_res.0.5")) +scConf1 = modMetaName(scConf1, meta.to.mod = c("nUMI", "nGene", "pctMT", "pctHK"), + new.name = c("No. UMIs", "No. detected genes", + "% MT genes", "% HK genes")) +scConf1 = modColours(scConf1, meta.to.mod = "library", + new.colours= c("black", "darkorange", "blue", "pink2")) +makeShinyFiles(seu, scConf1, gex.assay = "RNA", gex.slot = "data", + gene.mapping = TRUE, shiny.prefix = "sc1", + shiny.dir = "shinyAppMulti/", + default.gene1 = "NANOG", default.gene2 = "DNMT3L", + default.multigene = c("ANPEP","NANOG","ZIC2","NLGN4X","DNMT3L", + "DPPA5","SLC7A2","GATA3","KRT19"), + default.dimred = c("UMAP_1", "UMAP_2")) +``` + +We then repeat the same procedure for the second dataset to generate the files +required for the Shiny app. Notice that we used a different prefix here +`shiny.prefix = "sc2"`. + +``` r +seu <- readRDS("readySeu_d21i.rds") +scConf2 = createConfig(seu) +scConf2 = delMeta(scConf2, c("orig.ident", "RNA_snn_res.0.5")) +scConf2 = modMetaName(scConf2, meta.to.mod = c("nUMI", "nGene", "pctMT", "pctHK"), + new.name = c("No. UMIs", "No. detected genes", + "% MT genes", "% HK genes")) +scConf2 = modColours(scConf2, meta.to.mod = "library", + new.colours= c("black", "blue", "purple")) +makeShinyFiles(seu, scConf2, gex.assay = "RNA", gex.slot = "data", + gene.mapping = TRUE, shiny.prefix = "sc2", + shiny.dir = "shinyAppMulti/", + default.gene1 = "GATA3", default.gene2 = "DNMT3L", + default.multigene = c("ANPEP","NANOG","ZIC2","NLGN4X","DNMT3L", + "DPPA5","SLC7A2","GATA3","KRT19"), + default.dimred = c("UMAP_1", "UMAP_2")) +``` + + +## Generate code for Shiny app +We can the proceed to the final part where we generate the code for the Shiny +app using the `makeShinyCodesMulti()` function. To specify that two datasets +will be included in this Shiny app, we input the prefixes of the two datasets +`shiny.prefix = c("sc1", "sc2")`. Also, users need to specify section headers +for each dataset via the `shiny.headers` argument. The remaining arguments are +the same as explained in the +[Tutorial for changing ShinyCell aesthetics and other settings]( +https://htmlpreview.github.io/?https://github.com/SGDDNB/ShinyCell/blob/master/docs/1aesthetics.html). + +``` r +footnote = paste0( + 'strong("Reference: "), "Liu X., Ouyang J.F., Rossello F.J. et al. ",', + 'em("Nature "), strong("586,"), "101-107 (2020) ",', + 'a("doi:10.1038/s41586-020-2734-6",', + 'href = "https://www.nature.com/articles/s41586-020-2734-6",', + 'target="_blank"), style = "font-size: 125%;"' +) +makeShinyCodesMulti( + shiny.title = "Multi-dataset Tutorial", shiny.footnotes = footnote, + shiny.prefix = c("sc1", "sc2"), + shiny.headers = c("RSeT reprogramming", "Day 21 intermediates"), + shiny.dir = "shinyAppMulti/") +``` + +Now, we have both the data and code for the Shiny app and we can run the Shiny +app. Each dataset can be found in their corresponding tabs and clicking on the +tab creates a dropdown to change the type of plot to display on the Shiny app. +This tutorial can be easily expanded to include three or more datasets. Users +simply have to create the corresponding data files for each dataset and finally +generate the code for the Shiny app. +A live version of the shiny app can be found at +[shinycell2.ddnetbio.com](http://shinycell2.ddnetbio.com). + +![](../images/multi-shiny.png) + diff --git a/docs/3otherformat.html b/docs/3otherformat.html new file mode 100644 index 0000000..4df2216 --- /dev/null +++ b/docs/3otherformat.html @@ -0,0 +1,1652 @@ + + + + + + + + + + + + + + +3otherformat + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+
+
+
+
+ +
+ + + + + + + +

ShinyCell supports all four common single-cell data formats, namely h5ad, loom, SCE and Seurat. In our other tutorials, we focused on using Seurat objects as inputs. Here, we will explain how to use the other supported file formats to create shiny apps from single-cell data objects.

+

Overall, the process is identical to the other tutorials except that the file path is required for h5ad / loom files and the SCE object itself is supplied for SingleCellExperiment objects. To further change the aesthetics and ordering of metadata, please refer to the Tutorial for changing ShinyCell aesthetics and other settings. To include multiple datasets into one shiny app, please refer to the Tutorial for creating a ShinyCell app containing several single-cell datasets.

+
+

h5ad file as input

+

For using h5ad file as input, we will demonstrate using the scRNA-seq of endocrine development in the pancreas, taken from Bastidas-Ponce et al. Development (2018). The dataset has been further processed for use with the scVelo package.

+
library(ShinyCell)
+getExampleData("h5ad")
+
+inpFile = "endocrinogenesis_day15.h5ad"
+scConf = createConfig(inpFile)
+makeShinyApp(inpFile, scConf, 
+             default.gene1 = "Pcsk2", default.gene2 = "Dcdc2a",
+             default.multigene = c("Pcsk2", "Dcdc2a", "Ank", "Gng12", "Top2a",
+                                   "Pak3", "Tmem163", "Nfib", "Pim2", "Smoc1"),
+             shiny.dir = "shinyAppH5ad/", 
+             shiny.title = "ShinyCell h5ad Example")
+

Running the above code generates a shiny app in the shinyAppH5ad/ folder, looking like this:

+

+
+
+

loom file as input

+

For using loom file as input, we will demonstrate using the scRNA-seq of hematopoietic differentiation, taken from Setty et al. Nature Biotechnology (2019). The dataset has been further processed using the ASAP pipeline; key: xr7ne3.

+
library(ShinyCell)
+getExampleData("loom")
+
+inpFile <- "xr7ne3_dim_reduction_13225_output.loom"
+scConf = createConfig(inpFile, meta.to.include = 
+                        c("_Depth","_Detected_Genes","_Mitochondrial_Content",
+                          "_Protein_Coding_Content","_Ribosomal_Content",
+                          "_clust_1_seurat","bundle_version","donor_organism.sex"))
+
+# Manually factor "_clust_1_seurat" column
+scConf[ID == "_clust_1_seurat"]$fID = paste(seq(26), collapse = "|")
+scConf[ID == "_clust_1_seurat"]$fUI = paste(seq(26), collapse = "|")
+scConf[ID == "_clust_1_seurat"]$fCL = 
+  paste0(colorRampPalette(brewer.pal(12, "Paired"))(26), collapse = "|")
+scConf[ID == "_clust_1_seurat"]$fRow = 4
+scConf = modDefault(scConf, "_clust_1_seurat", "bundle_version")
+
+makeShinyApp(inpFile, scConf, 
+             shiny.dir = "shinyAppLoom/", 
+             shiny.title = "ShinyCell loom Example")
+

Note that loom files do not necessarily store the categories / levels information for discrete single-cell metadata. ShinyCell tries to circumvent this by automatically factoring all columns containing text. However, there are cases where the single-cell metadata are integers and it is difficult to automatically detect if these metadata are meant to be treated in a discrete or continuous manner. In this loom file, the seurat clusters _clust_1_seurat is one such example and the categories / levels information have to be manually added into the ShinyCell configuration.

+

Running the above code generates a shiny app in the shinyAppLoom/ folder, looking like this:

+

+
+
+

SCE object as input

+

For using SCE object as input, we will demonstrate using the Seurat object used in the other tutorials. The Seurat object can be easily converted to a SCE object and the SCE object is processed by ShinyCell in the same way as its Seurat counterpart. Here, we reuse the code from the quick start guide.

+
library(Seurat)
+library(ShinyCell)
+
+getExampleData()                       # Download example dataset (~200 MB)
+seu = readRDS("readySeu_rset.rds")
+sce = as.SingleCellExperiment(seu)
+scConf = createConfig(sce)
+makeShinyApp(sce, scConf, gene.mapping = TRUE,
+             shiny.title = "ShinyCell Quick Start")
+
+ + + +
+
+ +
+ + + + + + + + + + + + + + + + diff --git a/docs/3otherformat.md b/docs/3otherformat.md new file mode 100644 index 0000000..640f02e --- /dev/null +++ b/docs/3otherformat.md @@ -0,0 +1,126 @@ +--- +title: | + | Tutorial for other supported file formats (h5ad / loom / SCE) +author: | + | John F. Ouyang +date: "Jan 2021" +output: + html_document: + toc: true + toc_depth: 2 + toc_float: + collapsed: false + pdf_document: default +fontsize: 12pt +pagetitle: "3otherformat" +--- + + +ShinyCell supports all four common single-cell data formats, namely h5ad, +loom, SCE and Seurat. In our other tutorials, we focused on using Seurat +objects as inputs. Here, we will explain how to use the other supported file +formats to create shiny apps from single-cell data objects. + +Overall, the process is identical to the other tutorials except that the file +path is required for h5ad / loom files and the SCE object itself is supplied +for SingleCellExperiment objects. To further change the aesthetics and +ordering of metadata, please refer to the +[Tutorial for changing ShinyCell aesthetics and other settings]( +https://htmlpreview.github.io/?https://github.com/SGDDNB/ShinyCell/blob/master/docs/1aesthetics.html). +To include multiple datasets into one shiny app, please refer to the +[Tutorial for creating a ShinyCell app containing several single-cell datasets]( +https://htmlpreview.github.io/?https://github.com/SGDDNB/ShinyCell/blob/master/docs/2multi.html). + + +## h5ad file as input +For using h5ad file as input, we will demonstrate using the scRNA-seq of +endocrine development in the pancreas, taken from +[Bastidas-Ponce et al. Development (2018)]( +https://dev.biologists.org/content/146/12/dev173849.abstract). The dataset has +been further processed for use with the [scVelo package]( +https://scvelo.readthedocs.io/Pancreas.html). + +``` r +library(ShinyCell) +getExampleData("h5ad") + +inpFile = "endocrinogenesis_day15.h5ad" +scConf = createConfig(inpFile) +makeShinyApp(inpFile, scConf, + default.gene1 = "Pcsk2", default.gene2 = "Dcdc2a", + default.multigene = c("Pcsk2", "Dcdc2a", "Ank", "Gng12", "Top2a", + "Pak3", "Tmem163", "Nfib", "Pim2", "Smoc1"), + shiny.dir = "shinyAppH5ad/", + shiny.title = "ShinyCell h5ad Example") +``` + +Running the above code generates a shiny app in the `shinyAppH5ad/` folder, +looking like this: + +![](../images/other-h5ad.png) + + +## loom file as input +For using loom file as input, we will demonstrate using the scRNA-seq of +hematopoietic differentiation, taken from +[Setty et al. Nature Biotechnology (2019)]( +https://www.nature.com/articles/s41587-019-0068-4). The dataset has +been further processed using the [ASAP pipeline; key: xr7ne3]( +https://asap.epfl.ch/). + +``` r +library(ShinyCell) +getExampleData("loom") + +inpFile <- "xr7ne3_dim_reduction_13225_output.loom" +scConf = createConfig(inpFile, meta.to.include = + c("_Depth","_Detected_Genes","_Mitochondrial_Content", + "_Protein_Coding_Content","_Ribosomal_Content", + "_clust_1_seurat","bundle_version","donor_organism.sex")) + +# Manually factor "_clust_1_seurat" column +scConf[ID == "_clust_1_seurat"]$fID = paste(seq(26), collapse = "|") +scConf[ID == "_clust_1_seurat"]$fUI = paste(seq(26), collapse = "|") +scConf[ID == "_clust_1_seurat"]$fCL = + paste0(colorRampPalette(brewer.pal(12, "Paired"))(26), collapse = "|") +scConf[ID == "_clust_1_seurat"]$fRow = 4 +scConf = modDefault(scConf, "_clust_1_seurat", "bundle_version") + +makeShinyApp(inpFile, scConf, + shiny.dir = "shinyAppLoom/", + shiny.title = "ShinyCell loom Example") +``` + +Note that loom files do not necessarily store the categories / levels +information for discrete single-cell metadata. ShinyCell tries to circumvent +this by automatically factoring all columns containing text. However, there +are cases where the single-cell metadata are integers and it is difficult to +automatically detect if these metadata are meant to be treated in a discrete +or continuous manner. In this loom file, the seurat clusters `_clust_1_seurat` +is one such example and the categories / levels information have to be +manually added into the ShinyCell configuration. + +Running the above code generates a shiny app in the `shinyAppLoom/` folder, +looking like this: + +![](../images/other-loom.png) + + +## SCE object as input +For using SCE object as input, we will demonstrate using the Seurat object +used in the other tutorials. The Seurat object can be easily converted to a +SCE object and the SCE object is processed by ShinyCell in the same way as its +Seurat counterpart. Here, we reuse the code from the quick start guide. + +``` r +library(Seurat) +library(ShinyCell) + +getExampleData() # Download example dataset (~200 MB) +seu = readRDS("readySeu_rset.rds") +sce = as.SingleCellExperiment(seu) +scConf = createConfig(sce) +makeShinyApp(sce, scConf, gene.mapping = TRUE, + shiny.title = "ShinyCell Quick Start") +``` + diff --git a/docs/4cloud.html b/docs/4cloud.html new file mode 100644 index 0000000..20b3724 --- /dev/null +++ b/docs/4cloud.html @@ -0,0 +1,1615 @@ + + + + + + + + + + + + + + +4cloud + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + +
+
+
+
+
+ +
+ + + + + + + +

The shiny app generated by ShinyCell can be easily deployed in a variety of ways, namely via (i) https://www.shinyapps.io/, (ii) in-house server using R Shiny Server or (iii) other cloud computing platforms e.g. Amazon Web Services (AWS). The ease and availability of several cloud options is due to the use of R Shiny backend, which is designed to be easily deployed online.

+
+

shinyapps.io

+

One of the simplest way to deploy the shiny app is via the dedicated online service https://www.shinyapps.io/. First, one has to register for an account, which will prompt the user to create an account name ACCOUNT that will constitute part of the URL of the eventual shiny app. After registration, one has to setup the connection between your R / RStudio and shinyapps.io via the code below. One can then then upload the shiny app by specifying the shiny app directory shinyApp and the app will be available online at https://[ACCOUNT].shinyapps.io/shinyApp/. For more details, refer to the shinyapps user guide.

+
install.packages('rsconnect')     # package to interface shiny apps
+library(rsconnect)
+
+rsconnect::setAccountInfo(name="<ACCOUNT>", 
+                          token="<TOKEN>",
+                          secret="<SECRET>") 
+rsconnect::deployApp("shinyApp/")
+
+
+

R Shiny Server

+

If you have a on-site server, you can deploy the shiny app on the server via R Shiny Server. This requires the installation of R Shiny Server for your corresponding operating system, details of which can be found here.

+

After installing R Shiny Server, the shiny app can be deployed by placing the entire folder shinyApp into the directory /srv/shiny-server/. The shiny app can then accessed online via [IP-address-of-server]:3838/shinyApp. For more details, refer to the Administrator’s Guide.

+
+
+

Amazon Web Services (AWS)

+

It is possible to deploy the shiny app cloud computing platforms. Here, we will briefly outline how to do so on Amazon Web Services (AWS). There are three steps, namely (i) creating a new Elastic Compute Cloud (EC2) instance, (ii) installing R and R Shiny Server and (iii) deploying the shiny app.

+

There are several online tutorials on how to deploy shiny apps on AWS such as https://towardsdatascience.com/how-to-deploy-your-shiny-app-to-aws-856587cd412c and https://www.charlesbordet.com/en/guide-shiny-aws.

+
+ + + +
+
+ +
+ + + + + + + + + + + + + + + + diff --git a/docs/4cloud.md b/docs/4cloud.md new file mode 100644 index 0000000..4775a82 --- /dev/null +++ b/docs/4cloud.md @@ -0,0 +1,71 @@ +--- +title: | + | Instructions on how to deploy ShinyCell apps online +author: | + | John F. Ouyang +date: "Jan 2021" +output: + html_document: + toc: true + toc_depth: 2 + toc_float: + collapsed: false + pdf_document: default +fontsize: 12pt +pagetitle: "4cloud" +--- + + +The shiny app generated by ShinyCell can be easily deployed in a variety of +ways, namely via (i) https://www.shinyapps.io/, (ii) in-house server using R +Shiny Server or (iii) other cloud computing platforms e.g. Amazon Web Services +(AWS). The ease and availability of several cloud options is due to the use of +R Shiny backend, which is designed to be easily deployed online. + + +## shinyapps.io +One of the simplest way to deploy the shiny app is via the dedicated online +service https://www.shinyapps.io/. First, one has to register for an account, +which will prompt the user to create an account name `ACCOUNT` that will +constitute part of the URL of the eventual shiny app. After registration, one +has to setup the connection between your R / RStudio and shinyapps.io via the +code below. One can then then upload the shiny app by specifying the shiny app +directory `shinyApp` and the app will be available online at +`https://[ACCOUNT].shinyapps.io/shinyApp/`. For more details, refer to the +[shinyapps user guide](https://docs.rstudio.com/shinyapps.io/). + +``` r +install.packages('rsconnect') # package to interface shiny apps +library(rsconnect) + +rsconnect::setAccountInfo(name="", + token="", + secret="") +rsconnect::deployApp("shinyApp/") +``` + + +## R Shiny Server +If you have a on-site server, you can deploy the shiny app on the server via +[R Shiny Server](https://rstudio.com/products/shiny/shiny-server/). This +requires the installation of R Shiny Server for your corresponding operating +system, details of which can be found [here]( +https://rstudio.com/products/shiny/download-server/). + +After installing R Shiny Server, the shiny app can be deployed by placing the +entire folder `shinyApp` into the directory `/srv/shiny-server/`. The shiny +app can then accessed online via `[IP-address-of-server]:3838/shinyApp`. For +more details, refer to the [Administrator’s Guide]( +https://docs.rstudio.com/shiny-server/). + + +## Amazon Web Services (AWS) +It is possible to deploy the shiny app cloud computing platforms. Here, we +will briefly outline how to do so on Amazon Web Services (AWS). There are +three steps, namely (i) creating a new Elastic Compute Cloud (EC2) instance, +(ii) installing R and R Shiny Server and (iii) deploying the shiny app. + +There are several online tutorials on how to deploy shiny apps on AWS such as +https://towardsdatascience.com/how-to-deploy-your-shiny-app-to-aws-856587cd412c +and https://www.charlesbordet.com/en/guide-shiny-aws. + diff --git a/images/other-h5ad.png b/images/other-h5ad.png new file mode 100644 index 0000000..ce6cc7a Binary files /dev/null and b/images/other-h5ad.png differ diff --git a/images/other-loom.png b/images/other-loom.png new file mode 100644 index 0000000..39aa6db Binary files /dev/null and b/images/other-loom.png differ