We provide several implementations of ARCOS as open-source code which can be found on github.

The code provided as R and Python packages can be used in Jupyter notebooks or in batch processing pipelines. The Napari plugin enables anyone without extensive programming knowledge to explore parameters through an intuitive GUI on a platform that emerges as a de-facto standard for viewing multidimensional images

How to get the necessary input data for ARCOS

To get from raw data to data that ARCOS accepts as input, several different tools can be used. The steps neccessary can be summarised as follows:

1. Acquire your image data.

2. Segment images to identify individual objects.

   • Tools that can be used for this purpose include Ilastik (a more general approach), simple image thresholding, or more specialised tools such as stardist, and cellpose in the case of microscopy data and many others.

3. Optionally, extract a measurement value from objects, for example from a fluorescent biosensor, other intensity changes, shape changes or something else entirely. This is needed if some objects should be excluded from the analysis based on a activity threshold.

4. Optionally, track detected objects across time and space. This is needed from subsequent downstream analysis but not necessarily for ARCOS itself.

How to prepare the data with ARCOS

Interpolate Measurments

If the measurement column contains missing values, in the first step the data should be interpolated. Helper functions are available across all implementations.

Detrend and rescale the measurement

Often time-series data can exhibit local and global trends that are introduced as artefacts of the data acquisition. In the case of fluorescence microscopy bleaching can be an example of such a bias. To help with this several de-trending methods are implemented in ARCOS, all of which are optional. There are three options available: ['none', 'lm', 'runmed']. With "none", the data is first rescaled to a feature range of 0,1. Subsequently, a short-term median filter is applied to the time series to reduce noise in the data. "lm" uses linear regression to detect long-term trends. Additionally, a short-term median filter is used to reduce noise in the time series. With "runmed", a long-term and a short-term median filter is used. After de-trending the data with options "lm" and "runmed", the output is rescaled to a feature range of 0,1.

Binarization

ARCOS requires binarized data to detect and track collective event clusters. Binarization is done by setting a threshold and defining measurements below this threshold as 0 and above as 1. Alternatively, all input objects can be defined as "active" if no measurement is available.

Identification of spatial clusters

A dbscan algorithm first spatially clusters entities deemed active in each frame. In step 2, clusters are sequentially linked between frames to capture collective events over time. The cluster in frame one forms a seed of a collective event. The cluster in frame two is linked to this seed cluster because several of its member cells are within the neighbourhood radius 𝜀. In frame three, only clusters #3, #5, & #6 are linked to the previous frame’s cluster. Cells in cluster #4 are too far and thus form a new seed of a collective event.

Flow-Chart overview of ARCOS event detection

The flow chart below outlines the steps in the algorithm.

About

ARCOS is a computational method to detect and quantify collective, spatio-temporally correlated phenomena. The algorithm identifies and tracks spatial clusters in time-lapse images. Although designed to analyze signalling phenomena in biological cells or cell collectives, it is applicable to other systems even outside of the realm of cell biology.

Code

We provide open-source implementations of ARCOS for:

Both code bases can handle segmented data and raster images, although the Python version contains additional optimizations and features to handle large datasets.

GUI

The napari plugins enables anyone without extensive programming knowledge to explore parameters through an intuitive GUI on a platform that emerges as a de-facto standard for viewing multidimensional images.

Demos

Publications

If you use this method in your research, please cite our papers:

