The Magrathea Manual: Coordinated Agent Modelling By Example

Introduction

Magrathea is a prototype implementation of the Coordinated Agent Modelling (CAM) Method for representing biological pathways.

This prototype may be used to generate rule-based animated movies representing biological pathways. While it is hoped that this prototype demonstrates the underlying principals of CAM and that it is useful as an exploratory or narrative tool, no claims are made as to the utility or correctness of models generated using this method.

Availability

The magrathea.tz prototype script can be made available to interested collabortors. A paper is being prepared describing this work. These manual pages are posted for the benfit of collaborators and interested readers.

Comments, feedback and requests for the magrathea.tz prototype are welcome and may be sent to ian.donaldson@biotek.uio.no.

Acknowledgements

The Magrathea prototype and this documentation were developed by Ian Donaldson and Antonio Mora at the Biotechnology Centre of Oslo, University of Oslo.

The Magrathea prototype is dependent on the breve autonomous agent toolkit written by Jon Klein and available at http://www.spiderland .org.

Copyright

The material on this site is Copyright 2009, Ian Donaldson.

Introduction to Coordinated Agent Modelling By Example

This section outlines some of the defining features of Coordinated Agent Modelling (CAM). A more detailed and formal description of the implementation of CAM in the Magrathea prototype program is given in the second part of The Magrathea Manual: Building Coordinated Agent Models. This section describes the construction of model files for CAM models.

Coordinated Agent Modelling considers that animation of pathways and simulation of pathways belong to the same continuum. The Coordinator is a device that is used to tie animation and simulation to this same continuum. The next sections briefly review the ideas of CAM. The sections beginning with "Present Implementation" walks the reader through these ideas using a series of examples.

Molecules and Coordinators

Coordinated agent modeling is a method used to animate representations of biological pathways. A coordinated agent model is created by defining a set of molecule types and coordinator types.

In brief, molecule type descriptions define the properties of the types of molecules in the model. Coordinator type descriptions define the types of potential relationships that may occur between these different types of molecules. These relationships include physical interactions and any molecular transformations that may occur as a result of these interactions. In addition to describing the types of molecules and coordinators, the model may also specify the number and locations of the molecules and coordinators that initially populate the simulation.

A model is initially populated with molecules distributed in some three-dimensional space. Coordinators are brought into existence when two molecules move within one another’s neighborhoods (say, for instance, they collide) and those two molecules are both potential members of some coordinator (such as a potential interaction). When the coordinator is created, it is assigned a position in three-dimensional space that is midway between its member molecules.

Coordinators act on molecules

Coordinators act on molecules. For instance, a coordinator defining an interaction between two molecules will adjust the physical locations of these two molecules at each time step of the simulation so they remain adjacent to one another without overlapping. Each coordinator maintains a list of the molecules that it is currently acting on (its member molecules). A coordinator’s members may change over the course of the simulation. Conversely, each molecule maintains a list of the coordinators that are acting on it.

A coordinator acts on its member molecules according to a set of rules predefined in the coordinator type description. These rules may cause the member molecule to undergo state changes or translocations (across a compartment boundary). The execution of these events is dependent on a set of conditions that must be met. Conditions may include the number, types and states of the other member molecules of the coordinator. Coordinator rules may also be used to determine when molecules of some type may either join or leave the coordinator.

Coordinators may be used to define complexes

A coordinator with two member molecules is used to describe an interaction between those two molecules along with the resulting molecular transformations that take place as a result of the interaction.

A coordinator may also be used to define an interaction between three or more molecules in a complex without defining the individual interactions between the members of the complex. This may be useful in cases where the interactions are either unknown or of no importance to the model. In cases where a coordinator defines a complex, the member molecules are constrained in a region of space defined by the surface of a sphere with the coordinator at the centre. The surface area of the sphere is equivalent to the sum of the cross-sectional areas of the member molecules. Each molecule is held to the surface of this sphere using a spring function defined by the positions of the coordinator and the molecule.

Coordinator members have stoichiometry

Coordinators have potential members defined by a molecule type and some maximal stoichiometry for that molecule type. A coordinator is created once two or more potential molecules encounter one another in their respective neighborhoods. Additional members may join this coordinator in subsequent time-steps if the maximal stoichiometry for that molecule type has not been met. The addition of molecules to a coordinator may be unordered or (optionally) ordered by a set of addition rules specified by the coordinator. Similarly, rules may be used to specify the order in which molecules leave a coordinator depending on the presence, stoichiometry and state of any of the member molecules.

Coordinators may be used to define compartments

A coordinator may be used to describe a compartment. The representation is similar to that of a complex. Again, the coordinator is positioned midway between member molecules. The coordinator then moves (and holds) these molecules to a position on the surface of an imaginary sphere whose surface area is equivalent to the sum of the cross-sectional areas of each of the members radii. The resulting structure appears as a spherical compartment whose surface is covered by the member molecules in a closely packed configuration. Optionally, a set of “marker” molecules may be assigned as members of the coordinator that have an “effective radius” that is larger than their apparent (visualized) radius. This allows for the demarcation of large compartments without having to specify molecules that cover the entire surface.

