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:

\begin{eqnarray} \Delta E_{chem} = -\lambda\left ( c(x_{destination}) - c(x_{source}) \right ) \end{eqnarray}

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 ):

\begin{eqnarray} \Delta E_{chem} = -\lambda \left [ \frac{c(x_{destination})}{s+c(x_{destination})} - \frac{c(x_{source})}{s+c(x_{source})} \right ] \end{eqnarray}

or

\begin{eqnarray} \Delta E_{chem} = -\lambda \left [ \frac{c(x_{destination})}{sc(x_{destination})+1} - \frac{c(x_{source})}{sc(x_{source})+1} \right ] \end{eqnarray}

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}\),

\begin{eqnarray} \Delta E_{chem} = -\frac{\lambda}{s + c_{CM}} \left ( c(x_{destination}) - c(x_{source}) \right ) \end{eqnarray}

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)