API

CellPotts(space, initialCellState, penalties)

A data container that holds information to run the cellular potts simulation.

Requires three inputs:

• space – a region where cells can exist, generated using CellSpace().
• state – a table where rows are cells and columns are cell properties, generated using CellState().
• penalties – a vector of penalties to append to the model.

countcells(cpm::CellPotts)

Count the number of cells in the model

countcelltypes(cpm::CellPotts)

Count the number of cell types in the model

CellSpace(gridSize::NTuple{N, T}; periodic=true, diagonal=false)
CellSpace(gridSize::T...; periodic=true, diagonal=false) where T<:Integer

A concrete type that stores the underlying space cells will occupy.

A CellSpace() can be created by supplying a tuple of dimensions or multiple arguments for each dimension, e.g. CellSpace((3,3,4)) or CellSpace(3,3,4). There are two optional keyword arguments:

• periodic ::Bool: Determines if the grid has periodic boundaries
• diagonal ::Bool: Adjacent cells can have vonNeumann (default) or Moore neighborhoods. VonNeumann neighborhoods do not include adjacent diagonal positions.

CellRow

An concrete type that stores one row of a CellState.

CellState

An concrete type that stores a table where each row is a cell and each column is a cell property.

CellState(names::Vector{Symbol}, volumes::Vector{T}, counts::Vector{T}) where T<:Integer

Create a new CellState where each row corresponds to a cell.

By default, this function generates a table with the following columns:

• names::Vector{Symbol} – List of names given to cells (e.g. :TCell)
• cellIDs::Vector{<:Integer} – A unqiue number given to a cell
• typeIDs::Vector{<:Integer} – A number corresponding to the cell's name
• volumes::Vector{<:Integer} – Number of grid squares occupied
• desiredVolumes::Vector{<:Integer}– Desired number of grid square
• perimeters::Vector{<:Integer}– Cell border penality
• desiredPerimeters::Vector{<:Integer}– Desired cell border penality

The first row in the table is reserved for :Medium which is the name given to grid locations not belonging to any cell and is given an index of 0 (The first cell is given an index of 1).

Of note, desiredPerimeters are calculated as the minimal perimeter given the cell's volume.

addcellproperty(df::CellState, propertyName, propertyValue)
addcellproperty(df::CellState, propertyName, propertyValue, validCells)
addcellproperty(df::CellState, propertyName, cellPropertyPairs::Dict{Symbol, T})

Given a CellState, add a new column called propertyName with values from propertyValue.

There are several ways to add a new property to a CellState, with the simplest method requiring only a propertyName and a single propertyValue. A vector of propertyValues can also be provided if a unique value for each cell is desired.

Sometimes a property may only apply to certain cell types. A single cell type or vector of cell types can be passed to validCells. All non-valid cells will be given a missing value for that property.

Finally, a dictionary of cell=>value pairs can be passed for a given property. Cells not in this dictionary will be given a property value of missing.

addnewcell(df::CellState, cell<:NamedTuple)

Given a CellState, add a new row corresponding to a new cell in the model. Property names for the cell need to match column names in the CellState

removecell(df::CellState, cellID)

Given a CellState, remove the cell with provided cellID.

AdhesionPenalty(J::Matrix{Int})

A concrete type that penalizes neighboring grid locations from different cells.

Requires a symmetric matrix J where J[n,m] gives the adhesion penality for cells with types n and m. J is zero-indexed meaning J[0,1] and J[1,0] corresponds to the :Medium ↔ :Cell1 adhesion penalty.

Note: J is automatically transformed to be a zero-indexed offset array.

ChemoTaxisPenalty(λ, Species)

A concrete type that encourages cells to move up or down a concentration gradient.

Two integer parameters control how cells protude:

• λ: A parameter that controls the strength of this penalty
• Species: The concentration profile for a species that should match the size of the cell space

Species concentration profile can be updated dynamically (e.g. by an ODE)

Supplying a positive λ will move cells up the gradient, negative values down the gradient.

MigrationPenalty(maxAct, λ, gridSize)

A concrete type that encourages cells to protude and drag themselves forward.

Two integer parameters control how cells protude:

• maxAct: A maximum activity a grid location can have
• λ: A parameter that controls the strength of this penalty
• 'gridSize': The size of the space, simply supply size(space)

Increasing maxAct will cause grid locations to more likely protrude. Increasing λ will cause those protusions to reach farther away.

Penalty

An abstract type representing a constraint imposed onto the cellular potts model.

To add a new penalty, a new struct subtyping Penalty needs to be defined and the addPenalty!() function needs to be extended to include the new penalty.

Note: variables associated with a new penalty may need to be offset such that index 0 maps to :Medium, index 1 maps to :Cell1, etc.

PerimeterPenalty(λᵥ::Vector{Int})

A concrete type that penalizes cells that deviate from their desired perimeter.

Requires a vector λₚ with n penalties where n is the number of cell types. λₚ is zero-indexed meaning λₚ[0] corresponds to the :Medium perimeter penalty (which is set to zero).

Note: λₚ is automatically transformed to be a zero-indexed offset array and does not require the perimeter penalty for :Medium.

VolumePenalty(λᵥ::Vector{Int})

A concrete type that penalizes cells that deviate from their desired volume.

Requires a vector λᵥ with n penalties where n is the number of cell types. λᵥ is zero-indexed meaning λᵥ[0] corresponds to the :Medium volume penalty (which is set to zero).

Note: λᵥ is automatically transformed to be a zero-indexed offset array and does not require the volume penalty for :Medium.

cellborders!(plotObject, space::CellSpace)

Add line borders to differentiate cells in a plot.

recordCPM(
    file::String,
    cpm::CellPotts,
    timestamps = 0:300,
    cmap = ColorSchemes.tol_muted;
    framerate=60,
    kwargs...)

Generates an animation of the CPM model.