README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# ARCOS

<!-- badges: start -->
<!-- badges: end -->
<br>
<p align="center">
  <img alt="Light" src="man/figures/README-ARCOS-logo.png" width="45%">
&nbsp; &nbsp; &nbsp; &nbsp;
  <img alt="Dark" src="man/figures/README-cellular-dynamics-lab-logo2.png" width="45%"> 
</p>
<br>

**A**utomated **R**ecognition of **Co**llective **S**ignalling (ARCOS) is an [R](https://www.r-project.org) package to identify space-time correlations in biological data developed in the [Cellular Dynamics Lab](https://www.pertzlab.net) at the University of Bern. 
The associated publication in the Journal of Cell Biology is available [here](https://doi.org/10.1083/jcb.202207048). A video summary can be viewed [here](https://youtu.be/UoX4CynZfaE?si=TVUMZespd4642gyN).


The software identifies and visualises collective protein activation in 2- and 3D cell cultures over time. Such collective phenomena have been recently identified in various biological systems. 
They have been demonstrated to play an important role in the: (1) maintenance of the epithelial homeostasis ([Gagliardi et al., 2020](https://doi.org/10.1016/j.devcel.2021.05.007), [Takeuchi et al., 2020](https://doi.org/10.1016/j.cub.2019.11.089), [Aikin et al., 2020](https://doi.org/10.7554/eLife.60541)), (2) acinar morphogenesis ([Ender et al., 2020](https://doi.org/10.1101/2020.11.20.387167)), (3) osteoblast regeneration ([De Simone et al., 2021](https://doi.org/10.1038/s41586-020-03085-8)), and (4) coordination of collective cell migration ([Aoki et al., 2017](https://doi.org/10.1016/j.devcel.2017.10.016), [Hino et al., 2020](https://doi.org/10.1016/j.devcel.2020.05.011)).

![](https://user-images.githubusercontent.com/25979488/123080758-8d053180-d41d-11eb-9d05-b17786091696.mp4)

Despite its focus on cell signalling, the framework can be also applied to other spatially correlated phenomena that occur over time in an arbitrary spatial dimension.

## Implementations

This repository covers the R implementation. 
Visit the [main ARCOS project page](https://arcos.gitbook.io/home/) to learn about the ARCOS ecosystem.

For other implementations check:

- [arcos4py](https://github.com/bgraedel/arcos4py), a Python implementation written by Benjamin Grädel.
- [arcos-gui](https://github.com/bgraedel/arcos-gui), a dedicated plugin with GUI for [napari](https://napari.org) image viewer. See a YouTube [demo](https://www.youtube.com/watch?v=hG_z_BFcAiQ).
- [arcos-px-gui](https://github.com/bgraedel/arcosPx-napari), a dedicated plugin with GUI for [napari](https://napari.org) image viewer dedicated to tracking clusters in raster images. 


![arcos-gui plugin for napari image viewer](man/figures/README-napari-gui-3D.png)

## Cite

If you are using ARCOS in your research please cite the relevant paper:

```
@article{gagliardi2023,
    author = {Gagliardi, Paolo Armando and Gr\"adel, Benjamin and Jacques, Marc-Antoine and Hinderling, Lucien and Ender, Pascal and Cohen, Andrew R. and Kastberger, Gerald and Pertz, Olivier and Dobrzy\'nski, Maciej},
    title = "{Automatic detection of spatio-temporal signaling patterns in cell collectives}",
    journal = {Journal of Cell Biology},
    volume = {222},
    number = {10},
    pages = {e202207048},
    year = {2023},
    month = {07},
    issn = {0021-9525},
    doi = {10.1083/jcb.202207048}
}
```

## Installation

You can install the development version from [GitHub](https://github.com/dmattek/ARCOS) with:

``` r
# install.packages("devtools")
devtools::install_github("dmattek/ARCOS")
```

## Data format

The minimal input comprises time series arranged in [long format](https://en.wikipedia.org/wiki/Wide_and_narrow_data#Narrow), where each row defines object's location and time. 

ARCOS defines an `arcosTS` object that extends the `data.table` [class](https://cran.r-project.org/web/packages/data.table/). In practice, additional attributes are added to the existing `data.table` object to define column names relevant for the analysis.

## Example

The following synthetic dataset contains 81 objects (e.g., biological cells) spaced on a 2D 9x9 lattice with a spacing of 1x1 length units. Each object has an ID (column `id`) and can assume values 0 and 1 (column `m`), which correspond to an *inactive* and *active* state. The evolution of active states takes place over 8 consecutive time points (column `t`). Each object wiggles slightly around its position. 

```{r ex1gen, warning=FALSE}
library(ARCOS)
library(ggplot2)

# Generate a synthetic dataset with a single event evolving over 8 frames
dts = ARCOS::genSynthSingle2D(inSeed = 7)
```

```{r ex1showTS, echo=FALSE}
knitr::kable(head(ARCOS::keepSignifDig(dts, 4)))
```

In the plot below, grey circles correspond to inactive and black to active states of objects and their collective activation (*wave*) develops over 8 time points.

```{r ex1plotTS, echo=FALSE, fig.height=5, fig.width=10}
p1 = ggplot(dts,
            aes(x = x,
                y = y)) +
  geom_point(aes(color = as.factor(m)), size = 5) +
  scale_color_manual(values = c("grey80",
                                "grey20")) +
  facet_wrap(~ t, ncol = 4) +
  coord_fixed(ratio=1) +
  theme_void() +
  theme(text = element_text(size = 20),
        legend.position = "none")

p1
```

The following R code will identify the collective event and store the result in a `dcoll` variable. We are interested in a collective event comprised of *active* objects, hence we select rows with `m > 0`. The parameter `eps` sets the threshold radius for the spatial clustering (`dbscan` algorithm). Here, we set `eps = 2`, which is enough to find all the nearest active objects in the cluster, given the 1x1 horizontal and vertical spacing of objects in the lattice.

```{r ex1trackColl}
# Track collective events
dcoll = ARCOS::trackColl(dts[m > 0], 
                         eps = 2.)
```

```{r ex1showColl, echo = FALSE}
knitr::kable(head(ARCOS::keepSignifDig(dcoll, 4)))
```

The `dcoll` table contains the results of spatio-temporal clustering. Column `collid` stores a unique identifier of the collective event. The `collid.frame` column stores an identifier of collective event that is unique only within a frame.

For better visualisation, we add convex hulls around collective events using the `chull` function from the `grDevices` package.

```{r ex1calcCH}
# Create convex hulls around collective events for visualisation
dcollch = dcoll[,
                .SD[grDevices::chull(x, y)],
                by = .(t,
                       collid)]
```

In the following plot, objects that participate in the collective event are indicated by red dots. The red polygon indicates a convex hull.

```{r ex1plotColl, echo = FALSE, fig.height=5, fig.width=10}
p2 = ggplot(dts,
            aes(x = x,
                y = y)) +
  geom_point(aes(color = as.factor(m)), size = 5) +
  scale_color_manual(values = c("grey80",
                                "grey20")) +
  ggnewscale::new_scale_color() +
  geom_point(data = dcoll,
             aes(color = as.factor(collid)), size = 1) +
  geom_polygon(data = dcollch,
               aes(color = as.factor(collid)),
               fill = NA, 
               linewidth = 1) +
  facet_wrap(~ t, ncol = 4) +
  coord_fixed(ratio=1) +
  theme_void() +
  theme(text = element_text(size = 20),
        legend.position = "none")

p2
```

### Save frames

The code below saves individual time frames as `png` files in the `frames` folder located in the current working directory.

```{r ex1saveFrames, eval=F}
ARCOS::savePlotColl2D(dts, dcoll, 
                      outdir = "./frames",
                      xlim = c(-.5,9),
                      ylim = c(-.5,9),
                      plotwh = c(4,3),
                      imtype = "png")
```

Individual files can be later combined into a movie using software such as [ffmpeg](http://ffmpeg.org). 

For example, if you have `ffmpeg` installed on your system, create an `mp4` movie at 2 frames/second and a 520x420 pixel resolution by typing the following line in the command line:

```{bash ex1bash, eval = F}
ffmpeg -framerate 2 -i "frames/F%04d.png" -vcodec libx264 -s 560x420 -pix_fmt yuv420p frames-all.mp4
```


### Visualise interactively

Interactive visualisation with an accompanying shiny app located in `inst/shiny-examples/collVisApp`.

```{r ex1visShiny, eval=F}
library(shiny)
library(plotly)
library(RColorBrewer)

ARCOS::runCollVis(dts, dcoll)
```

## The algorithm

![arcos-gui plugin for napari image viewer](man/figures/README-algFlow.png)