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.

Cell

An concrete type that points to a row in a referenced CellState table.

CellState

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

CellState(
names::AbstractVector{S},
volumes::AbstractVector{T},
counts::AbstractVector{T};
options...) where {S<:Symbol, T<:Integer}


CellState(;names::AbstractVector{Symbol}, volumes::AbstractVector{T}, counts::AbstractVector{T}, options...) 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 squares
• 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).

Additional cell properties can be supplied as keyword arguements. The length of the keyword arguement needs to match the number of cell types or the total cell count.

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)

Calculate line borders to differentiate cells in a plot.

record(
    cpm::CellPotts;
    file = "output.gif",
    steps = 300,
    framerate = 30,
    skip = 1,
    colorby = :type,
    kwargs...)

Generates an animation of the Cellular Potts Model.

Change the file type by modifying the file name (e.g. file = "output.mp4)

visualize!(
    plt::AbstractPlot
    cpm::CellPotts;
    colorby=:type,
    cellcolors=nothing,
    migrationcolors=nothing,
    kwargs...)

Generates a visualization of the CPM model.

This function will append the given plot with a Cellular Potts Model visualization

visualize(
    cpm::CellPotts;
    colorby=:type,
    cellcolors=nothing,
    migrationcolors,
    kwargs...)

Generates a visualization of the Cellular Potts Model.

This plotting function builds on Plots.jl, so any possible keywords can be passed on.

The optional colorby arguement can be: 1. :type to color the cells by cell type 2. :id to give each cell a unique color 3. :none to not color the cells

To change the background (Medium) color, supply a color to background

A custom set of colors can be supplied, e.g., colormap = [:red,:blue,:green]

migrationcolors accepts a colormap when a MigrationPenalty is present (cannot be applied to 3D visualizations currently).