Chemotaxis
Chemotaxis
plugin, is used to simulate chemotaxis
of cells. For every pixel copy, this plugin calculates change of energy
associated with pixel move. There are several methods to define a change
in energy due to chemotaxis. By default we define a chemotaxis using the
following formula:
where \(c(x_{source})\) and \(c(x_{destination})\) denote chemical concentration at the pixel-copy-source and pixel-copy-destination pixel, respectively.
The body of the Chemotaxis
plugin description contains sections called
ChemicalField
. In this section we tell CompuCell3D which module contains
chemical field that we wish to use for chemotaxis. In our case it is
FlexibleDiffusionSolverFE
. Next we specify the name of the field - FGF
.
Subsequently, we specify lambda
for each cell type so that cells of
different type may respond differently to a given chemical. In
particular types not listed will not respond to chemotaxis at all.
Occasionally we may want to use different formula for the chemotaxis
than the one presented above. Current version of CompCell3D supports the
following definitions of change in chemotaxis energy (Saturation
and
SaturationLinear
respectively ):
or
where s
denotes saturation constant. To use first of the above
formulas we set the value of the saturation coefficient:
<Plugin Name="Chemotaxis">
<ChemicalField Source="FlexibleDiffusionSolverFE" Name="FGF">
<ChemotaxisByType Type="Amoeba" Lambda="0"/>
<ChemotaxisByType Type="Bacteria" Lambda="2000000" SaturationCoef="1"/>
</ChemicalField>
</Plugin>
Notice that this only requires small change in line where you previously specified only lambda.
<ChemotaxisByType Type="Bacteria" Lambda="2000000" SaturationCoef="1"/>
To use second of the above formulas use SaturationLinearCoef
instead of
SaturationCoef
:
<Plugin Name="Chemotaxis">
<ChemicalField Source="FlexibleDiffusionSolverFE" Name="FGF">
<ChemotaxisByType Type="Amoeba" Lambda="0"/>
<ChemotaxisByType Type="Bacteria" Lambda="2000000" SaturationLinearCoef="1"/>
</ChemicalField>
</Plugin>
The lambda
value specified for each cell type can also be scaled using the
LogScaled
formula according to the concentration of the field at the center of mass of the
chemotaxing cell \(c_{CM}\),
The LogScaled
formula is commonly used to mitigate excessive forces on cells
in fields that vary over several orders of magnitude, and can be selected
by setting the value of \(s\) with the attribute LogScaledCoef like as follows,
<ChemotaxisByType Type="Amoeba" Lambda="100" LogScaledCoef="1"/>
Sometimes it is desirable to have chemotaxis at the interface
between only certain types of cells and not between other
cell-type-pairs. In such a case we augment ChemotaxisByType
element with
the following attribute:
<ChemotaxisByType Type="Amoeba" Lambda="100 "ChemotactTowards="Medium"/>
This will cause that the change in chemotaxis energy will be non-zero
only for those pixel copy attempts that happen between pixels belonging
to Amoeba
and Medium
.
Note
The term ChemotactTowards
means “chemotax at the interface between”
CC3D supports slight modifications of the above formulas in the
Chemotaxis
plugin where \(\Delta E\) is non-zero only if the cell located at \(x_{source}\) after
the pixel copy is non-medium. To enable this mode users need to include
<Algorithm="Regular"/>
tag in the body of CC3DML plugin.
Additionally, Chemotaxis
plugin can apply the above formulas using the parameters
and formulas of both the cell located at \(x_{source}\) (if any) and the cell located
at \(x_{destination}\) (if any). To enable this mode users need to include
<Algorithm="Reciprocated"/>
Let’s look at the syntax by studying the example usage of the Chemotaxis plugin:
<Plugin Name="Chemotaxis">
<ChemicalField Source="FlexibleDiffusionSolverFE" Name="FGF">
<ChemotaxisByType Type="Amoeba" Lambda="300"/>
<ChemotaxisByType Type="Bacteria" Lambda="200"/>
</ChemicalField>
</Plugin>
The definitions of chemotaxis presented so far do not allow specification of chemotaxis parameters individually for each cell. To do this we will use Python scripting. We still need to specify in the CC3DML which fields are important from chamotaxis stand point. Only fields listed in the CC3DML will be used to calculate chemotaxis energy:
…
<Plugin Name="CellType">
<CellType TypeName="Medium" TypeId="0"/>
<CellType TypeName="Bacterium" TypeId="1" />
<CellType TypeName="Macrophage" TypeId="2"/>
<CellType TypeName="Wall" TypeId="3" Freeze=""/>
</Plugin>
…
<Plugin Name="Chemotaxis">
<ChemicalField Source="FlexibleDiffusionSolverFE" Name="ATTR">
<ChemotaxisByType Type="Macrophage" Lambda="20"/>
</ChemicalField>
</Plugin>
…
In the above excerpt from the CC3DML configuration file we see that
cells of type Macrophage
will chemotax in response to ATTR
gradient.
Using Python scripting we can modify chemotaxis properties of individual cells as follows:
class ChemotaxisSteering(SteppableBasePy):
def __init__(self, _simulator, _frequency=100):
SteppableBasePy.__init__(self, _simulator, _frequency)
def start(self):
for cell in self.cellList:
if cell.type == self.cell_type.Macrophage:
cd = self.chemotaxisPlugin.addChemotaxisData(cell, "ATTR")
cd.setLambda(20.0)
cd.assignChemotactTowardsVectorTypes([self.cell_type.Medium, self.cell_type.Bacterium])
break
def step(self, mcs):
for cell in self.cellList:
if cell.type == self.cell_type.Macrophage:
cd = self.chemotaxisPlugin.getChemotaxisData(cell, "ATTR")
if cd:
lam = cd.getLambda() - 3
cd.setLambda(lam)
break
In the start
function for first encountered cell of type Macrophage
(type==self.cell_type.Macrophage
) we insert ChemotaxisData
object (it determines chemotaxing
properties) and initialize λ
parameter to 20
. We also initialize vector
of cell types towards which Macrophage cell will chemotax (it will
chemotax towards Medium and Bacterium cells). Notice the break statement
inside the if statement, inside the loop. It ensures that only first
encountered Macrophage cell will have chemotaxing properties altered.
In the step function we decrease lambda chemotaxis by 3
units every 100
MCS. In effect we turn a cell from chemotaxing up ATTR
gradient to being
chemorepelled.
In the above example we have more than one macrophage but only one of them has altered chemotaxing properties. The other macrophages have chemotaxing properties set in the CC3DML section. CompuCell3D first checks if local definitions of chemotaxis are available (i.e. for individual cells) and if so it uses those. Otherwise it will use definitions from from the CC3DML.
The ChemotaxisData
structure has additional functions which allow to set
chemotaxis formula used. For example we may type:
def start(self):
for cell in self.cellList:
if cell.type == self.cell_type.Macrophage:
cd = self.chemotaxisPlugin.addChemotaxisData(cell, "ATTR")
cd.setLambda(20.0)
cd.setSaturationCoef(200.0)
cd.assignChemotactTowardsVectorTypes([self.cell_type.Medium, self.cell_type.Bacterium])
break
to activate Saturation
formula. To activate SaturationLinear
formula we
would use:
cd.setSaturationLinearCoef(2.0)
To activate the LogScaled
formula for a cell, we would use:
cd.setLogScaledCoef(3.0)
Warning
When you use chemotaxis plugin you have to make sure that fields that you refer to and module that contains this fields are declared in the CC3DML file. Otherwise you will most likely cause either program crash (which is not as bad as it sounds) or unpredicted behavior (much worse scenario, although unlikely as we made sure that in the case of undefined symbols, CompuCell3D exits)