In this tutorial we show how Chaste can be used to create, run and visualize Potts-based simulations.
Full details of the mathematical model can be found in Graner, F. and Glazier, J. A. (1992). “Simulation
of biological cell sorting using a two-dimensional extended Potts model”. Phys. Rev. Lett., 69(13):2015–2016, doi:10.1103/PhysRevLett.69.2013.
As in previous cell-based Chaste tutorials, we begin by including the necessary header files.
The remaining header files define classes that will be used in the cell population
simulation test. We have encountered some of these header files in previous cell-based
Chaste tutorials.
The next header file defines a helper class for generating a suitable mesh.
The next header file defines the class that simulates the evolution of an on lattice CellPopulation.
The next header file defines aCellPopulation class for implementing a cellular Potts model.
The next header files define some update rules for describing the Hamiltonian used to define the Potts simulations.
Finally these headers allow us to output cell labels.
Next, we define the test class, which inherits from AbstractCellBasedTestSuite
and defines some test methods.
In the first test, we run a simple Potts-based simulation, in which we create a monolayer
of cells, using a Potts mesh. Each cell is assigned a stochastic cell-cycle model.
First, we generate a Potts mesh. To create a PottsMesh, we can use
the PottsMeshGenerator. This generates a regular square-shaped mesh,
in which all elements are the same size.
Here the first three arguments specify the domain width; the number of elements across; and the width of
elements. The second set of three arguments specify the domain height; the number of elements up; and
the height of individual elements.
We have chosen a 2 by 2 block of elements, each consisting of 4 by 4 ( = 16) lattice sites.
Having created a mesh, we now create a std::vector of CellPtrs.
To do this, we the CellsGenerator helper class, which is templated over the type
of cell model required (here UniformCellCycleModel)
and the dimension. We create an empty vector of cells and pass this into the
method along with the mesh. The second argument represents the size of that the vector
cells should become - one cell for each element. Third argument makes all cells
proliferate.
Now we have a mesh and a set of cells to go with it, we can create a CellPopulation.
In general, this class associates a collection of cells with a mesh.
For this test, because we have a PottsMesh, we use a particular type of
cell population called a PottsBasedCellPopulation.
We can set the “Temperature” to be used in the Potts simulation using the optional command below.
The default value is 0.1.
By default the Potts simulation will make 1 sweep over the whole domain per timestep. To use a different
number of sweeps per timestep use the command.
We then pass in the cell population into an OnLatticeSimulation,
and set the output directory and end time.
The default timestep is 0.1, but can be changed using the below command. The timestep is used in conjunction with the “Temperature” and
number of sweeps per timestep to specify the relationship between cell movement and proliferation. We also set the simulation to only output
every 10 steps i.e. once per hour.
We must now create one or more update rules, which determine the Hamiltonian
in the Potts simulation. For this test, we use two update rules based upon
a volume constraint (VolumeConstraintPottsUpdateRule) and adhesion between cells (AdhesionPottsUpdateRule) and pass them to the OnLatticeSimulation.
For a list of possible update rules see subclasses of AbstractPottsUpdateRule.
These can be found in the inheritance diagram, here, AbstractPottsUpdateRule.
Similarly to specifying forces for off lattice simulations we use the MAKE_PTR macro
to make a boost shared pointer to our required update rule before specifying parameters and passing to the simulation as follows
Set an appropriate target volume in number of lattice sites. Here we use the default value of 16 lattice sites.
You can also vary the deformation energy parameter. The larger the parameter
the more cells will try to maintain target volume. Here we use the default value of 0.2.
Finally we add the update rule to the simulator.
We repeat the process for any other update rules.
To run the simulation, we call Solve().
The next two lines are for test purposes only and are not part of this tutorial. If different simulation input parameters are being explored
the lines should be removed.
To visualize the results, open a new terminal, cd to the Chaste directory,
then cd to anim. Then do: java Visualize2dVertexCells /tmp/$USER/testoutput/PottsBasedMonolayer/results_from_time_0.
We may have to do: javac Visualize2dVertexCells.java beforehand to create the
java executable.
We could also visualize the results using Paraview.
Load the file /tmp/$USER/testoutput/PottsBasedMonolayer/results_from_time_0/results.pvd, and click apply.
Add box “Glyphs” to represent lattice sites. You will need to adjust the size so they don’t overlap.
Note that, for larger simulations, you may need to unclick “Mask Points” (or similar) so as not to limit the number of glyphs
displayed by Paraview.
Select the “Display” tab and select “color by” cell index to see individual cells.
Add a “Threshold” filter, filter by cell type and make the lower threshold 0 or greater (unoccupied lattice sites are labelled with -1). This will allow you to view only the cells.
Load the files /tmp/$USER/testoutput/PottsBasedMonolayer/results_from_time_0/outlines_..vtu, and click apply.
In order to see the cell outlines you will need to select “Surface With Edges” in the drop down menu.
Click play to see the evolution of the simulation.
You should see that the cells sort into ones of the same type.
The next test generates a collection of cells, there are two types of cells, labelled ones
and non labelled ones, there is differential adhesion between the cell types. For the
parameters specified, the cells sort into separate types.
Parameters are taken from Graner, F. and Glazier, J. A. (1992). Simulation of biological
cell sorting using a two-dimensional extended Potts model. Phys. Rev. Lett., 69(13):2015–2016.
First, we generate a Potts mesh. To create a PottsMesh, we can use
the PottsMeshGenerator. This generates a regular square-shaped mesh,
in which all elements are the same size.
We have chosen an 8 by 8 block of elements each consisting of 4 by 4 ( = 16) lattice sites.
Having created a mesh, we now create a std::vector of CellPtrs.
To do this, we the CellsGenerator helper class, as before but this time
the third argument is set to make all cells non-proliferative.
Before we make a CellPopulation we make a boost shared pointer to a cell label and then assign this
label to some randomly chosen cells.
Now we have a mesh and a set of cells to go with it, we can create a CellPopulation.
In order to visualize labelled cells we need to use the following command.
We then pass in the cell population into an OnLatticeSimulation,
and set the output directory and end time.
We must now create one or more update rules, which determine the Hamiltonian
in the Potts simulation. For this test, we use two update rules based upon
a volume constraint (VolumeConstraintPottsUpdateRule) and differential adhesion between cells (DifferentialAdhesionPottsUpdateRule), set appropriate parameters, and pass them to the OnLatticeSimulation.
These parameters cause the cells to sort, for different values you can get different patterns.
To run the simulation, we call Solve().
The next two lines are for test purposes only and are not part of this tutorial.
To visualize the results, open a new terminal, cd to the Chaste directory,
then cd to anim. Then do: java Visualize2dVertexCells /tmp/$USER/testoutput/PottsMonolayerCellSorting/results_from_time_0.
We may have to do: javac Visualize2dVertexCells.java beforehand to create the
java executable.
The next test extends the previous example to three dimensions.
First, we generate a Potts mesh. To create a PottsMesh, we can use
the PottsMeshGenerator. This generates a regular square-shaped mesh,
in which all elements are the same size.
Here the first three arguments specify the domain width; the number of elements across; and the width of
elements. The second set of three arguments specify the domain height; the number of elements up; and
the height of individual elements. The third set of three arguments specify the domain depth; the number of elements deep; and
the depth of individual elements.
We have chosen an 4 by 4 by 4 ( = 64) block of elements each consisting of 2 by 2 by 2 ( = 8) lattice sites.
Having created a mesh, we now create a std::vector of CellPtrs.
To do this, we the CellsGenerator helper class, as before but this time
the third argument is set to make all cells non-proliferative.
As for the 2D case before we make a CellPopulation we make a pointer to a cell label and then assign this
label to some randomly chosen cells.
Now we have a mesh and a set of cells to go with it, we can create a CellPopulation.
In general, this class associates a collection of cells with a set of elements or a mesh.
For this test, because we have a PottsMesh, we use a particular type of
cell population called a PottsBasedCellPopulation.
In order to visualize labelled cells we need to use the following command.
We then pass in the cell population into an OnLatticeSimulation,
and set the output directory and end time.
We must now create one or more update rules, which determine the Hamiltonian
in the Potts simulation. For this test, we use two update rules based upon
an area constraint and differential adhesion between cells and pass them to the OnLatticeSimulation.
Now set the target volume to be appropriate for this 3D simulation.
We use the same differential adhesion parameters as in the 2D case.
To run the simulation, we call Solve().
The next two lines are for test purposes only and are not part of this tutorial.
To visualize the results, we need to use Paraview. Note that we don’t output the cell boundaries (outlines) in 3D.
See the Visualizing With Paraview tutorial for more information.
Load the file /tmp/$USER/testoutput/PottsCellSorting3D/results_from_time_0/results.pvd, and click apply.
Add box “Glyphs” to represent lattice sites. You will need to adjust the size so they don’t overlap.
Note that, for larger simulations, you may need to unclick “Mask Points” (or similar) so as not to limit the number of glyphs
displayed by Paraview.
Select the “Display” tab and select “color by” cell label (you can also “color by” cell index to see individual cells).
Add a “Threshold” filter, filter by cell type and make the lower threshold 0 or greater (unoccupied lattice sites are labelled with -1). This will allow you to view only the cells.
Click play to see the evolution of the simulation.
You should see that the cells sort into ones of the same type.