An unsupervised method for identifying cell behaviour in heterogeneous cell trajectory data

cellPLATO workflow:

1. takes tracking and segmentation data as input
2. measures morphology and migration at each timepoint for every cell
3. clusters cells with similar morphology and migration using UMAP and HDBSCAN
4. measures the similarity of behavioural sequences for each cell over time, and clusters them to form 'trajectories of behaviour'
5. de-abstractifies the clustered behaviours using graphics of exemplar cells, readouts of plasticity and comparisons between conditions

Updates

Published in the Journal of Cell Science on the 24th of June, 2024 here

Movies for the paper can be found here

On the 14th of May 2023 at Journal of Cell Science's 'Imaging Cell Dynamics' conference in Lisbon, we presented cellPLATO's UMAP and HDBSCAN module to produce a fingerprint of cell behaviours in a heterogeneous population. Go here to see the poster!

Description

A Python data analysis package for time-lapse cell migration experiments written in collaboration with Tyler Sloan at Quorumetrix. Used after segmention (eg. Cellpose) and tracking (eg. Bayesian Tracker) of large timelapse microscopy datasets, cellPLATO measures morphokinetic information about each cell per timepoint and automatically makes statistical plots (plots of difference in python, inspired by those in R by Joachim Goedhart). Users can pool/compare multiple replicates from multiple experimental conditions. Next, dimensionality reduction and cluster analysis is used to segregate cells into behavioural subtypes and produce a fingerprint for each condition (cells per behaviour subtype). Finally, exemplar cells are automatically selected and graphically displayed to disambiguate the nature of each quanitfied cell behavioural subtype.

Installation instructions

1. Using anaconda terminal, cd to a directory where you want to install the software
2. Clone the repository onto your local machine: git clone
3. cd to the folder that contains 'environment.yml' and type: conda env create -f environment.yml
4. Activate the environment: conda activate cellPLATO
5. Install the rest of the packages: pip install -e .

Known issues with installation:

If you get the ERROR: Could not build wheels for hdbscan, which is required to install pyproject.toml-based projects

Please check 1) you have C++ installed, 2) install hdbscan using 'conda install -c conda-forge hdbscan'

If matplotlib fails to install via pip for the same reason, please use:

conda install -c conda-forge matplotlib

How to use cellPLATO:

cellPLATO is made to be used downstream of cell segmentation and tracking, and can currently be used with several tracking methodologies. The default is btrack.

Step 1:

Organize your data into the following heirarchal format:

• 📁 Master folder [Folder_path]
  • 🌿 Condition_1 [Experimental condition 1]
  • 🔄 Rep_1 [Experimental repeat 1]
    • 📄 Replicate_1.h5
  • 🔄 Rep_2
    • 📄 Replicate_2.h5
  • 🔄 Rep_n
    • 📄 Replicate_n.h5
  • 🌿 Condition_2
  • 🔄 Rep_1
  • 🔄 Rep_2
  • 🔄 Rep_n
  • 🌿 Condition_n
  • 🔄 Rep_n

📁 represents the main folder or directory. 🌿 represents the condition folders. 🔄 represents the replicate folders. 📄 represents the individual H5 files containing the segmentations and tracks

Step 2:

Open the config.py file, and edit as directed.

As a minimum fill in the master directory, experiments to include, pixel size and sampling interval.

Experiments to include getsf filled with the folder names of the conditions you are measuring:

EXPERIMENTS_TO_INCLUDE = ['Condition_1', 'Condition_2', 'Condition_n']

Step 3:

Run cellPLATO through Jupyter Notebooks. Choose the master notebook to run all of the analysis step by step.