The Magrathea Manual: Building Coordinated Agent Models

Making models

The model.txt file

Magrathea opens a file called “model.txt” at the beginning of a simulation. Information is read from the file to populate the simulation with molecules and coordinators. The properties of different types of molecules and coordinators are specified in the model.txt file along with the number and positions of all of the starting molecules and coordinators. The sections below describe the format of the model.txt file.

A simple example

An example model.txt file is shown below in Figure 1.

The model.txt file is a text file and must be called “model.txt”. Lines beginning with # are comments and are ignored. Blank lines are ignored. Any text in the file after the line

EOF

will be ignored.

There are two types of sections in a model file. A section used to describe a type of molecule and create instances of that molecule type at the beginning of the simulation begins with the line:

[moleculeType]

and ends with the line

[/moleculeType]

A section that is used to describe a coordinator type and create instances of that coordinator at the beginning of the simulation begins with the line:

[coordinatorType]

and ends with the line

[/coordinatorType]

An example model.txt file for Magrathea

###########
#ab complex
###########

[moleculeType]
id 1
label a
color .81 .60 .21
shape Sphere 1
neighborhood-size 5
coordinator 1 3
instantiate 10 random spherical volume 10 30 10 10
[/moleculeType]

[moleculeType]
id 2        
label b
color 0.67 0.08 0.37
shape Sphere 1
neighborhood-size 5
coordinator 1 3
instantiate 4 random spherical volume 10 15 10 10
[/moleculeType]

[coordinatorType]
id 3
label a-b-complex
shape Cube 1 1 1
molecule 1 1
molecule 2 1
[/coordinatorType]

EOF

Key-value format

Each line in these two sections types encodes a separate piece of information as a key-value pair. So, for instance, members of the first molecule type are labeled “a” as indicated by the line

label a

In this line “label” is the key and “a” is the value. Keys and their values are separated by white-spaces. There may be several values specified for a given key. The key is always the first block of text on a line. A brief description of the example model.txt file

The above example model file, specifies a simulation that has two molecule types and one coordinator type.

Each molecule of type “1” has a label of “a”, has some specified color, is drawn as a sphere, can detect neighboring molecules within a 5 unit radius and can be coordinated by some coordinator type 3 on channel 1. These ideas are encoded by the lines

id 1
label a
color .81 .60 .21
shape Sphere 1
neighborhood-size 5
coordinator 1 3

The simulation begins with 10 instances of this molecule type distributed randomly throughout some specified spherical volume. This is encoded by the line:

instantiate 10 random spherical volume 10 30 10 10

The second molecule type has a label of “b”, is also drawn as a sphere with a different color. The simulation begins with only four instances of this molecule type that are also distributed in a spherical volume at a separate location in the simulation. Both molecules a and b can be coordinated by coordinator type 3 on channel 1 (as specified in the line):

coordinator 1 3

for both molecule a and b.

There is only one type of coordinator in this simulation. It has an id of 3 and is labeled “a-b-complex”. The simulation does not begin with any instances of this coordinator type. Instead, an instance of this coordinator type will be created once an instance of molecule “a” and an instance of molecule “b” diffuse within one another’s “neighborhood distance” during the simulation. The coordinator will then appear between the two molecules as a cube. The coordinator has two molecule type members (each with a stoichiometry of 1) as indicated by the lines:

molecule 1 1
molecule 2 1

Once the two molecules become a part of this coordinator, they will move towards the coordinator (at some position between where the two molecules started) and remain there.

A screen shot of the resulting simulation is shown below in the Figure below. The remainder of this section of the manual shows exactly how molecule and coordinator types can be specified.

Screen shot of a simulation resulting from the example model.txt file Insert screen shot here

Describing molecule types

