This README contains the information to install the Cellects software, to use it,
and to reproduce the results of the paper describing it.

Installation and documentation

Find Cellects' documentation and readme on github.

Content

This repository contains one zip file allowing to reproduce the results of the paper describing Cellects:

• Cellects_data.zip

Files structure

Cellects_data.zip
|- cellular_dynamics_and_morphologies_across_systems/
|  |- figure1.py
|  |- fig1/
|  |- Cobo2018/
|  |- Guiet2022/
|  |- physarum/
|- ground_truth_accuracy/
|  |- figure2_ground_truth_tests.py
|  |- fig2/
|- a_posteriori_accuracy/
|  |- CellectsPaper
|  |  |- src/
|  |  |  |- cellects/
|  |  |  |- config
|  |  |  |- core
|  |  |  |- image_analysis
|  |  |  |- paper_illustrations
|  |  |  |- utils
|  |  |  |- __main__.py
|  |- paper_figs_jpg/
|  |- paper_figs_tif/
|  |- quail_development/
|  |- slime_choice_on_blackpaper/
|  |- slime_circular_on_leds/
|  |- slime_circular_on_whitepaper/
|  |- slime_lengthen_on_leds/
|  |- slime_square_on_leds/
|  |- Validation_images/
|  |  |- slime_choice_on_blackpaper/
|  |  |- slime_circular_on_leds/
|  |  |- slime_circular_on_whitepaper/
|  |  |- slime_lengthen_on_leds/
|  |  |- slime_square_on_leds/

Reproducing Figure 1

• Cellects version: v1.0.1
• Subfolder location: cellular_dynamics_and_morphologies_across_systems
• Additional information: each subfolder contains a.md file to describe what to do for each data set.
• Python file to run: Figure1.py

Reproducing the ground truth analysis of Figure 2

• Cellects version: v1.0.1
• Subfolder location: ground_truth_accuracy
• Python file to run: Figure2_ground_truth_tests.py

Reproducing the a posteriori analysis of Figure 2

• Cellects version: not versioned, saved in the CellectsPaper folder
• Subfolder location: a_posteriori_accuracy
• Additional information: README.md in the CellectsPaper folder (specific installation)
• Python file to run: Cellects paper.py

Detailed files content

Files content of the cellular dynamics and morphologies across systems

Cobo2018 contains:

• replicate_fungi_analysis.md: a file explaining where to download the 'Fungus' data and how to analyze it using Cellects.
• cellects_settings.json: a parameter file allowing users to run the analysis without having to change any parameter of Cellects' GUI.
• cellects_data.h5: a data file allowing users to run the video tracking without having to run the image analysis using Cellects' GUI.

Guiet2018 contains:

• replicate_hela_analysis.md: a file explaining where to download the 'HeLa' data and how to analyze it using Cellects. It also contains a small script to convert the 5 channels .tif file into an image stack (usable by Cellects).
• cellects_settings.json: a parameter file allowing users to run the analysis without having to change any parameter of Cellects' GUI.
• cellects_data.h5: a data file allowing users to run the video tracking without having to run the image analysis using Cellects' GUI.

physarum contains:

• physarum_rgb.h5: The first and 500th rgb image of the P.polycephalum example.
• coord_physarum_t500_y1475_x1477.h5: The coordinates of the pixels covered by the cell at these frames.
• coord_physarum_network_t500_y1475_x1477.h5: The coordinates of the pixels covered by the network at these frames.
• coord_physarum_pseudopods_t500_y1475_x1477.h5: The coordinates of the pixels covered by the pseudopods at these frames.
• edges_physarum_t720_y1475_x1477.csv: The identities of the two vertices linking each edge of the graph at all frames.
• vertices_physarum_t720_y1475_x1477.csv: The identities and coordinates of all vertices of the graph at all frames.
• replicate_physarum_analysis.md: a file explaining how to reproduce the analysis.

fig1 contains:

• All panels of the Figure 1 of the paper.

figure 1.py contains:

• The complete script to reproduce all panels of the Figure 1 of the paper.

Files content of the ground truth accuracy

fig2 contains:

• All panels of the ground truth comparison part of the Figure 2 of the paper.

Figure2_ground_truth_tests.py contains:

• The complete script to reproduce all panels of the ground truth comparison part of the Figure 1 of the paper.

Files content of the a posteriori analysis

Raw data files and outputs from Cellects

Raw data and outputs from the Cellects software can be found in six folders (named quail_development,
slime_choice_on_blackpaper, slime_circular_on_leds, slime_circular_on_whitepaper, slime_lengthen_on_leds,
slime_square_on_leds) in the Cellects_data.zip archive.

In these six folders, raw data are image sequences (in tif for quail_development and jpg for all others).

The outputs from Cellects include:

• Visualization of the efficiency of the analysis:
  • jpg files contain screenshots of the analysis of all arenas (and their identification number).
  • mp4 files contain videos of the analysis of each arena (named according to their identification number).
