# API

*CellularPotts.jl* includes the following core functions.

## Index

`CellularPotts.AdhesionPenalty`

`CellularPotts.Cell`

`CellularPotts.CellPotts`

`CellularPotts.CellSpace`

`CellularPotts.CellState`

`CellularPotts.CellState`

`CellularPotts.ChemoTaxisPenalty`

`CellularPotts.MigrationPenalty`

`CellularPotts.Penalty`

`CellularPotts.PerimeterPenalty`

`CellularPotts.VolumePenalty`

`CellularPotts.cellborders`

`CellularPotts.countcells`

`CellularPotts.countcelltypes`

`CellularPotts.record`

`CellularPotts.visualize`

`CellularPotts.visualize!`

## Full docs

`CellularPotts.CellPotts`

— Type`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.

`CellularPotts.countcells`

— Method`countcells(cpm::CellPotts)`

Count the number of cells in the model

`CellularPotts.countcelltypes`

— Methodcountcelltypes(cpm::CellPotts) Count the number of cell types in the model

`CellularPotts.CellSpace`

— Type```
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.

`CellularPotts.Cell`

— Type`Cell`

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

`CellularPotts.CellState`

— Type`CellState`

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

`CellularPotts.CellState`

— Method```
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.

`CellularPotts.AdhesionPenalty`

— Type`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.

`CellularPotts.ChemoTaxisPenalty`

— Type`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.

`CellularPotts.MigrationPenalty`

— Type`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.

`CellularPotts.Penalty`

— Type`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.

`CellularPotts.PerimeterPenalty`

— Type`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`

.

`CellularPotts.VolumePenalty`

— Type`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`

.

`CellularPotts.cellborders`

— Method`cellborders!(plotObject, space::CellSpace)`

Calculate line borders to differentiate cells in a plot.

`CellularPotts.record`

— Method```
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`

)

`CellularPotts.visualize!`

— Method```
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

`CellularPotts.visualize`

— Method```
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).