An example molecule type description is given below in Figure 3. Each of the key-value entry lines are described in a separate section below. For each key-value pair, a format is given. Square brackets indicate types of values that must are to be inserted into the line by the user (i.e., either a float (like 0.1), an integer (like 200) or a string value (like myComplex).

An example molecule type description

[moleculeType]
id 1
label molecule_a
color .81 .60 .21
shape Sphere 1
draw-as-point 0
opacity 1
show-neighbor-lines 0
neighborhood-size 5
dynamic-neighborhood-sizing 0
feature 234 Tyr234
feature-state 234 0 unphosphorylated
feature-state 234 1 phosphorylated
coordinator 1 3
resident-compartment-type 4
instantiate 10 random spherical volume 10 30 10 10
[/moleculeType]

Molecule parameters

id
key	id
format	id [integer]
description	A unique identifier for this molecule type
required	yes
default value	not applicable
example	id 1

Notes: id is usually the first key-value pair specified for a moleculeType. This id is used to refer to this molecule type in other key-value pairs of the model file.

label
key	label
format	label [string]
description	A label for the molecule type.
required	no
default value	molecule
example	label molecule_a

Notes: The label line allows the user to give a name to all molecules of this molecule type. The name will not appear during the simulation unless show-label is set to TRUE (see below). Including spaces in a molecule type name will truncate the name at the space.

show-label
key	show-label
format	show-label [1 or 0]
description	Boolean to determine if label should be shown.
required	no
default value	0
example	show-label 1

Notes: See label (above). All other values besides “1” will be interpreted as FALSE.

color
key	color
format	color [0…1] [0…1] [0…1]
description	A description of the color used to draw this molecule type.
required	no
default value	some randomly chosen color
example	color .81 .60 .21

Notes: A color may be specified by the user for drawing molecules of this molecule type.

shape
key	shape
format	shape Sphere [float] [float]
	or
	shape Cube [float] [float] [float]
description	A description of the shape used to draw this molecule type.
required	no
default value	Sphere 1.0
example	shape Sphere 0.5
example	shape Sphere 0.5 2
example	shape Cube 1.0 2.0 3.5

Notes:

Two shapes may be used to draw a molecule, a sphere or a cube.

If a Sphere is chosen, at least one additional float value must be given to specify the radius of the sphere. A second, optional float value may be given to specify the “effective radius” of the molecule. “Effective radius” is used to maintain distances between “molecules” that act as compartment markers. Compartment markers are used in place of representing all of the molecules that are really present in a membrane. They can be thought of as representing a single molecule at the center of a circular collection of molecules where the radius of the circle is the “effective radius”. Compartment markers will maintain a distance from one another equivalent to (er1 + er2) where er1 and er2 are the effective radii of compartment markers 1 and 2. Other molecules (non compartment markers) will maintain a distance from compartment markers of (r1 + r2) where r1 and r2 are the radii of the compartment marker and the molecule respectively. A second float value must be specified after the shape key in order for the molecule to behave as a compartment marker.

draw-as-point
key	draw-as-point
format	draw-as-point [1 or 0]
description	A Boolean flag indicating that the molecule is to be drawn as a point.
required	no
default value	draw-as-point 0
example	draw-as-point 1

Notes: If draw–as-point is set to 1 (TRUE) then the molecule will appear in the simulation as a point. The radius and effective radius will still be as specified in the shape line. This flag is used to speed up the simulation by reducing the amount of required rendering. It may also be used to hide molecule types that are not of interest to the user. Values other than 1 are interpreted as 0 (FALSE).

opacity
key	opacity
format	opacity [0…1]
description	A description of how opaque the molecule should appear (where 0 is transparent and 1 is totally opaque).
required	no
default value	opacity 1
example	opacity 0.1

Notes: Opacity can be set to some value below 1 in order to make the molecule somewhat transparent. This allows the user to see through molecules of a certain type that might otherwise block views to other parts of the simulation.

show-neighbor-lines
key	show-neighbor-lines
format	show-neighbor-lines [1,0]
description	A Boolean flag indicating that lines are to be drawn between the molecule and its neighbor (as determined by the molecule’s neighborhood-size).
required	no
default value	show-neighbor-lines 0
example	show-neighbor-lines 1

Notes: If show-neighbor-lines is set to 1 (TRUE) then lines will appear between the molecule and its neighbors. This can be useful when debugging a simulation. Values other than 1 are interpreted as 0 (FALSE).

neighborhood-size
key	neighborhood-size
format	neighborhood-size [float]
description	A description of the molecule’s neighborhood size.
required	no
default value	neighborhood-size 1.0
example	neighborhood-size 2.5

Notes: The neighborhood-size is a float value that specifies the radius of a sphere that has the same centre as the molecule. This value specifies how far the molecule “looks” when finding other neighbor molecules. When a molecule is looking for neighboring coordinators, it will only consider coordinators within this radius AND any coordinators of neighboring molecules.

dynamic-neighborhood-sizing
key	dynamic-neighborhood-sizing
format	dynamic-neighborhood-sizing [1,0]
description	A Boolean flag indicating if this molecule is to use dynamic-neighborhood-sizing.
required	no
default value	dynamic-neighborhood-sizing 0
example	dynamic-neighborhood-sizing 1

Notes: If dynamic-neighborhood-sizing is set to 1 (TRUE) then the molecule’s neighborhood size will increase by 1 unit per simulation iteration until all of its channels are occupied by some coordinator. Values other than 1 are interpreted as 0 (FALSE).

feature
key	feature
format	feature [integer] [string]
description	A feature is described using a feature identifier and a label. Each feature may have one of multiple possible states. These possible states are described using the feature-state line.
required	no
default value	There are no default values
example	feature 234 Tyr234

Notes: A molecule may have multiple features. Each feature is described using a separate feature line. Each feature is described using a feature id (integer value following the feature key word) followed by a label (string value with no spaces). The feature is not associated with any state information. For example, the line

feature 234 Tyr234

simply indicates that there is some feature (with id 234 and label Tyr234) that can exist in one of many multiple states (see feature-state below). For protein molecules, amino acids numbers could be used as feature identifiers for their corresponding amino acids; however, this is not required. Any integer may be used for a feature identifier so long as that integer is used only once for any given molecule.

N.B. features and feature-values are not used by Magrathea, but may be used in future to present information to the user. They do not have to be specified as a prerequisite to using state information in a coordinator rule (see below).