Dynetica User’s Guide (version 0.1beta)

Dynetica is a biologist oriented modeling tool for constructing, visualizing, and analyzing kinetic models of biological systems. The interface is overall rather intuitive. The best way to learn Dynetica is probably trying out the included examples and build some of your own.

Dynetica is written in Java. You need Java 1.3 or above to run the program. You should be able to get Java from Sun (http://www.sun.com) for free.

Getting started

· Installation (Back to top)

You can download Dynetica from http://www.cheme.caltech.edu/~you. Follow the links therein and get a zipped file called DyneticaInstall.zip. Unzip this file to a directory, say DyneticaDirectory. In DyneticaDirectory you should have two items, one is a jar file: Dynetica.jar, the other is a subdirectory called “examples”, which holds some example models built in Dynetica.

To run Dynetica, you can type the following command in a command window (in Unix or Windows):

Ø java –classpath Dynetica.jar Dynetica // NOTE: if you’re in the directory “DyneticaDirectory”

Ø java –classpath <DyneticaDirectory>/Dynetica.jar Dynetica //NOTE: if you’re anywhere else

Now you should see the main (blank) window popping onto your computer screen (Figure 1).

Figure 1. The main window without any models open

Note: Some of my colleagues have used Dynetica in a MacOS (OS X, I believe), althougth I haven’t tried myself. Since I can’t give you advice here, you will need to consult the manual for the Java virtual machine on how to run a java program in Mac.

· Opening an existing model (Back to top)

To open an existing model, click on the button labeled “Open”. A dialog window should pop out (Figure 2):

Figure 2. The dialogue window for opening an input file.

At the first use, Dynetica will need your help to locate the working directory. Just use the dialog window to locate the directory <DyneticaDirectory>/examples. Here is what the window should look like when you find the directory (Figure 3):

Figure 3. As above, but in a different directory

To start, let’s select a simple model reverse. Just click the file reverse.dyn and then click the button Open. You should get something like the following window (Figure 4). In this window, the left panel shows the tree-structure view of the network, and the right panel gives a graphic representation. In the graph a green line indicates the production of the connected substance by the connected reaction, a red line represents the consumption of the connected substance by the connected reaction, and a gray dashed line indicates that the connected substance affects the kinetics of the connected reaction. Details of these reactions are shown in Table 1.

Table 1. The reactions in the simple reaction network shown in Figure 4.

Reaction name	Stoichiometry	Kinetics
R1	A → B	k₁[A] [E] ^a
R2	B → A	k₂ [B]

^a The rate expression is actually written as k₁[A] * [E] in Dynetica.

Figure 4. The main window with the system Reverse opened.

Now you can click the nodes on the left hand side and inspect various entities in the model. Also, you can inspect the substances and reactions using the graph on the right. For example, if you double-click the node A, you should get an EntityEditor (see below), in which you can change the attributes (such as initial level, minimum and maximum levels) of this substance. You’ll also see a rate expression automatically generated by the program based on the structure of the network. Note that you can annotate the substance using the Annotation field.

Figure 5. The editor window for substance A.

You can also edit a reaction by double-clicking the corresponding node in the system tree or in the graph. Here is what you should get by double-clicking the reaction node R1.

Figure 6. The editor window for reaction R1. A ProgressiveReaction is characterized by two basic attributes: its stoichiometry (what is/are turned into what) and its kinetics (how fast?). Both can be typed in by following conventions in writing a reaction and a mathematical expression. Note that you can edit the substances and parameters associated with this reaction within this window.

Now you should be able to follow the same procedure and open the other model input files included in the package. Give it a try!

· Creating a new model (Back to top)

Creating a new model in Dynetica is extremely easy. First, click on the button New (or select the menu item New in the File menu). You should see the following window popping out, and let’s call the new system “Test”.

Figure 7. Dialogue window for creating a new system

Click OK and you should get a system with no substances or reactions (Figure 8). By default, the program will create a parameter called “Time” – you should never modify or delete it, which may corrupt your input file.

Figure 8. A test model with (almost) nothing in it.

To create a new substance, click the combo-button at the bottom, and select Substance. Change the suggested name into your preferred name, which should not contain spaces or mathematical operators (+, *, /, ^, etc). Let’s call it “A”. After you accepted the name, a node corresponding the substance will appear in the graph. The editor window for A will also pop up to allow you to specify the attributes of the substance. Let’s change the initial level of A to 100.

Follow the same procedure and create another substance “B”, and leave its attributes as they are. Then, create a ProgressiveReaction following the same procedure, and name the reaction “A2B”. In the Stoichiometry field, type in “A->B”, and in the Kinetics field, type in “k * [A]”. Note that you need to put a pair of parentheses around A to indicate that it’s a substance rather than a parameter. The parameter k should appear in the Parameters list in the reaction editor (Figure 9). Let change its value to 0.1.

Figure 9. Editor window for reaction A2B in the new test model.

After this step and some additional manual placement of the nodes, you may get something like this (Figure 10). And you now have a complete reaction system. You can add more reactions and substances following the procedure described above. Note: although the program can correctly generate the new substances or parameters you type in the reaction formula or the kinetics expressions, it may sometimes mess up the graphic layout on some platforms. To avoid this, always create a substance before using it in a reaction.

Figure 10. Your first model in Dynetica, which consists of a single reaction converting A into B.

You can save your model by clicking on “Save” or “Save As” buttons. The subsequent procedure is similar as what you follow in opening a file.

· Reactions in Dynetica (Back to top)

You can create two basic types of reactions: ProgressiveReaction and EquilibratedReaction. A ProgressiveReaction is a reaction not at equilibrium (thus progressive). As shown above, it’s characterized by two attributes: Stoichiometry and Kinetics. Several specialized reactions have been built upon ProgressiveReaction to facilitate model construction. In a MassAction reaction, the kinetics is based on the mass action law. A Generator reaction is a reaction that produces a product following the mass action kinetics; you need to specify the product name and a rate constant for this reaction type. A Decay reaction describes the degradation of a substance; you need to specify the substrate name and rate constant for this reaction type. A MichaelisMentenReaction is reaction that follows the Michaelis-Menten kinetics; you need to specify names of the substrate, the product and the enzyme, and two parameters: vmax and Km. Since all these specialized progressive reactions are derived from the ProgressiveReaction type, each of them can be formulated in a ProgressiveReaction, but the reverse is not true.

Currently, only one special type of EquilibratedReaction has been implemented: the EquilibratedMassAction. As its name suggests, an EquilibratedMassAction is an equilibrated reaction where the equilibrium constraint is specified following the mass action law. Note that, you should avoid equilibrated reactions if you want to use the Gillespie algorithm. Instead, you should replace an equilibrated reaction with a reversible, yet progressive reaction.

· Kinetic expressions in Dynetica (Back to top)

The expression parser of Dynetica can interpret mathematical expressions composed of the operations and functions shown in Table 2. The kinetics of most chemical reactions can be formulated easily within this framework.

Table 2. The mathematical operations and functions that are supported by Dynetica

	Symbols or expressions	Note
Basic operations	+, -, *, /, ^	‘^’ represents to the power of.
Basic functions ^a	sin(a), cos(a), tan(a), sqrt(a), log(a)	log(a) returns the natural logarithm value of a
Special functions ^a	step(a, b)	returns 1 if a ³ b, and 0 otherwise
	compare(a, b)	returns 1 if a > b, 0 if a = b, and –1 if a < b
	pulse(a, x, b)	returns 1 if a < x < b, 0 otherwise
	random(a, b)	returns a random value between a and b
	rand()	returns a random value between 0 and 1
	min(a, b, c, …)	returns the minimum value from the list of arguments
	max(a, b, c,…)	returns the maximum value from the list of arguments

^a Each of the symbols (a, b, c and x ) may represent a simple variable or a mathematical expression.

Running Simulations

· Time course simulations (Back to top)

Deterministic simulation

By default, Dynetica uses a variable time step 4^th order Runge Kutta algorithm (labeled “RungeKuttaFehlberg”), which is implemented based on the description in Numerical Recipies (http://www.nr.com/). Click the Start button and then the Plot button using your toy model, you’ll get a window with the time courses of the substances in the system (Figure 11). Similar results can be obtained if you select the classic Runge-Kutta 4^th order algorithm.

Figure 11. The time courses for the toy model in Figure 10. You’ll need to select both A and B in the list labeled as Y values. By default, the program use Time as the x-axis, but you may select a state variable (substance level) as the x-axis. For example, if you select A in the X value list and B in the Y value list, you’ll get the phase plane of this simple system (right hand side). The phase plane will look more interesting if your system will generate oscillations. For example, try the model described in lokta.dyn.

You may configure your simulation by clicking on the algorithm (from the combo-button or from the menu) you’d like to use, and change the attributes accordingly. For example, here is the basic configuration of the default algorithm (Figure 12). In this window you can change the total elongation of the simulation by change the number of iterations or the interval between sampling points. You can also change the error tolerance for the simulation: a smaller tolerance corresponds to higher accuracy.

Figure 12. The basic configuration of the RungeKuttaFehlberg algorithm.

Stochastic simulation

If levels of substances in the model are represented in terms of numbers of molecules, you can apply the Gillespie algorithm to conduct a stochastic simulation. Shown in Figure 13 (Left) is the simulation output from the model Reverse using the Gillespie algorithm. For comparison, the result from a deterministic simulation is also shown (Right).

B

A

Figure 13. (A) Stochastic and (B) deterministic simulation results from the model Reverse.

· Basic Sensitivity Analysis (Back to top)

In addition to simulating the temporal evolution of a reaction network, Dynetica provides the basic functionality to explore how the dynamics of the network responds to the perturbations to the network, in terms of variations in parameter values or the initial levels of substances. This feature is desirable for simulating dosage curves and for identifying key system parameters that are important in determining overall behaviors of the system.

Let’s use system Reverse as the example again. First, open the system input file Reverse.dyn. Then, click on menu Simulation and click item Sensitivity Analysis therein. A dialogue window should pop up, as shown in Figure 14A. You can fill in the appropriate information (Figure 14B) and conduct analysis. A typical set of sensitivity analysis result is shown in Figure 14C.

C

B

A

Figure 14. (A) The dialogue window for setting up sensitivity analysis. (B) The window with sensitivity analysis information specified: the variable to be varied is parameter k1; it will be varied from 0 to 1, with an interval of 0.1 (10 points will be calculated); the system will be simulated until the time point at 50.0; the dependence of all three state variables (A, B, and E) on k1 will be shown. (C) The sensitivity analysis result.

Example models

The following models can be found in the example directory.

· An Dictyostelium aggregation stage network (Back to top)

This model is based on Laub and Loomis, 1998, Mol Biol Cell 9: 3521-32. However, the parameters used here have different values from the published parameters, some of which were in error (W. Loomis, personal communication). Reactions of this network are shown in Table 3. With appropriate parameters, this model will generate sable oscillations.

Figure 15. The aggregation stage network model. (A) The network connectivity. (B) A typical simulation result demonstrating oscillations in the enzyme levels.

Table 3. The production reactions in the aggregation stage network ^a

Reaction	Stoichiometry	Kinetics	Notes
p_ACA	→ ACA	k₁ [ERK2]	activation of ACA by ERK2
d_ACA	ACA →	k₂ [ACA]	degradation of ACA
p_PKA	→ PKA	k₃ [cAMPi]	activation of PKA by cAMPi
d_PKA	PKA ®	k₄ [PKA]	degradation of PKA
p_ERK2	→ERK2	k₅ [CAR1]	activation of ERK2 by CAR1
d_ERK2	ERK2 →	k₆ [ERK2] [REGA]	degradation of ERK2 (catalyzed by REGA)
p_REGA	→REGA	k₇	constant production of REGA
d_REGA	REGA→	k₈ [REGA] [ERK2]	degradation of REGA (catalyzed by ERK2)
p_cAMPi	→ cAMPi	k₉ [ACA]	activation of cAMPi by ACA
d_cAMPi	cAMPi →	k₁₀[REGA][cAMPi]	degradation of cAMPi (catalyzed by REGA)
p_cAMPe	→ cAMPe	k₁₁ [ACA]	activation of cAMPe by ACA
d_cAMPe	cAMPe→	k₁₂ [cAMPe]	degradation of cAMPe
p_CAR1	→ CAR1	k₁₃ [cAMPe]	activation of CAR1 by cAMPe
d_CAR1	CAR1→	k₁₄ [CAR1][PKA]	degradation catalyzed by PKA

^aAlthough recent studies have suggested a slightly revised reaction network (http://www.biology.ucsd.edu/labs/loomis/network/laubloomis.html), the published model suffices to illustrate the usage of Dynetica.

· A simplified Phage T7 model (Back to top)

The model presented here (Figure 16) is a simplified version of a model of phage T7 intracellular growth cycle. The major difference between the current model and the previous ones is that a simplified genome is used here (Figure 16A). This simplified genome contains 20 essential T7 genes. The regulatory effect of promoters and transcription terminators is accounted for by specifying the relative transcription activity of each gene. As a result, RNA polymerases are allocated to different genes based on their relative transcription activities, whereas in the complete model RNA polymerases are allocated based on the relative strengths of promoters. The resulting T7 reaction network contains 91 reactions and 55 substances, excluding genes (Figure 16B). In this network, the reactions describing expression of genes and degradation of gene products are automatically generated by Dynetica.

Figure 16. A simplified phage T7 model. . (A) The simplified T7 genome. The left panel shows a list of genes in the genome (not all genes are shown); the right panel shows the attributes of the currently selected gene. (B) The graphic representation of the reaction network. Most of the reactions are automatically generated based on the genetic information shown in A.

B

A

Figure 17. Typical simulation results from the simple T7 model. Time courses of (A) selected mRNAs (half way into simulation), and (B) three major phage components: the newly synthesized DNA, procapsids, and final phage progeny.