• Data tables:
  • one_row_per_arena.csv
    • Description: contains the kind of variables that have only one value for the whole video of an arena
    • Variables (unit):
      • arena (1): identification number of the arena
      • first_move (frame): time at which Cellects detects a first movement of a specimen in the arena
      • iso_digi_transi (min): when the specimen displays an isotropic growth, if it switches into a digitated growth, save the time at which it happens. NA if one of these conditions is not met.
      • is_growth_isotropic (bool): 1 if the specimen displays an isotropic growth, 0 otherwise
      • final_area (pixels): the area covered by the specimens at the last frame.
  • one_row_per_frame.csv
    • Description: contains the kind of variables that have one value per frame for each arena
    • Variables (unit):
      • arena (1): identification number of the arena
      • time (min): for each arena, one row corresponds to one frame of the video
      • area (pixels): area covered by the specimen
      • perimeter (pixels): the total perimeter of the specimens at the last frame.
      • circularity (1): 4piarea/(perimeter^2)
      • rectangularity (1): area/(R1*R2) with R1 and R2 the lengths of the sides of the smallest rectangle containing the specimens
      • total_hole_area (pixels): summed area of all holes
      • solidity (1): area/convex_hull_area
      • convexity (1): convex_hull_perimeter/perimeter
      • eccentricity (1): sqrt(1 - (minor_axis_length/major_axis_length))
      • euler number (1): connected shape number - holes number
      • standard_deviation_x (pixels): standard deviation on the x-axis
      • standard_deviation_y (pixels): standard deviation on the y-axis
      • skewness_x (1): skewness on the x-axis
      • skewness_y (1): skewness on the y-axis
      • kurtosis_x (1): kurtosis on the x-axis
      • kurtosis_y (1): kurtosis on the y-axis
      • major_axis_len (pixels): sqrt(6 * (C2x + C2y + sqrt((2*C11)² + (C2X - C2y)²))) With C2x and C2y the second orders central moments with regard to x and y. And with C11 the first order central moment with regard to both x and y.
      • minor_axis_len (pixels): sqrt(6 * (C2x + C2y - sqrt((2*C11)² + (C2X - C2y)²)))
      • axes_orientation (radians): 0.5 * arctan((2*C11)/(C2x - C2y))
  • one_row_per_frame_arena1.csv
    • Description: contains the kind of variables that have one value per frame for each arena. Only exists when there can be more than one specimen per arena.
    • Variables (unit):
      • arena (1): identification number of the arena
      • time (min): for each arena, one row corresponds to one frame of the video
      • area (pixels): followed by a number identifying one specimen in the arena
      • newly_explored_area (pixels): area covered by the specimens for the first time at this frame
  • one_row_per_oscillating_cluster.csv
    • Description: contains a quantification of the clusters oscillating synchronously in the specimen
    • Variables (unit):
      • arena (1): identification number of the arena
      • mean_pixel_period (frame): the average period of the pixels of the current oscillating cluster
      • phase (frame): the average phase of the pixels of the current oscillating cluster
      • cluster_size (pixels): the size of the current oscillating cluster
      • edge_distance (pixels): the minimal distance between the current oscillating cluster and the edge of the specimen
  • software_settings.csv
    • Description: A list of all the settings to use when analyzing the current folder with Cellects.
• Software and analysis related files:
  • infos.JPG files contain the treatment applied to each arena
  • .pkl files contain parameters and matrices allowing to rerun the analysis more quickly

A posteriori validation of the Cellects software

The validation folder, in the Cellects_data.zip archive, contains folders named after the five tested experimental conditions:

• slime_choice_on_blackpaper
• slime_circular_on_leds
• slime_circular_on_whitepaper
• slime_lengthen_on_leds
• slime_square_on_leds

Each of these folders contains:

• The result of automatic segmentation for each of the sixty randomly selected arenas (Last_image_arena_x.tif)
• The manual correction of these segmentations (Aremaskx.tif)
• .pkl files allowing to rerun the analysis more quickly

Note: files named Last_image_arena_xbis.tif or Aremaskxbis.tif correspond to the second analysis made on these arenas in Appendix 2.
organized data tables, data visualizations, and statistical output

Figures of the paper presenting the a posteriori validation

The folders paper_figs_jpg and paper_figs_tif, in the Cellects_data.zip archive, are made to be empty.
Running the CellectsPaper python project will fill them with the images and plots used in the figures of the related article.
All files created in this way are compatible with the CC0 license waiver.

Scripts to reproduce the figures of the a posteriori validation

CellectsPaper contains a version of Cellects without GUI and the code to
reproduce the figures of the a posteriori validation using the Cellects_data folder.

Location of the data

Boussard, Aurèle; Arrufat, Patrick; Dussutour, Audrey; Pérez-Escudero, Alfonso (2023). Cellects, a software to quantify cell expansion and motion [Dataset]. Dryad. https://doi.org/10.5061/dryad.7wm37pvzp

An up-to-date version of the Cellects software, along with installation procedure and user manual, can be found at https://github.com/Aurele-B/Cellects