Contents

1 Installation

if (!require("BiocManager")) {
  install.packages("BiocManager")
}
BiocManager::install("lisaClust")
# load required packages
library(lisaClust)
library(spicyR)
library(ggplot2)
library(SingleCellExperiment)
library(SpatialDatasets)

2 Overview

Clustering local indicators of spatial association (LISA) functions is a methodology for identifying consistent spatial organisation of multiple cell-types in an unsupervised way. This can be used to enable the characterization of interactions between multiple cell-types simultaneously and can complement traditional pairwise analysis. In our implementation our LISA curves are a localised summary of an L-function from a Poisson point process model. Our framework lisaClust can be used to provide a high-level summary of cell-type colocalization in high-parameter spatial cytometry data, facilitating the identification of distinct tissue compartments or identification of complex cellular microenvironments.

3 Quick start

3.1 Generate toy data

To illustrate our lisaClust framework, we consider a very simple toy example where two cell-types are completely separated spatially. We simulate data for two different images.

set.seed(51773)
x <- round(c(
  runif(200), runif(200) + 1, runif(200) + 2, runif(200) + 3,
  runif(200) + 3, runif(200) + 2, runif(200) + 1, runif(200)
), 4) * 100
y <- round(c(
  runif(200), runif(200) + 1, runif(200) + 2, runif(200) + 3,
  runif(200), runif(200) + 1, runif(200) + 2, runif(200) + 3
), 4) * 100
cellType <- factor(paste("c", rep(rep(c(1:2), rep(200, 2)), 4), sep = ""))
imageID <- rep(c("s1", "s2"), c(800, 800))

cells <- data.frame(x, y, cellType, imageID)

ggplot(cells, aes(x, y, colour = cellType)) +
  geom_point() +
  facet_wrap(~imageID) +
  theme_minimal()

3.2 Create Single Cell Experiment object

First we store our data in a SingleCellExperiment object.

SCE <- SingleCellExperiment(colData = cells)
SCE
## class: SingleCellExperiment 
## dim: 0 1600 
## metadata(0):
## assays(0):
## rownames: NULL
## rowData names(0):
## colnames: NULL
## colData names(4): x y cellType imageID
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):

3.3 Running lisaCLust

We can then use the convenience function lisaClust to simultaneously calculate local indicators of spatial association (LISA) functions and perform k-means clustering. The number of clusters can be specified with the k = parameter. In the example below, we’ve chosen k = 2, resulting in a total of 2 clusters. The cell type column can be specified using the cellType = argument. By default, lisaClust uses the column named cellType.

The clusters identified by lisaClust are stored in colData of the SingleCellExperiment object as a new column called regions.

SCE <- lisaClust(SCE, k = 2)
colData(SCE) |> head()
## DataFrame with 6 rows and 5 columns
##           x         y cellType     imageID      region
##   <numeric> <numeric> <factor> <character> <character>
## 1     36.72     38.58       c1          s1    region_2
## 2     61.38     41.29       c1          s1    region_2
## 3     33.59     80.98       c1          s1    region_2
## 4     50.17     64.91       c1          s1    region_2
## 5     82.93     35.60       c1          s1    region_2
## 6     83.13      2.69       c1          s1    region_2

3.4 Plot identified regions

lisaClust also provides the convenient hatchingPlot function to visualise the different regions that have been demarcated by the clustering. hatchingPlot outputs a ggplot object where the regions are marked by different hatching patterns. In a real biological dataset, this allows us to plot both regions and cell-types on the same visualization.

In the example below, we can visualise our stimulated data where our 2 cell types have been separated neatly into 2 distinct regions based on which cell type each region is dominated by. region_2 is dominated by the red cell type c1, and region_1 is dominated by the blue cell type c2.

hatchingPlot(SCE, useImages = c("s1", "s2"))