ARCADE

Agent-based model of heterogeneous cell populations in dynamic microenvironments

ARCADE v2 is licensed under GPL 3. ARCADE v3+ is licensed under BSD 3-Clause.

---

• Code structure overview
• Building from source
• Running the code
• Setup file structure
• Snapshot file structure

---

Code structure overview

The src directory contains all source files for the model. The test directory contains all files for testing. The docs directory contains documentation.

arcade-X.X.X.jar is a compiled jar of the model, with the required library MASON included. Compiled jars for each release are included as a release asset.

Building from source

The model can be built from source using Gradle.

To build, use:

$ ./gradlew build

The build command will also output a command in the form:

$ docker build --build-arg VERSION=X.X.X -t arcade:X.X.X .

which can be used to build a Docker image from the compiled jar.

Documentation can be regenerated using:

$ ./gradlew javadoc

Running the code

The model can be run directly through command line, with or without real time visualization. Note that running the model with visualization is significantly slower than without visualization.

When using command line, first navigate to the directory containing the jar. Then:

$ java -jar arcade-X.X.X.jar potts XML PATH [(-v|--vis)] [--loadpath] [(-c|--cells)] [(-l|--locations)]

    XML
        Absolute path to setup XML
    PATH
        Absolute path for snapshot JSON
    [(-v|--vis)]
        Flag for running with visualization
    [--loadpath]
        Path prefix for loading files
    [(-c|--cells)]
        Flag for loading .CELLS file
    [(-l|--locations)]
        Flag for loading .LOCATIONS file

🔸 Example: Running model from command line

$ java -jar arcade.jar potts /path/to/setup.xml /path/to/output/

🔸 Example: Running model from command line with interactive visualization

$ java -jar arcade.jar potts /path/to/setup.xml /path/to/output/ --vis

🔸 Example: Running model from command line using loaded files

$ java -jar arcade.jar potts /path/to/setup.xml /path/to/output/ --loadpath /path/to/load/files --cells --locations

Setup file structure

The model uses a .xml file that describes the setup of the simulations, agents, and environment. Values in [ALL CAPS] should be replaced with actual values.

The basic structure of the file is:

<set prefix="[PREFIX]">
    <series name="[NAME]" start="[START]" end="[END]"
            ds="[DS]" margin="[MARGIN]" height="[HEIGHT]" length="[LENGTH]" width="[WIDTH]"
            dt="[DT]" ticks="[TICKS]" interval="[INTERVAL]">
        <potts>
            <potts.term id="[ID]" />
            <potts.parameter id="[ID]" value="[VALUE]" scale="[SCALE]" />
            <potts.parameter id="[ID]" value="[VALUE]" scale="[SCALE]" term="[TERM]" />
            <potts.parameter id="[ID]" value="[VALUE]" scale="[SCALE]" term="[TERM]" target="[TARGET]" />
            ...
        </potts>
        <agents>
            <populations>
                <population id="[ID]" init="[INIT]">
                    <population.parameter id="[ID]" value="[VALUE]" scale="[SCALE]" />
                    <population.parameter id="[ID]" value="[VALUE]" scale="[SCALE]" module="[MODULE]"  />
                    <population.region id="[ID]" />
                    ...
                </population>
                ...
            </populations>
        </agents>
    </series>
    ...
</set>

🔷 Tag: set

A group of simulations series is called a set. The setup XML can only include one set.

ATTRIBUTE	DESCRIPTION	TYPE	DEFAULT
prefix	prefix for all series names	string	""

🔷 Tag: series

A simulation series is a group of simulations that only differ in the random seed. Each <series> includes <potts>, <agents>, and <environment> tags that define various parts of the series. A set can include multiple <series> tags.

ATTRIBUTE	DESCRIPTION	TYPE	DEFAULT
name	name of the simulation series for output files	string
start	starting seed	integer	0
end	ending seed	integer	0
length	x size of the simulation	integer	100
width	y size of the simulation	integer	100
height	z size of the simulation	integer	1
margin	simulation environment margin	integer	0
ticks	total number of simulation ticks	integer	100
interval	number of ticks between snapshots	integer	50
ds	spatial conversion factor	integer, float, fraction	1
dt	temporal conversion factor	integer, float, fraction	1

🔷 Tag: potts

The potts tag describes Cellular Potts Model (CPM) framework-specific setup. Nested tags include potts.term for Hamiltonian terms and potts.parameter for parameters.

🔹 Nested tag: potts.term

The potts.term tag is used to specify the terms used in the CPM Hamiltonian. Valid options include:

• volume = target area (2D) or volume (3D) constraint
• adhesion = adhesion contact energy (2D and 3D)
• substrate = differential substrate adhesion contact energy (3D only)

🔸 Example: Including volume and adhesion Hamiltonian terms

<potts.term id="volume" />
<potts.term id="adhesion" />

🔹 Nested tag: potts.parameter

The potts.parameter tag lists CPM parameters that are either set to a new value or scaled from the default value. Unless modified, default values are used for all parameters (as listed in parameter.potts.xml). Either or both value and scale attributes can be applied, with value applied first.

