This codebase generates all the simulations and data presented in our paper [1]. Briefly, two cells are modeled energetically within the phase-field framework and undergo head-on collisions. Our main goal is to study how the speed and contact angle of the cell affect its chances to remain persistent upon head-on collisions.
[1] Zadeh, Pedrom, and Brian A., Camley. "Picking winners in cell-cell collisions: wetting, speed, and contact".bioRxiv (2022).
-
Clone the repo:
git clone https://github.com/pedromzadeh/collider.git cd collider
-
From project's root, create the necessary
conda
environment:- Install
conda
if you don't have it. - Update
conda
to make sure you have the latest version. - Now proceed to create an environment from the file:
conda env create -f environment.yaml conda activate collider
- Install
-
Install local packages at the root of repo:
pip install -e .
Cells are initialized from yaml configuration files with the following fields:
Parameter | Type | Description |
---|---|---|
id |
int |
The cell number |
R_eq |
float |
Specifies the target area of the cell |
R_init |
float |
pecifies the initial area of the cell |
center |
list |
The initial center-of-mass of the cell |
lam |
float |
Phase field interfacial thickness |
D |
float |
Angular diffusion coefficient |
polarity_mode |
str |
The polarity mechanism (sva or ffcr) |
gamma |
float |
Strength of cell line tension |
A |
float |
Strength of cell-substrate adhesion |
beta |
float |
Strength of cell protrusion |
g |
float |
Strength of cell-substrate repulsion |
eta |
float |
The coefficient of friction |
N_wetting |
int |
Time to push the cell onto substrate to facilitate wetting |
To generate the exact feature space used for simulations in [1], simply run
python configs/build.py arg1
where arg1
defines the polarity type and can be one of sva
or ffcr
.
If you prefer to define your own configuration file, then you must specify all the parameters listed in the table above, and follow the tree structure below:
config/
|
└─── sva
| └─── grid_id0
| │ cell0.yaml
| │ cell1.yaml
| ...
│
└─── ffcr
└─── grid_id0
│ cell0.yaml
│ cell1.yaml
...
Note that only the two modalities of static velocity-aligning (sva) and front-front contact repolarization (ffcr) are implemented. Moreover, only two configuration files can be defined, since only two cells can be initialized -- here, cell0.yaml
builds the left cell while cell1.yaml
builds the right one.
As an end user, you really need to only interact with the driver
directory, which houses code for running simulations, processing results, and making visualizations.
To simulate a single two-body collision, simply run
cd driver
python single_run.py arg1 arg2
arg1
:int
, defines the sub directory to use for config files,arg2
:str
, defines the cell polarity mechanism -- options aresva
andffcr
.
For example, python single_run.py 0 sva
will run a collision with cells initialized from the files at config/sva/grid_id0/
. Simulations should finish in about 15-20 mintues.
The results are stored in output/sva/grid_id0/run_0/results.csv
, and the following important values are recorded:
- surface tension
$\gamma$ , - adhesion to the substrate
$A$ , - strength of protrusion
$\beta$ , - center-of-mass speed
$v_{\rm CM}$ , - contact angle
$\theta$ , and - the binary representation of whether cells trained to the left (1) or to the right (0).
The last two observables are time series collected only after the cell has equilibrated and before it has collided -- this constitutes the pre-collision history.
Note that the table is sorted by cell_id
, and as such, the linear temporal ordering is NOT preserved. Thus, you should not interpret the values of a column from row to row as being from a previous time step to its consecutive next one.
At the end of the day, we want relative center-of-mass speeds and contact angles averaged over the pre-collision times, defined as driver/process_data.py
reads all of our simulation results, computes these values for us alongside the winning probability, and stores the processed results in processed/*.csv
. In particular, the columns present are:
- surface tension
$\gamma$ , - adhesion to the substrate
$A$ , - strength of protrusion
$\beta$ , -
$\delta v$ in$\mu \rm m/ min$ , -
$\delta \theta$ in degrees, and -
$P_{\rm win}$ , the binary representation of whether cells trained to the left (1) or to the right (0).
We have already run a complete set of simulations for each polarity mechanism and attached the processed data to this repository under processed/
. We use this as an example in driver/plots.ipynb
. You do not need to run process_data.py
unless you decide to execute a massive number of simulations across different parameters and want to compile results at once.
Check out driver/plots.ipynb
for a detailed look into how each plot presented in [1] was made. Feel free to check out analysis.py
to see our data analysis schema in detail.
Note that you must run the Jupyter notebook in the conda
environment we created above. This is because it needs to find the analysis
package. See this stackoverflow thread for how to add a conda
environment to your Jupyter kernel.
This codebase was written for scientific purposes, and as such, it was not implemented with scalability or generality in mind, and there is no continued support or updates for it. If you wish to fork this repository and use it in your projects, you may contact me for individual support at [email protected].