---
title: "Clustering of Local Indicators of Spatial Assocation (LISA) curves"
date: "`r BiocStyle::doc_date()`"
author:
- name: Nicolas Canete
  affiliation:  
  - &WIMR Westmead Institute for Medical Research, University of Sydney, Australia
  email: nicolas.canete@sydney.edu.au
- name: Ellis Patrick
  affiliation:
  - &WIMR Westmead Institute for Medical Research, University of Sydney, Australia
  - School of Mathematics and Statistics, University of Sydney, Australia
  email: ellis.patrick@sydney.edu.au
package: "`r BiocStyle::pkg_ver('spicyR')`"
vignette: >
  %\VignetteIndexEntry{"lisaClust"}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output: 
  BiocStyle::html_document
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, message = FALSE, warning = FALSE
)
library(BiocStyle)
```

# Installation

```{r, eval = FALSE}
if (!require("BiocManager"))
    install.packages("BiocManager")
BiocManager::install("spicyR")
```


```{r message=FALSE, warning=FALSE}
# load required packages
library(spicyR)
library(ggplot2)

```
 
 

# 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.



# Quick start

## Generate toy data

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

```{r eval=T}
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)
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)
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)


```

## Create SegmentedCellExperiment object

First we store our datas into a `SegmentedCells` object. 

```{r}

cellExp <- SegmentedCells(cells, cellTypeString = 'cellType')


```


## Generate LISA curves

We can then calculate local indicators of spatial association (LISA) functions 
using the `lisa` function. In our implementation, our LISA curves are a 
localised summary of an L-function from a Poisson point process model. By 
default, `lisa` will calculate curves for 20 'sensible' radii for each 
cell-type. 

```{r}

lisaCurves <- lisa(cellExp)

```

## Perform some clustering

The LISA curves can then be used to cluster the cells. Here we use k-means 
clustering, other clustering methods like SOM could be used. We can store these 
cell clusters or cell "regions" in our `SegmentedCells` object using the 
`region() <-` function.

```{r}

kM <- kmeans(lisaCurves,2)
region(cellExp) <- paste('region',kM$cluster,sep = '_')
```


## Plot identified regions

The `hatchingPlot` function can be used to construct a `ggplot` object where the 
regions are marked by different hatching patterns. This allows us to plot both 
regions and cell-types on the same visualization.


```{r}
hatchingPlot(cellExp, imageID = c('s1','s2'))
```




## Alternative hatching plot

We could also create this plot using `geom_hatching` and `scale_region_manual`.


```{r}

df <- region(cellExp, annot = TRUE)

p <- ggplot(df,aes(x = x,y = y, colour = cellType, region = region)) + 
  geom_point() + 
  facet_wrap(~imageID) +
  geom_hatching(window = "concave", 
                line.spacing = 11, 
                nbp = 50, 
                line.width = 1.5, 
                window.length = 0.1) +
  theme_minimal() + 
  scale_region_manual(values = 6:7, labels = c('ab','cd'))

p

```


# Damond et al. islet data.

Here we apply our `lisaClust` framework to three images of pancreatic islets 
from *A Map of Human Type 1 Diabetes Progression by Imaging Mass Cytometry* by 
Damond et al. (2019).

## Read in data

We will start by reading in the data and storing it as a `SegmentedCells` 
object. Here the data is in a format consistent with that outputted by 
CellProfiler.
```{r}
isletFile <- system.file("extdata","isletCells.txt.gz", package = "spicyR")
cells <- read.table(isletFile, header = TRUE)
cellExp <- SegmentedCells(cells, cellProfiler = TRUE)

```


## Cluster cell-types

This data does not include annotation of the cell-types of each cell. Here we 
extract the marker intensities from the `SegmentedCells` object using 
`cellMarks`. We then perform k-means clustering with eight clusters and store 
these cell-type clusters in our `SegmentedCells` object using `cellType() <-`.
```{r}
markers <- cellMarks(cellExp)
kM <- kmeans(markers,10)
cellType(cellExp) <- paste('cluster', kM$cluster, sep = '')
```

## Generate LISA curves

As before, we can calculate local indicators of spatial association (LISA) 
functions using the `lisa` function. In our implementation, our LISA curves are 
a localised summary of an L-function from a Poisson point process model. By 
default, `lisa` will calculate curves for 20 'sensible' radii for each 
cell-type. 

```{r}

lisaCurves <- lisa(cellExp, Rs = c(10,20,50))

```

## Perform some clustering

The LISA curves can then be used to cluster the cells. Here we use k-means 
clustering to cluster the cells into two microenvironments, other clustering 
methods like SOM could be used. We can store these cell clusters or cell 
"regions" in our `SegmentedCells` object using the `region() <-` function.

```{r}

kM <- kmeans(lisaCurves,2)
region(cellExp) <- paste('region',kM$cluster,sep = '_')

```



## Plot identified regions

Finally, we can use `hatchingPlot` to construct a `ggplot` object where the 
regions are marked by different hatching patterns. This allows us to visualize 
the two regions and eight cell-types simultaneously.

```{r}
hatchingPlot(cellExp)
```



# sessionInfo()

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