---
title: "Overview of Voyager"
author: "Lambda Moses, Lior Pachter"
date: "`r format(Sys.Date(), '%b %d, %Y')`"
output:
    BiocStyle::html_document:
        toc: true
        number_sections: true
        toc_depth: 3
        toc_float:
            collapsed: true
vignette: >
  %\VignetteIndexEntry{Functionality overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>", fig.align = "center"
)
```

As including a more detailed vignette inside the package makes the package exceed the tarball size, more detailed vignettes are hosted on [an external website](https://pachterlab.github.io/voyager/index.html). This is a simplified vignette.

# Installation
This package can be installed from Bioconductor:
```{r, eval=FALSE}
if (!requireNamespace("BiocManager")) install.packages("BiocManager")
BiocManager::install("Voyager")
# Devel version
# install.packages("remotes")
remotes::install_github("pachterlab/Voyager")
```

# Introduction
In non-spatial scRNA-seq, the [`SingleCellExperiment`](https://bioconductor.org/packages/release/bioc/html/SingleCellExperiment.html) (SCE) package implements a data structure and other packages such as [`scater`](https://bioconductor.org/packages/release/bioc/html/scater.html) implement methods for quality control (QC), basic exploratory data analysis (EDA), and plotting functions, using SCE to organize the data and results. `Voyager` to [`SpatialFeatureExperiment`](https://bioconductor.org/packages/release/bioc/html/SpatialFeatureExperiment.html) (SFE) aims to be analogous `scater` to SFE, implementing basic exploratory _spatial_ data analysis (ESDA) and plotting. SFE inherits from SCE and [`SpatialExperiment`](https://bioconductor.org/packages/release/bioc/html/SpatialExperiment.html) (SPE), so all methods written for SCE and SPE can be used for SFE as well.

In this first version, ESDA is based on the classic geospatial package [`spdep`](https://r-spatial.github.io/spdep/index.html), but future versions will incorporate methods from [`GWmodel`](https://cran.r-project.org/web/packages/GWmodel/index.html), [`adespatial`](https://cran.r-project.org/web/packages/adespatial/index.html), and etc. 

These are the main functionalities of the `Voyager` at present:

* Univariate global spatial statistics, such as Moran's I, Geary's C, permutation testing of I and C, correlograms, and global G.
* Univariate local spatial statistics, such as local Moran's I, local Geary's C, Getis-Ord Gi\*, Moran scatter plot, and local spatial heteroscedasticity (LOSH).
* Plotting gene expression and `colData` along with annotation geometries, with colorblind friendly default palettes. The actual geometries are plotted, not just centroids as in `Seurat`.
* Plotting permutation testing results and correlograms, multiple genes in the same plot, can color by gene, sample, or any other attribute.
* Clustering correlograms and Moran's scatter plots
* Plotting local spatial statistics in space
* Plotting dimension reduction in space
* Plotting spatial neighborhood graphs

Future versions will add bivariate and multivariate spatial statistics and user friendly wrappers of some successful spatial transcriptomics data analysis packages for spatially variable genes, cell type deconvolution, and spatial regions on CRAN, Bioconductor, pip, and conda, to provide a uniform syntax and avoid object conversion, as is done in `Seurat` for some non-spatial scRNA-seq methods.

# Dataset
Here we use a mouse skeletal muscle Visium dataset from [Large-scale integration of single-cell transcriptomic data captures transitional progenitor states in mouse skeletal muscle regeneration](https://www.nature.com/articles/s42003-021-02810-x). It's in the `SFEData` package, as an SFE object, which contains Visium spot polygons, myofiber and nuclei segmentations, and myofiber and nuclei morphological metrics.
```{r}
library(SFEData)
library(SpatialFeatureExperiment)
library(Voyager)
library(scater)
```

```{r}
sfe <- McKellarMuscleData()
# Only use spots in tissue here
sfe <- sfe[,colData(sfe)$in_tissue]
sfe <- logNormCounts(sfe)
sfe
```

# Univariate spatial statistics
A spatial neighborhood graph is required for all `spdep` analyses.
```{r}
colGraph(sfe, "visium") <- findVisiumGraph(sfe)
```

All of the numerous univariate methods can be used with `runUnivariate()`, which stores global results in `rowData(sfe)` and local results in `localResults(sfe)`. Here we compute Moran's I for one gene. While Ensembl IDs are used internally, the user can specify more human readable gene symbols. A warning will be given if the gene symbol matches multiple Ensembl IDs.
```{r}
features_use <- c("Myh1", "Myh2")
```

```{r}
sfe <- runUnivariate(sfe, type = "moran", features = features_use, 
                     colGraphName = "visium")
# Look at the results
rowData(sfe)[rowData(sfe)$symbol %in% features_use,]
```

Since Moran's I is very commonly used, one can call `runMoransI` rather than `runUnivariate`.

Compute a local spatial statistic, Getis-Ord Gi\*, which is commonly used to detect hotspots and coldspots. The `include_self` argument is only for Getis-Ord Gi\*; when set to `TRUE` Gi\* is computed as the spatial graph includes self-directing edges, and otherwise Gi is computed.
```{r}
sfe <- runUnivariate(sfe, type = "localG", features = features_use,
                     colGraphName = "visium", include_self = TRUE)
# Look at the results
DataFrame(localResults(sfe, name = "localG"))
```

Spatial statistics can also be computed for numeric columns of `colData(sfe)`, with `colDataUnivariate()`, and for numeric attributes of the geometries with `colGeometryUnivariate()` and `annotGeometryUnivariate()`, all with very similar arguments.

# Plotting
Plot gene expression and `colData(sfe)` together with annotation geometry. Here `nCounts` is the total UMI counts per spot, which is in `colData`.
```{r}
plotSpatialFeature(sfe, c("nCounts", "Myh1"), colGeometryName = "spotPoly", 
                   annotGeometryName = "myofiber_simplified", 
                   aes_use = "color", size = 0.4, fill = NA,
                   annot_aes = list(fill = "area"))
```

Plot local results
```{r}
plotLocalResult(sfe, "localG", features = features_use, 
                colGeometryName = "spotPoly", divergent = TRUE, 
                diverge_center = 0)
```

# Session info
```{r}
sessionInfo()
```