bonus_content_04.Rmd

---
title: "iUSEiSEE - Bonus content"
author: "Federico Marini^[marinif@uni-mainz.de], Najla Abassi^[abassina@uni-mainz.de] <br><hr>
  Collection of material developed by the iSEE core dev team <br>
  (Kevin Rue-Albrecht, Federico Marini, Charlotte Soneson, Aaron Lun)"
output: 
    html_document:
      theme: cosmo
      toc: yes
      toc_float: yes
      number_sections: true
vignette: >
  %\VignetteIndexEntry{04. Bonus content}
  %\VignettePackage{iUSEiSEE}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
bibliography: iUSEiSEErefs.bib
---

<img src="iSEE.png" align="right" alt="" width="120" />

```{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 [@Rue-Albrecht2018-isee].

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")
```


# iSEE a challenge: let's reproduce any figure!

We'd like to open up a challenge, with some simple rules:

* You search a nice graphical representation of data
* We try to reproduce this within `iSEE` - as far as this is possible!

Let's suggest a couple of figure/figure panels!  
Enter a couple of suggestions in this GSheet: https://docs.google.com/spreadsheets/d/1poE713rXqzfNdPcKAPN2AxJYXhaxy8GwgAjRsk_UiK8/edit?usp=sharing

# iSEEde and iSEEpathways

iSEEde and iSEEpathways: ideal companions for exploring DE results

We first load the processed `macrophage` data (derived from the work of [@Alasoo2018]) - on this, we already ran the workflow of `DESeq2` [@Love2014] to identify the differentially expressed genes.

```{r}
macrophage_location <- system.file("datasets", "sce_macrophage_readytouse.RDS",
  package = "iUSEiSEE"
)
macrophage_location

sce_macrophage <- readRDS(macrophage_location)

library("iSEE")
library("iSEEde")
library("iSEEpathways")
```

