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

Since reproducing the results only requires the python project named CellectsPaper, a prior installation of Cellects is not mandatory.

Content

This repository contains:
1 Two files corresponding to three different Cellects installation methods:

• Cellects_installer.exe
• Cellects.zip

2 Two zip files allowing to reproduce the results of the paper describing Cellects:

• Cellects_data.zip
• CellectsPaper.zip

The next section explain how to install and use Cellects,
and the last section explain how to reproduce the results of the paper.

1. Install and use Cellects

1.1. Installation

Following the README available here, you can install Cellects by:

• Downloading and running Cellects_installer.exe or Cellects.zip on windows
• Cloning the github repository at github.com/Aurele-B/Cellects

1.2. Usage

Learn to use Cellects with:

• This user manual: https://github.com/Aurele-B/Cellects/blob/main/UserManual.md
• This usage example in video: https://www.youtube.com/watch?v=N-k4p_aSPC0

2. Reproduce the results of the paper

2.1. Experimental context and validation process

The experimental procedure used to obtain this dataset is described in Appendix 2,
and the validation process is explained in the Validation section of the main text.

2.2. Files structure

Cellects_data.zip
|- 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/

CellectsPaper.zip
|- src/
|  |- cellects/
|  |  |- config
|  |  |- core
|  |  |- image_analysis
|  |  |- paper_illustrations
|  |  |- utils
|  |  |- __main__.py

2.3. Files content

2.3.1. 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

2.3.2. 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

2.3.3. Figures of the paper presenting Cellects

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.

2.3.4. Scripts to reproduce the figures of the paper

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

2.4. Usage

To reproduce our results, download and extract Cellects_data.zip and CellectsPaper.zip
The README file in the CellectsPaper folder explains how to install and use this python project.

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 [Software]. Zenodo. https://doi.org/10.5281/zenodo.8184830

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