---
title: "SIB Spatial Omics Data Analysis Course 2025 (Part 2): Lattice Data Analysis Vignette"
author: "Samuel Gunz, Martin Emons, Mark D. Robinson"
format:
    html:
      toc: true
      self-contained: true
editor: visual
editor_options: 
  chunk_output_type: console
bibliography: misc/PASTA.bib
---

# Introduction

In contrast to point pattern based methods, we can view the location of cells or spots as a fixed lattice and measure the corresponding marker expression at each location. HTS-based spatial transcriptomic technologies often produce data on a regular lattice (i.e., approximately evenly spaced spots or beads of uniform size and shape), whereas imaging-based technologies yield irregular lattice structures (i.e., with variable cell sizes and shapes, and non-uniform spacing).

For this representation of the cells, we will rely on the `r BiocStyle::Biocpkg('SpatialFeatureExperiment')` package (see below for more details). For preprocessing of the dataset, we refer the reader to the vignette of the `r BiocStyle::Biocpkg('Voyager')` package [@mosesVoyagerExploratorySinglecell2023]. The `Voyager` package also provides wrapper functions around the package `r BiocStyle::CRANpkg('spdep')` [@pebesmaSpatialDataScience2023] that work directly on the `SpatialFeatureExperiment` object. The package `spdep` is designed for the analysis of spatial data with lattice structure.

## Dependencies

```{r, warning=FALSE, message=FALSE}
suppressPackageStartupMessages({
  library(dplyr)
  library(ggplot2)
  library(patchwork)
  library(Voyager)
  library(SpatialFeatureExperiment)
  library(SFEData)
  library(spdep)
  library(sf)
  library(stringr)
  library(tidyr)
  library(magrittr)
  library(scater)
})

theme_set(theme_light())
```

## Setup and Preprocessing

We will load a dataset gereated by [@mckellarLargescaleIntegrationSinglecell2021] using the Visium technology [@stahlVisualizationAnalysisGene2016]. The data shows a sample taken from the tibialis anterior muscle of a mouse.

```{r}
# Load the dataset
sfe <- SFEData::McKellarMuscleData(dataset = "full")
# Take spots that are covered with tissue
sfe_tissue <- sfe[, colData(sfe)$in_tissue]
# Filter out genes with no counts
sfe_tissue <- sfe_tissue[rowSums(counts(sfe_tissue)) > 0, ]
# Convert counts log-transformed normalized expression values
sfe_tissue <- scater::logNormCounts(sfe_tissue)
```

`SpatialFeatureExperiment` [@mosesVoyagerExploratorySinglecell2023] objects are an extension of the `r BiocStyle::Biocpkg('SpatialExperiment')` object [@righelliSpatialExperimentInfrastructureSpatiallyresolved2022]. In particular, the objects contain geometric annotations that are encoded as simple features of the `r BiocStyle::CRANpkg('sf')` library [@pebesmaSpatialDataScience2023].

```{r}
sfe_tissue
```

For example, the spots of the Visium dataset are stored as a simple feature collection.

```{r}
colGeometry(sfe_tissue, "spotPoly")
```

# Lattice Data

## Definition

Lattice data refers to spatial data collected at locations arranged in a regular or irregular grid (lattice). Each location has a defined spatial unit, and the sampling locations are fixed rather than random. This approach contrasts with point pattern analysis, where we assume that the locations were generated by a stochastic process [@zuurAnalysingEcologicalData2007; @pebesmaSpatialDataScience2023].

```{r}
#| include: false
#| eval: false
plotSpatialFeature(sfe_tissue,
  "nCounts",
  colGeometryName = "spotPoly"
)
```

As can be seen below, the Visium dataset is a regular (hexagonal) lattice. The color shows the number of counts detected in each Visium spot. In contrast, the outlines of individual cells after segmentation (e.g., from a higher resolution spatial omics assay, or an H&E stain) could be thought of and represented as an irregular lattice. As this dataset also contains (manual) segmentations of myofibers (muscle cells stored as `myofiber_simplified`), we will illustrate calculations based on irregular lattice on the myofiber segmentations.

```{r}
# A plot using the plotSpatialFeature from Voyager
p <- plotSpatialFeature(sfe_tissue,
  "nCounts",
  annotGeometryName = "myofiber_simplified"
)

# This extracts the segmented cells
cells <- annotGeometry(sfe_tissue, "myofiber_simplified") |>
  st_geometry()

# We can also use ggplot and geom_sf to plot sf objects
q <- ggplot() +
  geom_sf(data = cells, fill = NA) +
  theme_void()

# Using `patchwork` to combine the plots
p | q
```