`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. 
These panels can be configured to extract data that was added via the `embedContrastResults()` function above. 
Let's look at an example:

```{r}
app <- iSEE(sce_macrophage, initial = list(
  DETable(
    ContrastName = "IFNgTRUE.SL1344TRUE.DESeq2",
    HiddenColumns = c("baseMean", "lfcSE", "stat")
  ),
  VolcanoPlot(ContrastName = "IFNgTRUE.SL1344TRUE.DESeq2"),
  MAPlot(ContrastName = "IFNgTRUE.SL1344TRUE.DESeq2")
))
```

```{r, echo=FALSE}
SCREENSHOT("images/isee_de_setup1.png", delay = 20)
```


<!-- Possible actions: -->
<!-- select some genes from any panel and pass the selection to others -->
<!-- move panels around, add some, update configuration -->
<!-- hover with the mouse to have the tooltip show up -->
<!-- usual iSEE magic: export code for the plots -->

Note how it is easy to switch to a different contrast in any of the panels. 

```{r}
app <- iSEE(sce_macrophage, initial = list(
  iSEEde::DETable(
    ContrastName = "IFNgTRUE.SL1344TRUE.DESeq2",
    HiddenColumns = c("baseMean", "lfcSE", "stat")
  ),
  iSEEde::VolcanoPlot(ContrastName = "IFNgTRUE.SL1344TRUE.DESeq2"),
  iSEEde::MAPlot(ContrastName = "IFNgTRUE.SL1344TRUE.DESeq2"),
  PathwaysTable(
    ResultName = "IFNgTRUE.SL1344TRUE.limma.fgsea",
    Selected = "GO:0046324"
  ),
  ComplexHeatmapPlot(
    RowSelectionSource = "PathwaysTable1",
    CustomRows = FALSE, ColumnData = "condition_name",
    ClusterRows = TRUE, Assay = "vst"
  ),
  FgseaEnrichmentPlot(
    ResultName = "IFNgTRUE.SL1344TRUE.limma.fgsea",
    PathwayId = "GO:0046324"
  )
))
```

```{r, echo=FALSE}
SCREENSHOT("images/isee_de_setup2.png", delay = 30)
```

<!-- Possible actions: -->
<!-- select a pathway from PAT1 -->
<!-- transform vst data in heatmap, center -->
<!-- receive row selection in volcano and MA plot -->
<!-- change coloring to "row selection" -->
<!-- select alternative contrast and see all dependencies updated -->
<!-- usual iSEE magic: export code for the plots -->
<!-- usual iSEE magic: export code for the panel configuration -->


# iSEEfier

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 `r Biocpkg("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 section, we will illustrate a simple example of how to use `r Biocpkg("iSEEfier")`. We will use the same pbmc3k data we worked with during this workshop.

We start by loading the data:

```{r}
library("iSEEfier")

# 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)
```

`?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

We will take another dataset for this, from a recent work of Bartneck and colleagues ([@Bartneck2023]).

You can find the dataset in the `sce_merged_allsets.RDS` object - let's see together how we can access that --> https://seafile.rlp.net/d/c7f1335a6248427d97da/.

Once the data is available locally, we load it in the R session and simply start iSEE on it.

```{r eval=FALSE}
library("iSEE")
sce_bartneck <- readRDS("path/to/sce_merged_allsets.RDS")
iSEE(sce_bartneck)
```

For more about this work, please refer to the [original publication](https://www.frontiersin.org/articles/10.3389/fimmu.2023.1267866/full).

# iSEEhub & iSEEindex

## iSEEhub: `iSEE`ing the ExperimentHub datasets

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}
library("iSEE")
library("iSEEhub")

ehub <- ExperimentHub()
app <- iSEEhub(ehub)
```

```{r, echo=FALSE}
SCREENSHOT("images/iseehub.png", delay = 20)
```

<!-- Possible actions: -->
<!-- select a dataset from DuoClustering -->
<!-- start iSEE on that -->

## iSEEindex: one instance of `iSEE` to explore them all

`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.
To see how to configure such an app, we will create a small example:

```{r}
library("iSEE")
library("iSEEindex")

bfc <- BiocFileCache(cache = tempdir())

dataset_fun <- function() {
  x <- yaml::read_yaml(system.file(package = "iSEEindex", "example.yaml"))
  x$datasets
}
initial_fun <- function() {
  x <- yaml::read_yaml(system.file(package = "iSEEindex", "example.yaml"))
  x$initial
}
app <- iSEEindex(bfc, dataset_fun, initial_fun)
```

```{r, echo=FALSE}
SCREENSHOT("images/iseeindex.png", delay = 20)
```


A more elaborate example (referring to the work in [@Rigby2023]) 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). 

<!-- Possible actions: -->
<!-- navigate to github repo -->
<!-- explore the app.R file -->
<!-- check the initial state files -->
<!-- have a look at the configuration yaml -->

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?


# Tours: help and storytelling

Tours can be an essential tool to satisfy two needs:

* Helping users to navigate the UI
* Telling a story on an existing configuration

A simple example can be demonstrated with this configuration:

```{r}
sce_location <- system.file("datasets", "sce_pbmc3k.RDS", package = "iUSEiSEE")
sce_location
sce <- readRDS(sce_location)

initial_for_tour <- list(
  ReducedDimensionPlot(PanelWidth = 3L), 
  RowDataTable(PanelWidth = 3L),
  FeatureAssayPlot(PanelWidth = 3L),
  ComplexHeatmapPlot(PanelWidth = 3L)
)
```

This next chunk defines the **steps** of the tour, specified by an anchoring point (`element`) and the content of that step (`intro`).

```{r}
tour <- data.frame(
  element = c(
    "#Welcome",
    "#ReducedDimensionPlot1",
    "#RowDataTable1",
    "#ComplexHeatmapPlot1",
    "#FeatureAssayPlot1",
    "#ReducedDimensionPlot1",
    "#Conclusion"),
  intro = c(
    "Welcome to this tour!",
    "This is the a reduced dimension plot",
    "and this is a table",
    "Why not a heatmap?",
    "... and now we look at one individual feature.",
    "Back to the a reduced dimension plot...",
    "Thank you for taking this tour!"),
  stringsAsFactors = FALSE
)

app <- iSEE(sce, initial = initial_for_tour, tour = tour)
```

```{r, echo=FALSE}
SCREENSHOT("images/isee_simpletour.png", delay = 20)
```

# Session info {-}

```{r}
sessionInfo()
```

# References {-}