@article{10.1083/jcb.202207048,
    author = {Gagliardi, Paolo Armando and Grädel, Benjamin and Jacques, Marc-Antoine and Hinderling, Lucien and Ender, Pascal and Cohen, Andrew R. and Kastberger, Gerald and Pertz, Olivier and Dobrzyński, 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},
    url = {https://doi.org/10.1083/jcb.202207048},
}

and if you used the tutorial please also cite:

@article{arcos-tutorial-2024,
    author = {Dobrzyński, Maciej and Grädel, Benjamin and Gagliardi, Paolo Armando and Pertz, Olivier},
    title = {Quantification of collective signalling in time-lapse microscopy images},
    journal = {Methods in Microscopy},
    volume = {1},
    number = {1},
    pages = {19--30},
    year = {2024},
    month = {06},
    issn = {2942-3899},
    doi = {doi:10.1515/mim-2024-0003},
    url = {https://doi.org/10.1515/mim-2024-0003},
}

How to use ARCOS

How ARCOS works

Learn the fundamentals of ARCOS to get a deeper understanding of our main features:

Installation instructions:

Package Specific Documentation and usage instructions:

Github repository:

An example dataset could look like this:

For the napari-plugin, as of now, a track id is required.

Installation instructions:

To install from pip, run this command in your terminal:

pip install arcos4py

Installing from conda-forge can be achieved by adding conda-forge to your channels with:

conda config --add channels conda-forge
conda config --set channel_priority strict

Once the conda-forge channel has been enabled, arcos4py can be installed with the conda package manager:

conda install arcos4py

Pip and conda-forge are the preferred methods to install arcos4py, as it will always install the most recent stable release.

You can either clone the public repository:

git clone https://github.com/bgraedel/arcos4py

curl -OJL https://github.com/bgraedel/arcos4py/tarball/master

Package Specific Documentation and usage instructions:

Github repository:

Napari

Demo of the napari plugin on Youtube:

Installation instructions:

pip install arcos-gui

Or install arcos-gui from within napari via the plugin toolbar (required for the standalone version).

To install the most recent development version :

pip install git+https://github.com/bgraedel/arcos-gui.git

Package Specific Documentation and usage instructions:

Github repository:

The following describes an example image processing pipeline written in python to analyse collective events in an MDCK epithelium. What we are aiming for can be seen in the gif above. First, the erk measurement is extracted from the images and the individual nuclei are tracked. The second step shows how to analyse the data with ARCOS. Similar results can be achieved with standalone tools such as CellProfiler and Ilastik. And both the R and Python packages can be used after preparing the data.

In the following zip file, you can find both the input data and the generated output from the image segmentation pipeline and ARCOS.

Data Preparation

The data in this example is from an MDCK cell line that stably expresses a fluorescent FRET biosensor reporting the activity of the ERK kinase.

In the first step, the nuclei are segmented using the stardist python package.

Subsequently, the mean intensity of individual objects in the ratio image is measured and the individual nuclei are tracked over time.

Import libraries and define custom functions

import os
import skimage
import numpy
import errno

from stardist.models import StarDist2D
from csbdeep.utils import normalize
from skimage.measure import regionprops, regionprops_table
from skimage.util import map_array

import pandas as pd
import trackpy

def create_folders(path: str, folder: list):
    for i in folder:
        folder_to_make = os.path.join(path, i)
        try:
            os.makedirs(folder_to_make)
            print(f'folder "{i}" created')
        except OSError as e:
            print(f'folder "{i}" alrady exists')
            if e.errno != errno.EEXIST:
                raise
                
def remap_segmentation(df: pd.DataFrame, segmentation: list, timepoint_column: str = 'timepoint', label_column: str = 'label', measure_column: str = 'ERK') -> list:
    tracked_numpy = df[[timepoint_column, label_column, measure_column]].sort_values(timepoint_column).to_numpy()
    grouped_numpy = numpy.split(tracked_numpy,numpy.unique(tracked_numpy[:,0], return_index = True)[1][1:])
    ratio_remapped = []
    for img, grp in zip(segmentation, grouped_numpy):
        img_copy = map_array(img, grp[:,1], grp[:, 2])
        ratio_remapped.append(img_copy)
    return ratio_remapped

Set variables

PATH = 'example_data' # where is you data located   
FOLDER = 'mdck_ekar' # subfolder of PATH where images are stored
OUT_DATA = 'data' # subfolder of PATH where csv is stored
OUT_LABELS = 'stardist' # subfolder of PATH where stardist segmentation is stored
FILENAME = 'C3-041_Ori.tif'
full_path = os.path.join(PATH, FOLDER)
orig_images_path = os.path.join(PATH, FOLDER)
out_path_csv = os.path.join(PATH, OUT_DATA)
create_folders(PATH, [OUT_DATA, OUT_LABELS]) 

Load image and stardist model

model = StarDist2D.from_pretrained('2D_versatile_fluo') # standard stardist model for 2d segmentation
image_data = skimage.io.imread(os.path.join(orig_images_path, FILENAME)) 

Segment Nuclei and extract values from image

out_path_stardist = os.path.join(PATH, OUT_LABELS,  'stardist.tif')
segmentation = []
df = []

for t, tp_data in enumerate(image_data):
    print(f'analysing timepoint {t}')
    labels, _ = model.predict_instances(normalize(tp_data))
    labels = skimage.segmentation.clear_border(labels)
    dic = regionprops_table(labels, tp_data, properties=['label', 'centroid', 'intensity_mean', 'area'])
    dic['timepoint'] = numpy.repeat(t, len(dic['label']))
    df.append(pd.DataFrame(dic))
    skimage.segmentation.clear_border(labels)
    segmentation.append(labels)

# optionally save segmentation
skimage.io.imsave(out_path_stardist, numpy.stack(segmentation))

Track Nuclei and save csv

df_full = pd.concat(df)
df_full = df_full.rename(columns={"centroid-1": "x", "centroid-0": "y", 'intensity_mean': 'ERK'})
df_full = df_full.sort_values(['timepoint'])
df_tracked = trackpy.link_df(df_full, search_range = 10, memory = 2, t_column = 'timepoint')
df_tracked = df_tracked.reset_index(drop=True).rename(columns={'particle': "track_id"})
df_tracked.to_csv(out_path_csv+'\\tracked_data_fret.csv')

Analyse data with ARCOS

In this example, the python package arcos4py is used. But the same analysis could be carried out easily with the R package or the napari plugin.

Imports

from arcos4py import ARCOS
from arcos4py.tools import filterCollev
from arcos4py.plotting import NoodlePlot

Detect Collective Events

ts = ARCOS(df_tracked, ["x", "y"], 'timepoint','track_id', 'ERK')
ts.interpolate_measurements()
ts.bin_measurements(biasMet='none', binThr=0.28)
df_arcos = ts.trackCollev(eps=40, minClsz=5)

Filter Collective Events

filterer = filterCollev(df_arcos, 'timepoint', 'clTrackID', 'track_id')
ts_filtered = filterer.filter(25, 10)

Plot NoodlePlot

NoodlePlot(ts_filtered, 'clTrackID', 'track_id', 'timepoint', 'x', 'y').plot('x')

Visualize Events in Napari

This step is optional and only one way to visualize events but can be usefull to validate correct event detection.

Imports

from napari import Viewer

TAB20 = [
    "#1f77b4",
    "#aec7e8",
    "#ff7f0e",
    "#ffbb78",
    "#2ca02c",
    "#98df8a",
    "#d62728",
    "#ff9896",
    "#9467bd",
    "#c5b0d5",
    "#8c564b",
    "#c49c94",
    "#e377c2",
    "#f7b6d2",
    "#7f7f7f",
    "#c7c7c7",
    "#bcbd22",
    "#dbdb8d",
    "#17becf",
    "#9edae5",
]

Prepare Data

np_data = df_tracked[['track_id', 'timepoint', 'y', 'x']].to_numpy()
colors = numpy.take(numpy.array(TAB20), ts_filtered['clTrackID'].unique(), mode="wrap")
df_w_colors = pd.merge(ts_filtered, pd.DataFrame(data={'colors': colors, 'clTrackID': ts_filtered['clTrackID'].unique()}))
points_data = df_w_colors[['timepoint', 'y', 'x']].to_numpy()
colors_data = df_w_colors['colors'].to_numpy('str')

Remap measured Ratio to segmented labels

ratio_remapped = remap_segmentation(df_tracked, segmentation)
ratio_remapped = numpy.stack(ratio_remapped)

Open Napari and add Layers

viewer = Viewer()
viewer.add_image(image_data, name='ERK Ratio image', colormap='inferno')
viewer.add_image(ratio_remapped, colormap='viridis')
viewer.add_labels(numpy.stack(segmentation), name='segmentation', visible=False)
viewer.add_tracks(np_data, name='cell tracks')
viewer.add_points(points_data, face_color=colors_data, name='collective events')