# API

*CellularPotts.jl* includes the following core functions.

## Index

`CellularPotts.AdhesionPenalty`

`CellularPotts.CellPotts`

`CellularPotts.CellRow`

`CellularPotts.CellSpace`

`CellularPotts.CellState`

`CellularPotts.CellState`

`CellularPotts.ChemoTaxisPenalty`

`CellularPotts.MigrationPenalty`

`CellularPotts.Penalty`

`CellularPotts.PerimeterPenalty`

`CellularPotts.VolumePenalty`

`CellularPotts.addcellproperty`

`CellularPotts.addnewcell`

`CellularPotts.cellborders!`

`CellularPotts.countcells`

`CellularPotts.countcelltypes`

`CellularPotts.recordCPM`

`CellularPotts.removecell`

## 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`

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

— Type`CellRow`

An concrete type that stores one row of a CellState.

`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::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.

`CellularPotts.addcellproperty`

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

s 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`

.

`CellularPotts.addnewcell`

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

`CellularPotts.removecell`

— Method`removecell(df::CellState, cellID)`

Given a `CellState`

, remove the cell with provided `cellID`

.

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

Add line borders to differentiate cells in a plot.

`CellularPotts.recordCPM`

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

Generates an animation of the CPM model.