---
title: "Create Multi-dimensional Plot of Spatially-resolved Transcriptomics Data"
author: 
  - name: Boyi Guo
    affiliation: &id1 "Johns Hopkins Bloomberg School of Public Health, Baltimore, MD, USA"
  - name: Stephanie C. Hicks
    affiliation: *id1
package: escheR
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Create Multi-dimensional Plot of Spatially-resolved Transcriptomics Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    message = FALSE,
    comment = "#>",
    # fig.width = 8,
    # fig.height = 8,
    fig.small = TRUE
)
```

# Introduction

The goal of escheR is to create an unified multi-dimensional spatial visualizations for spatially-resolved transcriptomics data following Gestalt principles.

Our preprint describing the innovative visualization is available from [bioRxiv](https://www.biorxiv.org/content/10.1101/2023.03.18.533302).


## Installation

You can install the latest release version of `escheR` from Bioconductor. with using the following code will install version of the `nnSVG` package from Bioconductor. Additional details are shown on the [Bioconductor](https://bioconductor.org/packages/escheR) page.

```{r install_bioc, eval=FALSE}
if (!require("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}
BiocManager::install("escheR")
```

The latest development version can also be installed from the `devel` version of Bioconductor or from [GitHub](https://github.com/boyiguo1/escheR) following

```{r install_github, eval = FALSE}
if (!require("devtools")) install.packages("devtools")
devtools::install_github("boyiguo1/escheR")
```

# Input data format

In the examples below, we assume the input data are provided as a [`SpatialExperiment`](https://bioconductor.org/packages/release/bioc/html/SpatialExperiment.html) Bioconductor object. For people whose data are stored as a [`Seurat`](https://satijalab.org/seurat/articles/spatial_vignette.html) object, we advise to convert to a `SpatialExperiment` object before applying the workflow below.  

# Tutorial


## Load Packages

To run the demonstration, there are two necessary packages to load, `escheR` and `spatialLIBD`. [`spatialLIBD`](http://spatial.libd.org/spatialLIBD/) contains a pre-processed 10x Visium dataset.

To note, `escheR`  will automatically load `ggplot2` package. Hence, explicitly loading `ggplot2` is not required. 
```{r setup}
library(escheR)
library(STexampleData)
library(spatialLIBD)
```


## Preparing example data

In this step, we will find one 10xVisium sample from [`STexampleData`](https://bioconductor.org/packages/release/data/experiment/html/STexampleData.html) package, indexed by brain number of "151673". For more information, please see the vignettes of [`STexampleData`](https://bioconductor.org/packages/release/data/experiment/vignettes/STexampleData/inst/doc/STexampleData_overview.html).

```{r data.import}
spe <- Visium_humanDLPFC()

# Subset in-tissue spots
spe <- spe[, spe$in_tissue == 1]
```

Here is a summary of the `SpatialExperiment` object called `spe`.
```{r spe_summary}
spe
```
  
## Setting up for escheR plot
Similar to `ggplot2::ggplot()`, we first use the function `make_escheR()` to create an empty plot. The input of `make_escheR()` is a [`SpatialExperiment`](https://bioconductor.org/packages/release/bioc/html/SpatialExperiment.html) object. The output of the function is a `ggplot` object with no layer in it. 
```{r create_plot}
p <- make_escheR(spe)
```

## Adding layers

Unlike `ggplot2`, we use piping `|>` instead of `+` to apply layers the figure. Mainly, we have three functions `add_fill`, `add_ground`, `add_symbol`. The inputs of these `add_*` functions include the plots created using `make_scheR()` and the variable name for the layer. Currently, the variable name should be in the the column data of the `spe` object, i.e. `colData(spe)`.

Here we first apply the `add_fill` to add the spots color-coded by the total number of cells all spots(`sum_umi`).  

```{r creat_fill}
(p1 <- p |>
    add_fill(var = "cell_count"))

p1 +
    scale_fill_viridis_c()
```

It is okay to use any combination of the `add_*` functions. For example, we want to show the spatial domains of the samples as the ground of the figure and use symbols to denote if each spot is within the outline of the tissue slice. In this example, all plotted spots are in the outlines of the tissue slice and hence marked with dots.
```{r create_ground}
(p2 <- p |>
    add_ground(var = "ground_truth")) # round layer
```


```{r add_symbol}
p2 |>
    add_symbol(var = "ground_truth", size = 0.2) # Symbol layer
```

It is okay to change the ordering of these `add_*` functions. However, we advise to always have the `add_fill` as the first step to achieve the best visual effect due to the laying mechanism. 

## Adjusting aesthetics

To change the aesthetics of each layer, one can simply use the `scale_*` from `ggplot2` to optimize the final visual presentation. For example, to optimize `add_fill`, one can use `scale_fill_*`; to optimize `add_ground`, one can use `scale_color_*`; to optimize `add_sumbol`, one use `scale_shape_*`. Here, we demonstrate how to change the color for the ground layer ( `add_ground`) using `scale_color_manual`.

```{r customize}
# Currated color pallette from spatialLIBD
spatialLIBD::libd_layer_colors

p2 +
    scale_color_manual(
        name = "", # No legend name
        values = spatialLIBD::libd_layer_colors
    ) +
    labs(title = "Example Title")
```


# Session information

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