ATTRIBUTE	DESCRIPTION
id	Parameter name
value	New parameter value
scale	Scaling factor applied to parameter value
term	Hamiltonian term the parameter applies to
target	Target populations ids for the parameter

Parameter changes for terms can be applied to specific populations using the target attribute

🔸 Example: Modifying global potts parameters

<potts.parameter id="MCS" value="[VALUE]"  />

🔸 Example: Modifying term-specific potts parameters

<potts.parameter term="volume" id="LAMBDA" value="[SCALE]" />

🔸 Example: Modifying term-specific potts parameters with target

<!-- Modifies LAMBDA parameter in volume term for population A -->
<potts.parameter term="volume" id="LAMBDA" scale="[SCALE]" target="A" />
<!-- Modifies ADHESION parameter in adhesion term between population A and population B -->
<potts.parameter term="adhesion" id="ADHESION" value="[VALUE]" target="A:B" />
<!-- Modifies ADHESION parameter in adhesion term between population A and media -->
<potts.parameter term="adhesion" id="ADHESION" value="[VALUE]" target="A:*" />

🔷 Tag: agents

The agents tag groups agent setup tags, including definitions of the various cell populations and actions.

🔷 Tag: populations

The Populations tag lists the cell populations included in the simulation. For each population tag, nested tags include population.parameter for parameters and population.region for regions.

ATTRIBUTE	DESCRIPTION	TYPE	DEFAULT	REQUIRED
id	unique name for the agent population	string		Y
init	number of initial agents in population	integer	0	N

🔸 Example: Initializing one agent population

<populations>
    <population id="A" init="10" />
</populations>

🔸 Example: Initializing two agent populations

<populations>
    <population id="A" init="10" />
    <population id="B" init="5" />
</populations>

🔸 Example: Initializing single agent population with padding between cells

<populations>
    <population id="A" init="10:3" />
</populations>

🔹 Nested tag: population.parameter

The population.parameter tag lists population-specific parameters that are either set to a new value or scaled from the default value. Unless modified, default values are used for all parameters (as listed in parameter.potts.xml). Either or both value and scale attributes can be applied, with value applied first.

ATTRIBUTE	DESCRIPTION
id	Parameter name
value	New parameter value
scale	Scaling factor applied to parameter value
module	State module the parameter applies to

The module attribute is used to specify parameters specific to a module.

🔸 Example: Modifying population parameters

<population.parameter id="CRITICAL_VOLUME_MEAN" value="[VALUE]" />

🔸 Example: Modifying population module parameters

<population.parameter id="CELL_GROWTH_RATE" module="proliferation" value="[VALUE]" />

🔹 Nested tag: population.region

The population.region tag lists subcellular regions for the population. Valid options include:

• DEFAULT = represents the entire cell
• NUCLEUS = represents the nuclear region

Unless specified, only the DEFAULT region is used.

🔸 Example: Including cell and nuclear regions

<population.region id="DEFAULT" />
<population.region id="NUCLEUS" />

Snapshot file structure

The models saves simulation snapshots to .json files, which describe the simulation and agents. Values in [ALL CAPS] are replaced with simulation values. Each simulation series produces a single overview file, and a number .CELLS/.LOCATIONS snapshots determined by the total number of simulation ticks and the snapshot interval.

Simulation series overview

The basic structure of the overview file is:

{
  "version": "[VERSION NUMBER]",
  "conversions": {
    "DS": [DS],
    "DT": [DT]
  },
  "ticks": [TICKS],
  "size": {
    "length": [LENGTH],
    "width": [WIDTH],
    "height": [HEIGHT],
    "margin": [MARGIN]
  },
  "populations": {
    "[POPULATION_ID]": {
      "CODE": [CODE],
      "PADDING": [PADDING],
      "INIT": [INIT],
      "[PARAMETER]": [PARAMETER VALUE],
    ...
      "[MODULE]/[PARAMETER]": [PARAMETER VALUE],
    ...
    },
    ...
  },
  "potts": {
    "[PARAMETER]": [PARAMETER VALUE],
    ...
    "[TERM]/[PARAMETER]": [PARAMETER VALUE],
    ...
    "[TERM]/[PARAMETER]:[TARGET]": [PARAMETER VALUE],
    ...
  }
}

Simulation .CELLS snapshot

The .CELLS snapshot file includes details about each cell agent. This file can be used to as initial conditions by loading with --cells.

[
  {
    "id": [ID],
    "parent": [PARENT ID],
    "pop": [POPULATION CODE],
    "age": [AGE],
    "divisions": [DIVISION],
    "state": [STATE],
    "phase": [PHASE],
    "voxels": [NUMBER OF VOXELS],
    "criticals": [[CRITICAL VOLUME], [CRITICAL HEIGHT]]
  },
  ...
]

Simulation .LOCATIONS snapshot

The .LOCATIONS snapshot file file includes details about each cell agent location. This file can be used to as initial conditions by loading with --locations.

[
  {
    "id": [ID],
    "center": [[CENTER_X], [CENTER_Y], [CENTER_Z]],
    "location": [
      {
        "region": [REGION],
        "voxels": [
          [[X], [Y], [Z]],
          ...
        ]
      },
      ...
    ]
  },
  ...
]