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.

Napari

Napari is a multidimensional image viewer for python. It is available either as a python package or as a standalone application. See here for installation instructions of napari.

Demo of the napari plugin on Youtube:

Installation instructions:

After successfully installing napari, you can install arcos-gui via pip:

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:

Arcos is aimed at analysing time series data which should be arranged in long format. Each row should define the object’s location, time, and optionally the measurement value. For the implementations in R and python, the objects don't necessarily need to be tracked over time. However, it is recommended as it allows a more in-depth downstream analysis of ARCOS's output.

An example dataset could look like this:

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

Installation instructions:

You can install the development version from with:

Package Specific Documentation and usage instructions:

Github repository:

Installation instructions:

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

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

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

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

The source for arcos4py can be downloaded from the .

You can either clone the public repository:

Or download the :

Package Specific Documentation and usage instructions:

Github repository:

ARCOS is a computational method to detect and quantify collective phenomena. The algorithm was designed with the signaling of epithelial cells in mind however it is also applicable to other systems even outside of the realm of cell biology.

We provide several open-source implementations of ARCOS

• Python (arcos4py)

• R (ARCOS)

• Plugin for Napari image viewer (arcos-gui)

ARCOS is now published in the Journal of Cell Biology (JCB): https://doi.org/10.1083/jcb.202207048

For a complete tutorial on how to use ARCOS from raw images to full analysis you may also refer to our recent tutorial published in Methods in Microscopy (MiM): https://doi.org/10.1515/mim-2024-0003

and the corresponding GitHub repository containing a detailed notebook and installation instructions.

Detecting Collective events with ARCOS

How to get ARCOS

How to use ARCOS

Overview of how ARCOS works

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

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

@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},
    abstract = "{Increasing experimental evidence points to the physiological importance of space–time correlations in signaling of cell collectives. From wound healing to epithelial homeostasis to morphogenesis, coordinated activation of biomolecules between cells allows the collectives to perform more complex tasks and to better tackle environmental challenges. To capture this information exchange and to advance new theories of emergent phenomena, we created ARCOS, a computational method to detect and quantify collective signaling. We demonstrate ARCOS on cell and organism collectives with space–time correlations on different scales in 2D and 3D. We made a new observation that oncogenic mutations in the MAPK/ERK and PIK3CA/Akt pathways of MCF10A epithelial cells hyperstimulate intercellular ERK activity waves that are largely dependent on matrix metalloproteinase intercellular signaling. ARCOS is open-source and available as R and Python packages. It also includes a plugin for the napari image viewer to interactively quantify collective phenomena without prior programming experience.}",
    issn = {0021-9525},
    doi = {10.1083/jcb.202207048},
    url = {https://doi.org/10.1083/jcb.202207048},
    eprint = {https://rupress.org/jcb/article-pdf/222/10/e202207048/1915749/jcb\_202207048.pdf},
}

and if you used the tutorial please also cite:

@article{DobrzyńskiGrädelGagliardiPertz+2024,
    url = {https://doi.org/10.1515/mim-2024-0003},
    title = {Quantification of collective signalling in time-lapse microscopy images},
    title = {},
    author = {Maciej Dobrzyński and Benjamin Grädel and Paolo Armando Gagliardi and Olivier Pertz},
    journal = {Methods in Microscopy},
    doi = {doi:10.1515/mim-2024-0003},
    year = {2024},
    lastchecked = {2024-06-18}
}

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.

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')