CloVarS: a simulation of single-cell clonal variability

This repository contains the source code accompanying the article "CloVarS: a simulation of single-cell clonal variability". The article is available on BioRxiv.

What is CloVarS

The Clonal Variability Simulator (CloVarS) is a cell culture simulation that generates synthetic single-cell lineage data, as normally obtained from time-lapse microscopy experiments.

The example below depicts a single colony, starting from a single cell, which grows over 7 days:

Quickstart

• Confirm that you have Python 3.8 or newer installed in your computer
• Open a terminal/CMD
• Type the command pip install clovars to download and install CloVarS
• Type clovars run to run CloVarS with the default settings
• Simulation results are placed in the folder named output (placed in the folder where your terminal is at)

Installation

CloVarS requires Python version 3.8+ in order to run. You can install CloVarS in your Python environment with the command:

pip install clovars

Note: this is meant to be typed in your system terminal / CMD, not in the Python shell.

Once installation is complete, the clovars command is added yo your system. All necessary dependencies are installed automatically.

How to use CloVarS

CloVarS can be executed in the following modes:

• run - run a simulation with the given settings;
• view - visualize the results of a previous simulation run (figures, images, videos);
• analyse - run analytical tools on the result of a previous simulation run;
• fit - fit experimental data to a variety of curves.

You also need to provide the path to the necessary settings files as a command-line argument. If no arguments are provided, clovars will use the default settings files. These files are set up for demonstration purposes, so we encourage you to use your own when designing new simulations to run.

Simulation Settings

The settings files use the TOML syntax, which makes it easy to open and edit them in any text editor. This folder has examples for the structure of the settings files. Be sure to pay attention: CloVarS will likely run into errors if the setting files have incorrect or missing values!

For more information on the settings and their meaning, please read the docs here (coming soon!).

Run CloVarS

clovars run path_to/run_settings.toml path_to/colonies.toml

where:

• path_to/run_settings.toml is the path for a TOML file with the run settings;
• path_to/colonies.toml is the path for a TOML file describing the colonies to simulate.

View CloVarS results

clovars view path_to/view_settings.toml

where:

• path_to/view_settings.toml is the path for a TOML file with the view settings.

Analyse CloVarS results

clovars analyse path_to/analysis_settings.toml

where:

• path_to/analysis_settings.toml is the path for a TOML file with the analysis settings.

Fit experimental data to treatments

clovars fit path_to/fit_settings.toml

where:

• path_to/fit_settings.toml is the path for a TOML file with the fit settings.

Please refer to the examples folder for examples on how the experimental data should be formatted.

Troubleshooting / FAQ

When I use the command pip install clovars, I get the error message ERROR: No matching distribution found for clovars

• Please make sure that you're using Python version 3.8 or newer when trying to pip install clovars. You can check your Python version by writing the command python --version in the terminal/CMD.

Dependencies

CloVarS depends on the following third-party Python packages:

• ete3
• matplotlib
• numpy
• pandas
• scipy
• seaborn

License

CloVarS is distributed under the MIT license. Read the LICENSE.md file for details.

Cite us

If you use CloVarS, cite us:

Juliano L. Faccioni, Julieti H. Buss, Karine R. Begnini, Leonardo G. Brunnet, Manuel M. Oliveira and Guido Lenz.
CloVarS: a simulation of single-cell clonal variability.
BioRxiv, 2024.
DOI: https://doi.org/10.1101/2024.02.22.581631.