cellx-predict
This package provides a reference implementation of a tau-VAE. The tau-VAE network is able to learn an explainable model of cell behaviour from timelapse-image sequences.
Installation and requirements
Dependencies
The software requires Python 3.7 (or greater), numpy
, scipy
, tqdm
, Tensorflow
, scikit-image
and scikit-learn
. Further, this repo makes extensive use of the cellx
and btrack
libraries. Full requirements can be found in the requirements.txt
file.
Running in a Docker container
We recommend running this in a docker container.
Build the image:
git clone https://github.com/lowe-lab-ucl/cellx-predict.git
cd cellx-predict
docker build . -t cellxpred/cellxpred:latest
You can use the included shell script to run the container and specify the jobs according to the descriptions below.
./run_docker.sh
Local installation
You can also clone and install a local version of the software.
git clone https://github.com/lowe-lab-ucl/cellx-predict.git
cd cellx-predict
pip install -e .
Hardware requirements
Training
We have tested the software on the following systems, a Ubuntu 20.04LTS server with 256 Gb RAM and NVIDIA V100 GPU and an Ubuntu 18.04LTS server with 128 Gb RAM and NVIDIA GTX1080Ti GPUs.
Inference
We tested the software on OS X and Ubuntu and found the inference algorithm to be performant even on basic commodity hardware such as laptops.
Data structure
We recommend structuring your data in the following format. Within the glimpses folder, the name of subfolders (e.g. apoptosis, mitosis) are used to infer the ground truth labels of the data contained within each folder.
training/
patches/
README.md
image_patches_0.tfrecord
glimpses/
README.md
data/
apoptosis/
GV0800_Pos3_7_RFP_apop.tif
mitosis/
metadata/
apoptosis/
GV0800_Pos3_7_RFP_apop.npz
mitosis/
inference/
glimpses/
GV0804_Pos12_18_RFP_mit.tif
Data availability
Datasets to enable training and inference are available from the UCL data repository using the following DOI: https://dx.doi.org/10.5522/04/16578959
Usage
The model needs to be trained in three separate operations:
- First the
encoder
model is trained - Then the
projector
model is trained - Finally, the
temporal
model is trained.
For inference, we use the full
model.
Command line options for each part of the pipeline can be listed using the help argument:
python run_training.py -h
Once trained, model weights and other parameters are stored in the models folder.
1. Encoder model
1.1 Training the encoder model
python run_training.py \
--model=encoder \
--src_dir=/path/to/training/patches \
--log_dir=/path/to/log_dir \
--epochs=50 \
1.2 Monitoring training using Tensorboard
During training of any model, the optimization can be monitored using Tensorboard:
tensorboard --logdir /path/to/log_dir
1.3 Training the projector model
python run_training.py \
--model=projector \
--src_dir=/path/to/training/patches \
2. Temporal model
2.1 Prepare training data for the temporal model
Before training the temporal model, you will need to prepare the training data using parameters of the encoder model. To do so, run the following script:
python run_prepare.py \
--model=temporal \
--src_dir=/path/to/training/glimpses \
--use_rotations
2.2 Training the temporal model
The temporal model is trained using the following script:
python run_training.py \
--model=temporal \
--src_dir=/path/to/training/glimpses \
--log_dir=/path/to/log_dir \
--epochs=50 \
--use_synthetic \
--use_probabilistic_encoder \
The training can be monitored using Tensorboard as above.
3. Inference
An example notebook using the full model to perform inference (inference.ipynb
) can be found in the notebooks folder.
Citation
@article{Soelistyo2021.11.24.469554,
author = {Soelistyo, Christopher and Vallardi, Giulia and Charras, Guillaume and Lowe, Alan R},
title = {Learning the rules of cell competition without prior scientific knowledge},
elocation-id = {2021.11.24.469554},
year = {2021},
doi = {10.1101/2021.11.24.469554},
publisher = {Cold Spring Harbor Laboratory},
URL = {https://www.biorxiv.org/content/early/2021/11/25/2021.11.24.469554},
eprint = {https://www.biorxiv.org/content/early/2021/11/25/2021.11.24.469554.full.pdf},
journal = {bioRxiv}
}