Merge pull request #1 from imbeimainz/fier_up_iSEE

Fier up iSEE

vignettes/bonus_content_04.Rmd

@@ -12,8 +12,8 @@ output:
 vignette: >
   %\VignetteIndexEntry{04. Bonus content}
   %\VignettePackage{iUSEiSEE}
-  %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
+  %\VignetteEngine{knitr::rmarkdown}
 editor_options: 
   chunk_output_type: console
 bibliography: iUSEiSEErefs.bib
@@ -62,9 +62,100 @@ TODO
 
 ## iSEEfier
 
-TODO
+Let's say we are interested in visualizing the expression of a list of specific marker genes in one view, or maybe we created different initial states separately, but would like to visualize them in the same instance. As we previously learned, we can do a lot of these tasks by running the command:
+
+```{r, eval=FALSE}
+# don't run
+iSEE(sce)
+```
+
+then add/remove the panels to our need. This can involve multiple steps (selecting the gene of interest, color by a specific `colData`...), or probably even write multiple lines of code.
+For that we can use the `iSEEfier` package, which streamlines the process of starting (or if you will, firing up) an `iSEE` instance with a small chunk of code, avoiding the tedious way of setting up every `iSEE` panel individually.
+In this chapter we will illustrate a simple example of how to use `iSEEfier`. We will use the same pbmc3k data we worked with during this workshop.
+We start by loading the data:
+
+```{r}
+# import data
+sce <- readRDS(
+  file = system.file("datasets", "sce_pbmc3k.RDS", package = "iUSEiSEE")
+)
+
+sce
+```
+
+For example, we can be interested in visualizing the expression of *GZMB*, *TGFB*, and *CD28* genes all at once. We start by providing a couple of parameters:
+
+```{r}
+# define the list of genes
+feature_list_1 <- c("GZMB", "TGFB1", "CD28")
+# define the cluster/cell type 
+cluster_1 <- "labels_main"
+```
+
+Now we can pass these parameters into `iSEEinit()` to create a customized initial configuration:
+
+```{r}
+# create an initial state with iSEEinit
+initial_1 <- iSEEinit(sce,
+                      features = feature_list_1,
+                      clusters = cluster_1,
+                      add_markdown_panel = TRUE)
+```
+
+The rest can be as easy as passing this initial to the `iSEE()` call:
+
+```{r}
+app <- iSEE(sce, initial = initial_1)
+```
+
+This is how it would look like:
+
+```{r, echo=FALSE, out.width='100%'}
+SCREENSHOT("images/isee-on-fier.png", delay = 30)
+```
+
+
+While we are visualizing the expression of these genes, we might want to take some notes (gene X is more expressed in a certain cell type/cluster than some others, maybe we are trying to annotate the cells ourselves if the annotation wasn't available...) For this, we used the argument `add_markdown_panel = TRUE`. It will display a `MarkdownBoard` panel where we can note our observations without leaving the app.
+
+We can also use the argument `add_dynamicTable_panel=TRUE` to add another custom panel to display the maker genes of certain cluster/cell type.
+
+```{r}
+feature_list_2 <- c("CD74", "CD79B")
+initial_2 <- iSEEinit(sce,
+                      features = feature_list_2,
+                      clusters = cluster_1,
+                      add_markdown_panel = TRUE,
+                      add_dynamicTable_panel = TRUE)
+```
+
+```{r}
+app <- iSEE(sce, initial = initial_2)
+```
+
+We can check the initial's content, or how the included panels are linked between each other without running the app with `view_initial_tiles()` and `view_initial_network()`:
+
+```{r}
+# display a graphical representation of the initial configuration, where the panels are identified by their corresponding colors
+view_initial_tiles(initial = initial_1)
+# display a network visualization for the panels
+view_initial_network(initial_1, plot_format = "igraph")
+```
+
+Another alternative for network visualization would use the interactive widget provided by `visNetwork`:
+
+```{r}
+view_initial_network(initial_1, plot_format = "visNetwork")
+```
+
+It is also possible to combine multiple initials into one:
+
+```{r}
+merged_config <- glue_initials(initial_1, initial_2)
+# check out the content of merged_config
+view_initial_tiles(initial = merged_config)
+```
 
-Najla :)
+`?iSEEfier` is always your friend whenever you need further documentation on the package/a certain function and how to use it.
 
 ## Multi-sample, multi-condition datasets: how to let iSEE shine