CellularPotts.jl

CellularPotts.jl is a Julia package designed to simulate behaviors observed in biological cells like division and adhesion. Users of this package can create 2D and 3D environments with any number of cell types, sizes, and behaviors. Simulations can be recorded and visualized as animations with the help of the Plots.jl package. The goal of this package is to create a flexible coding environment to explore how cell behaviors can coalesce into complex dynamics while still maintaining high performance. Compared to other excellent software for Cellular Potts modeling (e.g., Morpheus, Artistoo, CompuCell3D), CellularPotts.jl is unique in its approach for a few reasons:

• CellularPotts.jl is written completely in Julia, avoiding the "two language problem"

  • This unites developers and users to one language, simplifies the code base, and makes customization easier.

• The space cells occupy is modeled as a network/graph

  • Representing the model as a graph allows access to decades of graph theory research, for example:
  • Calculating articulation points to avoid cell fragmentation
  • Using graph partitioning algorithms to simulate cellular division
  • Avoiding cumbersome boundary conditions by adding edges that wrap around the defined space
  • Using graphical Laplacians to simulate diffusion

• CellularPotts.jl can be composed with other Julia packages.

  • For example, we can use state-of-the-art differential equation solving techniques from DifferentialEquations.jl as opposed to simple Euler methods. (Check out the BringingODEStoLife example.)

Quick Start

To create a basic Cellular Potts Model, you need to provide 3 pieces of information:

1. What space will the cells occupy?

2. What cells do you want to include in the model?

3. What penalties do you want to encourage certain behaviors?

```julia

Install the package (if needed)

using Pkg; Pkg.add("CellularPotts")

Load in the package

using CellularPotts

Create a space (50×50) for cells to exist in

space = CellSpace(50,50; periodic=true, diagonal=true)

Describe the cells in the model

initialCellState = CellState( :Epithelial, #cell names 500, #size of cells 1, #number of cells positions = (25,25))

Add penalties to the model

penalties = [ AdhesionPenalty([0 20; 20 0]), VolumePenalty([5]) ]

Create a model object

cpm = CellPotts(space, initialCellState, penalties)

Record a simulation of the model

recordCPM("ReadMeExample.gif", cpm) ```

Want to Contribute?

If you want to suggest new features or improvements to make CellularPotts.jl better, feel free to submit an issue or pull request. Please also report any bugs you may stumble upon and I will try my best to fix them. I've tried to ensure that this package is as performant as possible, but I welcome any improvements you might have!

How to Cite

If you happen to use CellularPotts.jl in your research, feel free to cite our paper:

https://doi.org/10.1093/bioinformatics/btad773

@article{gregg2024cellularpotts, title={CellularPotts. jl: simulating multiscale cellular models in Julia}, author={Gregg, Robert W and Benos, Panayiotis V}, journal={Bioinformatics}, volume={40}, number={1}, pages={btad773}, year={2024}, publisher={Oxford University Press} }

Future Improvements

• [ ] CellDivision!() currently cannot update custom cell state properties

• [ ] Use Shape() to plots cells instead of heatmap (will this be slower?)

• [ ] Use automatic differentiation to calculate cellular forces from the Hamiltonian

• [ ] Use SVectors to store graph edges? 🤔

  • Only useful for spaces where all nodes are identical (e.g., periodic boundaries)

• [x] Reduce heavy package dependencies using package extensions

  • [ ] Not using package extensions yet but some heavy dependencies were removed
  • [ ] Package extensions for DifferentialEquations.jl and Plots.jl

• [ ] Separate tutorials from examples

• [ ] Tutorial on how to create your own penalty (e.g. cell length to control cell shape)

• [ ] Make adding cells easier

• [ ] Make it easier to integrate PDE models (maybe Enzyme.jl?)