The Magrathea Manual: Building Coordinated Agent 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
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:
and ends with the line
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:
and ends with the line
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
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
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]
|description||A unique identifier for this molecule type|
|default value||not applicable|
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.
|description||A label for the molecule type.|
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.
|format||show-label [1 or 0]|
|description||Boolean to determine if label should be shown.|
Notes: See label (above). All other values besides “1” will be interpreted as FALSE.
|format||color [0…1] [0…1] [0…1]|
|description||A description of the color used to draw this molecule type.|
|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.
|format||shape Sphere [float] [float]|
|shape Cube [float] [float] [float]|
|description||A description of the shape used to draw this molecule type.|
|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|
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.
|format||draw-as-point [1 or 0]|
|description||A Boolean flag indicating that the molecule is to be drawn as a point.|
|default value||draw-as-point 0|
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).
|description||A description of how opaque the molecule should appear (where 0 is transparent and 1 is totally opaque).|
|default value||opacity 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.
|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).|
|default value||show-neighbor-lines 0|
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).
|description||A description of the molecule’s neighborhood size.|
|default value||neighborhood-size 1.0|
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.
|description||A Boolean flag indicating if this molecule is to use dynamic-neighborhood-sizing.|
|default value||dynamic-neighborhood-sizing 0|
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).
|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.|
|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 right now, 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).
|format||feature-state [integer] [integer] [string]|
|description||Each feature described by a feature line may have one of multiple possible states. These possible states are described using the feature-state line.|
|default value||There are no default values|
|example||feature-state 234 0 unphosphorylated|
|feature-state 234 1 phosphorylated|
Notes: A molecule may have multiple features. Each feature is described using a separate feature line (above). Each feature can exist in one of many multiple states. Each of these possible states is described by a separate feature-state line. The first integer indicates the feature identifier that this state applies to. The second integer is a state-identifier indicating one possible state for this feature. An integer identifier should be unique to a feature on a molecule. The string value provides a label that describes this particular state.
Note: 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).
|format||coordinator [integer] [integer]|
|description||A description of the coordinators that a molecule can “listen” to.|
|default value||there are no default coordinator assignments|
|example||coordinator 1 3|
Notes: Molecules of a given molecule type can be coordinated by a coordinator of a given coordinator type. Molecules may have multiple coordinators. A molecule joins a coordinator using one of its “channels”. A channel may be occupied by only one coordinator at a time. However, the same channel may be occupied by one of several different coordinator types. Channels could be thought of as binding sites and coordinators may be thought of as interactions (though the analogy is not applicable to all molecule coordinator pairings, hence the use of the “coordinator and channel” terminology). A binding site may be involved in one of several different interactions (i.e. with different binding partners). Therefore, multiple coordinator lines may be listed for a single molecule type. For instance, the lines:
coordinator 1 3 coordinator 1 4 coordinator 2 5
would be used to specify a molecule type that could pair (mutually exclusively) with either coordinator 3 or 4 using channel 1 and (at the same time) could pair with coordinator 5 using channel 2. The abstract ideas of channels and coordinator are more thoroughly explained in previous sections of this manual.
|description||Specifies that a molecule is a resident of some coordinator that represents a compartment|
|default value||there are no default assignments|
Notes: Spherical point coordinators may be used to represent compartments. At the beginning of a simulation, any molecules found inside a coordinator compartment will be kicked out unless this flag has been set indicating that the molecule may reside in that compartment type (the coordinator id is used to specify the compartment type). If a molecule is a resident of a compartment, it will move randomly within the space of that compartment until it encounters the inside face of the compartment. Collisions with the inside face of a compartment will result in the molecule being repelled (contained) back towards the center of the compartment.
It is very important that the isSizeDynamic flag be set to 1 for coordinators that are used to represent compartments. If not, the size and shape of the coordinator rendered in the simulation is meaningless (it is drawn only to mark the point-location of the coordinator). When isSizeDynamic is TRUE, the coordinator is drawn as a sphere and its size reflects the radius of the imaginary sphere around the coordinator centre that maintains the offset distance of member molecules from the coordinator. This offset distance is also used to determine whether molecules are inside or outside the compartment.
|key||See below. Multiple keys are associated with this subsection including id, if, then, and parameters|
[rule] id [integer] if [string] . . competitive-with [integer] . . then [string|integer] [string] [string|integer] . . parameters [string] [float] . . [/rule]
|description||Used to define events that occur to a molecule.|
|default value||there are no default rules|
[rule] id 1 if 1.1.1 competitive-with 2 then 1 is-destroyed parameters p 0.001 [/rule]
Notes: The [rule] … [/rule] subsection of molecules is used to define events that occur to a single molecule. Multiple rule subsections may be associated with one molecule. Each rule is defined using multiple lines with keywords id, if, competitive-with, then and parameters. These keywords and their line formats are described below.
In general, each rule has:
1) an identifier that is unique to the molecule
2) a set of prerequisite conditions (specified by if lines) that must be met in order for
3) some set of events to be carried out (specified by then lines) according to
4) a set of parameters specified on one or more parameter lines.
See this example for an example model file that uses molecule rules.
|[rule] id [/rule]|
|description||Used to identify a rule for a molecule|
|default value||there are no default rules|
Notes: The id line defines a single integer identifier for a rule. It must be the first line of the rule subsection and it must be unique to the rules defined for the molecule to which belongs to.
|[rule] if [/rule]|
|description||Used to define a prerequisite condition for some event. The precondition is expressed as the molecule id with or without some feature-state specification|
|default value||there are no default values|
Notes: The if line is used to define a prerequisite condition for some event. The precondition is expressed as the molecule id with or without some feature-state specification. The line contains a single value that is a dot delimited list of integers. For example,
This dot-delimited condition is of the form:
|if line format|
|position||Meaning and possible values||Example|
|1||Required molecule type (an integer corresponding to a molecule type id). See “id” key under [moleculeType]||2|
|2 + 2n||Feature identifier specified by some integer.||1|
|3 + 2n||Required state of feature (previous position) specified by some integer.||1|
Note: n is an integer from 0, 1, 2… specifying a feature-state condition (see explanation below).
So the first three numbers in the example above
mean that the rule applies for each copy of molecule type 2, with feature 1 in state 1. And the following 2.4 (positions 4 - 5) would indicate that the molecule must have feature 2 in state 4.
|[rule] competitive-with [/rule]|
|description||Used to point out that the present rule and the rule having the specified id can not occur simultaneously.|
|default value||there are no default values|
Notes: The competitive-with line specifies the identifier for a rule that is competitive to the current rule. That means that the rule including this line and the rule having the specified id can not occur simultaneously, even if the specified conditions in the if line were met, so the algorithm will choose one of them or neither of them, but never both. This is useful when having molecules that can follow different reactions.
|[rule] then [/rule]|
|format||integer] [string] [string|integer]|
|description||Used to define events that occur to a given molecule|
|default value||there are no default events|
|example||then 1 is-destroyed|
Notes:The then line is used to define events that may occur to a given molecule if the condition defined by the if line is met. There are several different possibilities for this line that are differentiated by the second string value. They are:
then 6.1 is-created-at-location-of 6
In this case, 1 instance of molecule type 6 is created at the same location of the molecule.
then 1 is-destroyed
In this case, the current molecule (1) is destroyed.
then 1 changes-state-to 1.2
In this case, the current molecule (tag 1) will change state according to the state description 1.2 (feature 1 changes state to state 2). Multiple feature–state changes may be specified on one line; i.e., 22.214.171.124.5.6.33 means that feature 1 assumes state 2, feature 4 assumes state 5 and feature 6 assumes state 33.
then 1 changes-colour-to .1:.32:.11
In this case, the molecule will change to the colour specified by .1:.32:.11 (the colons separate three float values in the RGB colour description; i.e. .1 .32 .11).
Currently, translocations are not supported as events for molecule rules (as they are for coordinator rules).
|[rule] parameters [/rule]|
|format||parameters [string] [float]|
|description||Used to define parameters for the event under consideration|
|default value||parameters p 1.0|
|example||parameters kf 0.07|
Notes: The parameters line is used to specify the value of the parameters for the event that will occur. The string value will represent the id for that parameter while the float value (so far) will represent the probability for the event to take place given that all conditions were met. The default parameters value is 1.0, meaning that events will occur if all conditions are met.
In the future, the float value could include values of kinetic mass-action, Michaelis-Menten or Hill constants. Not implemented yet.
|description||Creates instances of molecules and assigns locations in the|
|default value||there are no default instantiations of molecule types|
|example||instantiate 4 random spherical volume 10 15 10 10|
Notes: The instantiate line is the last line listed for a molecule type description. This line creates instances of molecules and assigns them positions within the simulation. An instantiate line is also used to create new instances of coordinators and position them in space; the same format given below applies. The instantiation line is composed of up to 14 white-space delimited fields. These fields and their formats are described in the table below, Specific examples of their use are described next.
The simplest case is to create one or more molecules at some determined point in space using the line:
instantiate 1 determined point - 10 15 10
However, a set of molecules could also be created and given random locations within the volume of a sphere using
instantiate 4 random spherical volume 10 15 9 5
Here, 10 15 9 specifies the x,y,z coordinates for the centre of the sphere and 5 specifies the radius of the sphere.
The molecules could also be distributed on the surface of the sphere (instead of within its volume) using the line:
instantiate 4 random spherical surface 10 15 9 5
Or the distribution could be applied to a plane using:
instantiate 100 random planar - 10 15 22 5 0 1 0
Here 10 15 22 specifies a point on the plane, 5 represents the maximum distance from this point that the molecules will be distributed to (radius) and 0 1 0 describes a normal to the plane. In a breve simulation, a normal of 0 1 0 points up along the y axis, a normal of 1 0 0 points along the x axis and a normal of 0 0 1 points along the z axis in the positive direction. The – in field 5 is used as a placeholder since the centres of the molecules will be aligned with the plane and neither “volume” nor “surface” apply.
Lastly, a distribution may be applied to the surface or volume of a cylinder using
instantiate 100 random cylindrical volume 10 15 22 0 1 0 5 35
Here, 10 15 22 specifies the centre of the base of the cylinder. 0 1 0 specifies a normal vector to the base of the cylinder. 5 is the radius of the cylinder and 35 is the height of the cylinder.
Feature-state information may also be specified at the time of instantiation using a feature.state vector in the fourteenth field of the instantiate line. For example:
instantiate 10 random spherical volume 10 15 10 1 - - - - 126.96.36.199
will set feature 1 to state 1 and feature 2 to state 0 for this set of molecules. See feature and feature-state above.
Using multiple instantiate lines
Multiple instantiate lines may be used for creating multiple distributions of the same molecule (or coordinator) type at different locations within the simulation. Features of the molecule type may be altered between instantiate lines (see below for an example); the last description of a feature listed will be applied to the next instantiation. For example:
[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 coordinator 1 3 instantiate 10 random spherical volume 10 30 10 5 color .99 .99 .99 instantiate 4 random spherical volume 10 20 10 5 [/moleculeType]
The above moleculeType description will create 14 molecules of type 1; however, 4 of the molecules will have a generally different starting location and a different color.