-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
193 lines (141 loc) · 8.02 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
---
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 -->
**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. The associated publication in the Journal of Cell Biology is available [here](https://doi.org/10.1083/jcb.202207048).
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)).
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. 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 plugin with GUI for [napari](https://napari.org) image viewer; written by Benjamin Grädel. See a YouTube [demo](https://www.youtube.com/watch?v=hG_z_BFcAiQ).
Please visit the main ARCOS project page for general documentation and installation instructions [gitbook](https://arcos.gitbook.io/home/).
## 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