Molecules may be described as potential inhabitants of compartments. This acts to restrict molecules from entering compartments where they do not belong and to constrain molecules within compartments where they do belong. Molecules may be moved into and out of compartments by interacting with surface molecules (members of the coordinator representing a compartment) that act as transporters. This interaction and subsequent translocation is encoded by a set of coordinator rules. This translocation may be dependent on the state of the transporter molecule and/or the state of the molecule to be transported.

Coordinators may be used to define membranes

Coordinators representing interactions, complexes and compartments all use a point location around which member molecules are organized. Coordinators have two other geometric forms which allow for the representation of planar and linear macromolecular structures.

Planar coordinators may be used to represent membranes. Member molecules of planar coordinators are constrained to movement in the surface of the plane using a spring function defined by the positions of the coordinator and the molecule. Non-member molecules are restricted from passing through a planar coordinator although they may be translocated across the plane by a method analogous to that described for compartment transporters.

Linear molecules may be used to represent structures such as microtubules. Member molecules are constrained to movement along a linear path defined by a line with some beginning and end point in 3D space.

Coordinators may be used to describe a molecule’s context

A molecules function is largely dependent upon its context. A molecule’s context may be thought as the sum of all the sub-contexts in which that molecule is directly a member.

For example, a membrane-bound receptor (r) may bind to some extra-cellular ligand (l) to form an rl complex. The formation of the complex initiates some intracellular signalling event. In this example, r may be thought of as having two potential contexts. The first context is that of the membrane (M). r being in the context of M has implications on its physical location and movement as well as the molecules that it is most likely to meet with (other molecules with context M). The second context is that of a specific interaction (I) between r and l. r being in the context of I has implications on its physical location (it will of course co-localize with l) and on the probability of events associated with this context (for example, the transformation of r to some alternative “active” state that will allow r to participate in some new context; say some downstream event in the signalling pathway).

In this example, the receptor (r) has two sub-contexts; an interaction (I) and a membrane (M). Both of these contexts may be represented by coordinators in a CAM model (see above). The ability of R to simultaneously participate in two sub-contexts is described by assigning two “channels” to R. A channel represents the potential of a molecule to be coordinated by some coordinator. In this case, channel A conveys effects on R encoded by coordinator I and channel B conveys effects encoded by coordinator M. When molecule R joins a coordinator, it does so by assigning that coordinator to a channel and that channel is then said to be occupied. Each channel may be unoccupied or occupied by a single coordinator from a list of potential coordinator types for that channel. This “channel” device allows a molecule to simultaneously participate in (be effected by or informed by) multiple sub-contexts. A channel may correspond to a physical binding site though this does not hold in all cases (such as for the channel mediating the membrane (M) context).

The above example may be extended to include an effector molecule (e) that binds to the cytosolic portion of the receptor (r). This interaction is represented by a third coordinator (S). S may encode a rule that monitors the states of the member molecules at each time-step. If r is in some activated state and if e is present in some inactive state, then the rule specifies an event whereby some feature of e changes state and leaves the coordinator. This example demonstrates how a model may propagate a state-change (signal) from one molecule to another (l to r to e) via coordinators (I and S) even though these two molecules (l and e) do not directly share the same context.

Coordinators may be used to organize the molecules in a simulation

Coordinators are brought into existence once two molecules occur within one another’s neighborhoods and those two molecules can both potentially belong to the same type of coordinator. A molecule’s neighborhood is defined as a sphere with some radius that has the same centre as the molecule. If two molecules each have neighborhoods with radii equivalent to their own radii, a potential coordinator may be created when these two molecules collide.

The neighborhood size may be specified to be larger than the actual molecule. At each time step of the simulation, the molecule will check its neighborhood for the presence of other molecules with which it could create a coordinator. This device allows for a coordinator defining an interaction to be created before the two molecules actually collide. The coordinator defining the interaction will then act to move these two molecules together and maintain their association.

Additionally, the neighborhood size of a molecule may be set to increase at each time-step of the simulation if the molecule has unoccupied channels. This device is called “dynamic neighborhood sizing” and has the effect of allowing each molecule to scan the simulation until it finds its closest potential coordinator co-member. Dynamic neighborhood sizing has the effect of organizing the molecules of the simulation such that they become animated by a set of predefined rules encoded by coordinators.

As molecules become assembled with coordinators, they may change state, be destroyed, be translocated, leave existing coordinators, join existing coordinators or create new coordinators. Since coordinators are dynamically formed and destroyed according to the local presence of molecules and their individual states, the components of the model are constantly organized and re-organized throughout the time course of the animation.

If the neighborhood size of molecules is set to zero, then coordinators are formed when molecules physically collide. If dynamic neighborhood sizing is used, molecules will be organized by coordinators before they collide. This device then ties simulation (neighborhood size = 0) and animation (dynamic neighborhood sizing) to the same continuum.

Next we introduce the present implementation of the CAM method and demonstrate how it may be used to build such animated narratives of biological pathways.