FocalPointPlasticity Plugin¶
FocalPointPlasticity
puts constrains on the
distance between cells’ center of masses. A key feature of this plugin is that
the list of “focal point plasticity neighbors” can change as the
simulation evolves and user has to specifies the maximum number of “focal point
plasticity neighbors” a given cell can have. Let’s look at relatively
simple CC3DML syntax of FocalPointPlasticityPlugin
(see
Demos/PluginDemos/FocalPointPlasticity/FocalPointPlasticity example and we will show more complex
examples later):
<Plugin Name="FocalPointPlasticity">
<Parameters Type1="Condensing" Type2="NonCondensing">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>2</MaxNumberOfJunctions>
</Parameters>
<Parameters Type1="Condensing" Type2="Condensing">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>2</MaxNumberOfJunctions>
</Parameters>
<NeighborOrder>1</NeighborOrder>
</Plugin>
Parameters
section describes properties of links between cells.
MaxNumberOfJunctions
, ActivationEnergy
, MaxDistance
and NeighborOrder
are responsible for establishing connections between cells. CC3D
constantly monitors pixel copies and during pixel copy between two
neighboring cells/subcells it checks if those cells are already
participating in focal point plasticity constraint. If they are not,
CC3D will check if connection can be made (e.g. Condensing
cells can
have up to two connections with Condensing
cells and up to 2 connections
with NonCondensing
cells – see first line of Parameters
section and
MaxNumberOfJunctions
tag). The NeighborOrder
parameter determines the
pixel vicinity of the pixel that is about to be overwritten which CC3D
will scan in search of the new link between cells. NeighborOrder 1
(which is default value if you do not specify this parameter) means that
only nearest pixel neighbors will be visited. The ActivationEnergy
parameter is added to overall energy in order to increase the odds of
pixel copy which would lead to new connection.
Once cells are linked the energy calculation is carried out according to the formula:
where \(l_{ij}\) is a distance between center of masses of cells i
and j
and \(L_{ij}\) is
a target length corresponding to \(l_{ij}\).
\(\lambda_{ij}\) and \(L_{ij}\) between different cell types are
specified using Lambda
and TargetDistance
tags. The MaxDistance
determines the distance between cells’ center of masses past which the link
between those cells break. When the link breaks, then in order for the
two cells to reconnect they would need to come in contact again.
However it is usually more likely that there will be other
cells in the vicinity of separated cells so it is more likely to
establish new link than restore broken one.
The above example was one of the simplest examples of use of
FocalPointPlasticity
. A more complicated one involves compartmental
cells. In this case each cell has separate “internal” list of links
between cells belonging to the same cluster and another list between
cells belonging to different clusters. The energy contributions from
both lists are summed up and everything that we have said when
discussing example above applies to compartmental cells. Sample syntax
of the FocalPointPlasticity
plugin which includes compartmental cells is
shown below. We use InternalParameters
tag/section to describe links
between cells of the same cluster (see Demos/PluginDemos/FocalPointPlasticity/FocalPointPlasticityCompartments
example):
<Plugin Name="FocalPointPlasticity">
<Parameters Type1="Top" Type2="Top">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions NeighborOrder="1">1</MaxNumberOfJunctions>
</Parameters>
<Parameters Type1="Bottom" Type2="Bottom">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions NeighborOrder="1">1</MaxNumberOfJunctions>
</Parameters>
<InternalParameters Type1="Top" Type2="Center">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>1</MaxNumberOfJunctions>
</InternalParameters>
<InternalParameters Type1="Bottom" Type2="Center">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions>1</MaxNumberOfJunctions>
</InternalParameters>
<NeighborOrder>1</NeighborOrder>
</Plugin>
We can also specify link constituent law and change it to different form that “spring relation”. To do this we use the following syntax inside FocalPointPlasticity CC3DML plugin:
<LinkConstituentLaw>
<!--The following variables lare defined by default: Lambda,Length,TargetLength-->
<Variable Name='LambdaExtra' Value='1.0'/>
<Formula>LambdaExtra*Lambda*(Length-TargetLength)^2</Formula>
</LinkConstituentLaw>
By default CC3D defines 3 variables (Lambda
, Length
, TargetLength
) which
correspond to \(\lambda_{ij}\) , \(l_{ij}\) and \(L_{ij}\) from the formula
above. We can also define extra variables in the CC3DML (e.g.
LambdaExtra
). The actual link constituent law obeys muParser
syntax
convention. Once link constituent law is defined it is applied to all
focal point plasticity links. The example demonstrating the use of
custom link constituent law can be found in
Demos/PluginDemos/FocalPointPlasticityCustom.
Sometimes it is necessary to modify link parameters individually for
every cell pair. In this case we would manipulate FocalPointPlasticity
links using Python scripting. Example
Demos/PluginDemos/FocalPointPlasticity/FocalPointPlasticityCompartments demonstrates exactly this
situation. You still need to include CC3DML section as the one shown
above for compartmental cells, because we need to tell CC3D how to link
cells. The only notable difference is that in the CC3DML we have to
include <Local/>
tag to signal that we will set link parameters (Lambda
,
TargetDistance
, MaxDistance
) individually for each cell pair:
<Plugin Name="FocalPointPlasticity">
<Local/>
<Parameters Type1="Top" Type2="Top">
<Lambda>10.0</Lambda>
<ActivationEnergy>-50.0</ActivationEnergy>
<TargetDistance>7</TargetDistance>
<MaxDistance>20.0</MaxDistance>
<MaxNumberOfJunctions NeighborOrder="1">1</MaxNumberOfJunctions>
</Parameters>
...
</Plugin>
Python steppable where we manipulate cell-cell focal point plasticity link properties is shown below:
class FocalPointPlasticityCompartmentsParams(SteppablePy):
def __init__(self, _simulator, _frequency=10):
SteppablePy.__init__(self, _frequency)
self.simulator = _simulator
self.focalPointPlasticityPlugin = CompuCell.getFocalPointPlasticityPlugin()
self.inventory = self.simulator.getPotts().getCellInventory()
self.cellList = CellList(self.inventory)
def step(self, mcs):
for cell in self.cellList:
for fppd in InternalFocalPointPlasticityDataList(self.focalPointPlasticityPlugin, cell):
self.focalPointPlasticityPlugin.setInternalFocalPointPlasticityParameters(cell, fppd.neighborAddress,
0.0, 0.0, 0.0)
The syntax to change focal point plasticity parameters (or as here internal parameters) is as follows:
setFocalPointPlasticityParameters(cell1, cell2, lambda, targetDistance, maxDistance)
setInternalFocalPointPlasticityParameters(cell1, cell2, lambda, targetDistance, maxDistance)
Similarly, to inspect current values of the focal point plasticity parameters we would use the following Python construct:
for cell in self.cellList:
for fppd in InternalFocalPointPlasticityDataList(self.focalPointPlasticityPlugin, cell):
print "fppd.neighborId", fppd.neighborAddress.id
" lambda=", fppd.lambdaDistance
For non-internal parameters we simply use FocalPointPlasticityDataList
instead of InternalFocalPointPlasticityDataList
.
Examples Demos/PluginDemos/FocalPointPlasticity… show in relatively simple way how
to use FocalPointPlasticity
plugin. Those examples also contain useful
comments.
Note
When using FocalPointPlasticity
Plugin from Mitosis
module one might
need to break or create focal point plasticity links. To do so
FocalPointPlasticity
Plugin provides 4 convenience functions which can
be invoked from the Python level:
deleteFocalPointPlasticityLink(cell1, cell2)
deleteInternalFocalPointPlasticityLink(cell1, cell2)
createFocalPointPlasticityLink(cell1, cell2, lambda , targetDistance, maxDistance)
createInternalFocalPointPlasticityLink(cell1, cell2, lambda , targetDistance, maxDistance)