## Spatial weight matrix

In lattice data analysis, a key concept is the *spatial weight matrix*, which models the spatial relationships between units in the lattice (i.e., spots or cells). Various methods exist to construct this matrix, such as contiguity-based (direct neighbors), graph-based, or distance-based methods. [@getisSpatialWeightsMatrices2009; @zuurAnalysingEcologicalData2007; @pebesmaSpatialDataScience2023]. The documentation of the package `spdep` gives an [overview of the different methods](https://r-spatial.github.io/spdep/articles/nb.html).

For Visium, the most straightforward way is to take the direct neighbours of each spot. This is done using the function `findVisiumGraph`.

```{r}
colGraph(sfe_tissue, "visium") <- findVisiumGraph(sfe_tissue)
```

```{r}
plotColGraph(sfe_tissue,
  colGraphName = "visium",
  colGeometryName = "spotPoly"
) + theme_void()
```

In an irregular lattice, the task of finding a spatial weight matrix is more complex, as different options exist. One option is to base the neighbourhood graph on neighbours that are in direct contact with each other (contiguous), as implemented in the `poly2nb` method.

```{r, warning=FALSE, message=FALSE}
annotGraph(sfe_tissue, "myofiber_poly2nb") <-
  findSpatialNeighbors(sfe_tissue,
    type = "myofiber_simplified",
    MARGIN = 3,
    method = "poly2nb", # wraps spdep function with same name
    zero.policy = TRUE
  )
```

```{r}
p1 <- plotAnnotGraph(sfe_tissue,
  annotGraphName = "myofiber_poly2nb",
  annotGeometryName = "myofiber_simplified"
) + theme_void()
```

Alternatively, we could take the five nearest neighbours of each cell.

```{r}
annotGraph(sfe_tissue, "knn5") <-
  findSpatialNeighbors(sfe_tissue,
    type = "myofiber_simplified",
    MARGIN = 3, # to use the annotation geometry
    method = "knearneigh", # wraps the spdep function with the same name
    k = 5,
    zero.policy = TRUE
  )
```

```{r}
p2 <- plotAnnotGraph(sfe_tissue,
  annotGraphName = "knn5",
  annotGeometryName = "myofiber_simplified"
) + theme_void()
```

As we can see below, the graphs look quite distinct. On the left side, in the contiguous neigbhbour graph (neighbours in direct contact) we can notice the formation of patches, while in the knn graph isolated patches are interconnected.

```{r}
p1 + p2
```

<!-- In the case of Visium data, we don't have cell level gene expression information and therefore continue with the analysis using the spatial analysis of the regularly spaced spots. -->

# Spatial autocorrelation

Spatial autocorrelation measures the association between spatial units while recognizing that the spatial units are not independent measurements. These measures can be global (summarizing the entire field) or local (providing statistics for individual locations) [@pebesmaSpatialDataScience2023].

## Global Measures

Global methods give us an overview over the entire field-of-view and summarize the spatial autocorrelation metric to a single value. The metrics are a function of the weight matrix and the variables of interest. The variables of interest can be gene expression, intensity of a marker or the area of the cell. The global measures can be seen as a weighted average of the local metric, as explained below.

In general, a global spatial autocorrelation measure has the form of a double sum over all locations $i,j$

$$\sum_i \sum_j f(x_i,x_j) w_{ij}$$

where $f(x_i,x_j)$ is the measure of association between features of interest and $w_{ij}$ scales the relationship by a spatial weight as defined in the weight matrix $W$ [@zuurAnalysingEcologicalData2007; @pebesmaSpatialDataScience2023].

### Moran's I

Moran's I is the most prominent measure of spatial autocorrelation. The values are bounded by $-1$ and $1$. The expected value is close to $0$ for large $n$, the exact value is given by $\mathbb{E}(I) = -1/(n-1)$. A value higher than the expected value indicates spatial auto-correlation. Negative values indicate negative auto-correlation. Spatial auto-correlation means that similar values tend to be found together in the tissue. In fact, Moran's I can be interpreted as the Pearson correlation between the value at location $i$ and the averages value of the neigbours of $i$, (neighbours as defined in the weight matrix $W$) [@moranNotesContinuousStochastic1950].

In the first example, we will calculate Moran's I for the number of counts and genes measured in the Visium dataset. First we have a look at the distribution by eye.

```{r}
plotSpatialFeature(sfe_tissue,
  features = c("nCounts", "nGenes"),
  colGeometryName = "spotPoly",
  swap_rownames = "symbol"
)
```

Based on these values we can calculate Moran's I

```{r}
calculateUnivariate(t(colData(sfe_tissue)[, c("nCounts", "nGenes")]),
  type = "moran",
  listw = colGraph(sfe_tissue, "visium")
)
```

We can further use permutation testing to get a significance of our estimates.

```{r}
sfe_tissue <- colDataUnivariate(sfe_tissue,
  features = c("nCounts", "nGenes"),
  colGraphName = "visium", nsim = 1000,
  type = "moran.mc"
)
plotMoranMC(sfe_tissue, c("nCounts", "nGenes"),
  linewidth = 2
)
```

Here we can see the Moran's I values for the number of counts and genes that were identified in the Visium dataset and a permutation-based null distribution. As we can see, the Moran's I values both indicate positive spatial autocorrelation and are highly significant. This means that regions with similar count and number of measured gene values tend to cluster together. This is an interesting finding and was observed in other spatial transcriptomic datasets, see [@bhuvaLibrarySizeConfounds2024].

## Local Measures for Univariate Data

Often a global measure is not enough. One number determining, e.g., the spatial autocorrelation over an entire tissue slice might not be reflective of tissue heterogeneity. Therefore, local indicators of spatial associations have been developed [@pebesmaSpatialDataScience2023].

### Local Moran's I

Local Moran's I provides a measure of spatial autocorrelation at each location, highlighting local clusters of similarity or dissimilarity [@anselinLocalIndicatorsSpatial1995]. It is defined as:

$$I_i = \frac{x_i - \bar{x}}{\sum_{k=1}^n(x_k-\bar{x})^2/(n-1)} \sum_{j=1}^n w_{ij}(x_j - \bar{x})$$

where the index $i$ refers to the location for which the measure is calculated. The interpretation is analogous to the global Moran's I where a value of $I_i$ higher than $\mathbb{E}(I) = -1/(n-1)$ indicates spatial auto-correlation; smaller values indicate negative auto-correlation. It is important to note that, as for the global counterpart, the value of local Moran's I could be a result from both the high or low end of the values. Here we will calculate the local Moran's I value for the measurement of muscle fiber marker gene *Myh2*:

```{r}
sfe_tissue <- runUnivariate(sfe_tissue,
  type = "localmoran",
  features = "Myh2",
  colGraphName = "visium",
  swap_rownames = "symbol"
)

# plot the expression values
pExp <- plotSpatialFeature(sfe_tissue,
  features = c("Myh2"), colGeometryName = "spotPoly",
  swap_rownames = "symbol"
)

# plot the local Moran's I values
pLi <- plotLocalResult(sfe_tissue, "localmoran",
  features = c("Myh2"),
  colGeometryName = "spotPoly", swap_rownames = "symbol",
  divergent = TRUE, diverge_center = 0
) + labs(fill = "li(Myh2)") # specify legend


# plot the local Moran's I p-values
pPval <- plotLocalResult(sfe_tissue, "localmoran",
  features = c("Myh2"), "-log10p_adj",
  colGeometryName = "spotPoly", swap_rownames = "symbol",
  divergent = TRUE, diverge_center = -log10(0.05)
) + labs(fill = "-log10(p.adj)") # specify legend

# please note that the
pExp + pLi + pPval
```

In the local version of Moran's I, the interpretation is the same as the global version. When interpreting local autocorrelation measures, it is important to consider both the effect size estimates and the significance level. Since the significance level is calculated for each spot separately, it is recommended to adjust for multiple testing. By default, `runUnivariate` uses the Benjamini & Hochberg correction. The local Moran's I statistics reveal locations in the tissue that have similar values to their neighbours (c.f., the lower part of the tissue).

::: {.callout-tip title="EXERCISE"}
Try to recalculate the local Moran's I with gene *Myh1*. What do you notice?
:::

```{r}
#| eval: false #remove this line when you want to execute the chunk

sfe_tissue <- runUnivariate(...)
```

### Advanced -- Bivariate Moran's I

There exists a bivariate version of Moran's I as well. The package `spatialDM` [@liSpatialDMRapidIdentification2023] uses an adapted version of bivariate Moran's I to identify ligand-receptor pairs.

For two continous observations, the global bivariate Moran's I is defined as [@wartenbergMultivariateSpatialCorrelation1985; @bivandPackagesAnalyzingSpatial2022]

$$I_B = \frac{\Sigma_i(\Sigma_j{w_{ij}b_j\times a_i})}{\Sigma_i{b_i^2}}$$

where $a_i$ and $b_i$ are the two variables of interest and $w_{ij}$ is the value of the spatial weights matrix for positions $i$ and $j$. It is a measure of the correlation of the variables $a$ with the the average of the neighboring values for variable $b$ (also called the spatial lag of $b$).

There exists a local version that we will explore here. Note that the results are not symmetric, but very similar to each other.

```{r}
sfe_tissue <- runBivariate(sfe_tissue, 
                           "localmoran_bv", # wraps the method from spdep
                           c("Myh1", "Myh2"),
                           swap_rownames = "symbol", nsim = 1000)

# this command gives all results of localmoran_bv
localResultFeatures(sfe_tissue, "localmoran_bv")

plotLocalResult(sfe_tissue, "localmoran_bv", 
                c("Myh1__Myh2", "Myh2__Myh1"),
                colGeometryName = "spotPoly",
                divergent = TRUE, diverge_center = 0)
```

Compare the results to the local Moran's I plots for genes *Myh1* and *Myh2*. What do you notice?

Please note that the result might overestimate the spatial autocorrelation of the variables due to the inherent (non-spatial) correlation of $x$ and $y$ [@bivandPackagesAnalyzingSpatial2022].

## Impact of neighbourhood on autocorrelation measures

Let's compare the impact of different spatial weight matrices on local autocorrelation analysis. In this Visium dataset we do not have gene expression information for each cell because of the resolution of the spots. We will instead calculate the autocorrelation measures on the area of the segmented cells. This could be helpful when looking at local cell densities in a tissue.

First, we base the spatial weight matrix on contiguous neighbours.

```{r}
sfe_tissue <- annotGeometryUnivariate(sfe_tissue, 
  "localmoran", "area",
  annotGeometryName = "myofiber_simplified",
  annotGraphName = "myofiber_poly2nb",
  include_self = FALSE, zero.policy = TRUE,
  name = "myofiber_poly2nb"
)

pPoly <- plotLocalResult(sfe_tissue, "myofiber_poly2nb", "area",
  annotGeometryName = "myofiber_simplified",
  annotGraphName = "myofiber_poly2nb",
  divergent = TRUE, diverge_center = 0
) + labs(title = "Local Moran's I (li)\nContiguous Neighbours", 
         fill = "li(area)")
```

As an alternative, we also base the spatial weight matrix on the 5 nearest neighbours.

```{r}
sfe_tissue <- annotGeometryUnivariate(sfe_tissue, "localmoran", "area",
  annotGeometryName = "myofiber_simplified",
  annotGraphName = "knn5",
  include_self = FALSE, zero.policy = TRUE,
  name = "knn5"
)

pKnn5 <- plotLocalResult(sfe_tissue, "knn5", "area",
  annotGeometryName = "myofiber_simplified",
  annotGraphName = "knn5",
  divergent = TRUE, diverge_center = 0
) + labs(title = "Local Moran's I (li)\n5 Nearest Neighbours (knn5)", 
         fill = "li(area)")
```

```{r}
pPoly + pKnn5
```

::: {.callout-tip title="EXERCISE"}
What happens if we set the nearest neighbourhood graph to 10 nearest neighbours? What do you notice?
:::

```{r}
#| eval: false #remove this line when you want to execute the chunck

annotGraph(sfe_tissue, "knn10") <-
  findSpatialNeighbors(...)

plotLocalResult(...)
```

# Summary and Considerations

-   Lattice data refers to spatial data collected at fixed locations arranged in regular or irregular grids, contrasting with stochastic point pattern analysis.
-   Regular lattices have uniform, evenly spaced spots, while irregular lattices have variable sizes and shapes with non-uniform spacing.
-   The spatial weight matrix models spatial relationships between lattice units. Different methods exist to define the spatial weight matrix.
-   Global spatial autocorrelation measures, like Moran's I, summarize spatial correlation over the entire field, while local measures identify local clusters of similarity or dissimilarity.

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

This tutorial is partially based on the following `Voyager` [vignette](https://pachterlab.github.io/voyager/articles/vig2_visium.html).
