How to create EcoNet models?

During the design process of EcoNet interface, we had several choices for a model input method. Several modeling software use a graphical user interface (GUI) where users drag and drop geometrical shapes representing stocks and then define arrows connecting these stocks. EcoNet uses a flexible text-based model input method.

While a GUI-interface is intuitive and user friendly, it is not necessarily easier to use. Typing a text file is considerably quicker and easier than using a mouse to form a diagram. A model in text format is extremely portable and does not need special file formats to be saved or sent. It can be copied and pasted into other applications, and is human readable. Furthermore, a text-based interface enables expert users to write codes to automatically generate very large models with thousands of stocks and flows for spatial modeling or statistical analysis.

EcoNet model structure

EcoNet models consist of four basic information types, each associated with some special characters:

Flows among compartments: A directional flow from compartment A to compartment B is intuitively represented by "A -> B". Environment is represented by "*", so "* -> C" and "D -> *" represent the environmental input to compartment C and the dissipation from compartment D respectively.
Initial storage value of compartments: These values are entered by simply typing the compartment name followed by "=", and then the numerical value. If the initial value of compartment A is 15 units, this can be represented by "A = 15".
Flow type and associated coefficients: In real life, speed of a flow between two compartments may depend solely on the storage value of the donor compartment, or the recipient compartment, or both (Lotka-Volterra). In some real-life cases, there is an upper-bound on the speed of flow no matter how high the storage values of both compartments are. There even cases where the flow between two compartments is affected by the storage value of a third compartment. We call these different flow types, and naturally the simulation results will change dramatically based on what flow types are used.
EcoNet currently features donor controlled (mass-action type) and donor-recipient controlled (Lotka Volterra) flow types. However EcoNet is currently being updated to accommodate a variety of flow types, including Michaelis-Menten. The notations for these flow types are presented below, however only the first two are currently functional. We have plans to feature flow types beyond the three listed below. Please check out the news page for updates and contact us with your suggestions and requests. Different flow types can be used in the same model.
- Donor controlled flow: If the speed of flow from compartment A to B is proportional to the storage value of A, the flow type is represented by "c=2.3" where 2.3 is a coefficient specific to this flow. In other words:
  (Speed of flow A->B) = 2.3 * (Storage value of A)
- Donor-Recipient controlled flow: If the speed of flow from compartment A to B is proportional to the storage values of both A and B, the flow type is represented by "r=1.2" where 1.2 is a coefficient specific to this flow. In other words:
  (Speed of flow A->B) = 1.2 * (Storage value of A) * (Storage value of B)
- Michaelis-Menten type flow: Michaelis-Menten type flow: Originally developed for enzymatic reactions, this flow type is useful when flow speed is limited or mediated by other factors. The syntax for defining a Michaelis-Menten type flow from compartment A to B is "v=3.2,2.1" where coefficients 3.2, 2.1 correspond to V_max, K_m [1]. The speed of this flow is interpreted as:
  (Speed of flow A->B) = 3.2 * (Storage value of A) * (Storage value of B) / ( 2.1 + (Storage value of A) )
Comments: EcoNet ignores anything written in a line after "#".

EcoNet model flexibility

Text based human-computer interactions are generally very demanding on the user's side. Sometimes, even a blank space must be accounted for when writing a computer code. However EcoNet users can write their models with a great range of flexibility, as EcoNet does not require strict formatting rules. EcoNet recognizes each stock name, and classifies each user input as an initial condition, a flow, or a flow type. It is EcoNet that does the hard work, not the user. To demonstrate this feature, we re-write the same model in different but correct ways. Consider the following simple model:

* -> Phytoplankton            c=3
Phytoplankton -> Zooplankton  c=1
Zooplankton -> Fish           c=.5
Fish -> *                     c=.2
Phytoplankton = 10
Zooplankton   = 1
Fish          = 5

Although each flow and initial condition is written as separate lines, there is no such restriction. One can write multiple flows or initial conditions in a single line by separating them using commas or semicolons:

* -> Phytoplankton  c=3; Phytoplankton -> Zooplankton  c=1
Zooplankton -> Fish  c=.5, Fish -> *  c=.2
Phytoplankton = 10; Zooplankton= 1, Fish=5

EcoNet ignores the order of appearance of flows and initial conditions. For better readability, one may choose to write all initial conditions grouped at the very end, or the beginning. In case of a large model with multiple parts, users can form groups of flows and initial conditions corresponding to each part. Or one can choose to write initial conditions after each flow:

* -> Phytoplankton  c=3
Phytoplankton = 10
Fish -> *  c=.2
Fish = 5 
Phytoplankton -> Zooplankton  c=1; Zooplankton = 1
Zooplankton -> Fish  c=.5

In rare cases, one may want to group flow types. This is also possible, and below is an example where there is almost no order; flows, initial conditions and flow types are all mixed together:

* -> Phytoplankton
c=3
Phytoplankton = 10
Phytoplankton -> Zooplankton
Zooplankton= 1; c=1
Zooplankton -> Fish; Fish=5
Fish -> *
c=.5, c=.2

Note that in this case, EcoNet will associate flow types to flows in the order of appearance. All this flexibility enables users to easily create and modify their models. Despite the fact that these models look very different, EcoNet generates the exact same equations for each of them.

A few rules about EcoNet models

Here are a few rules that users should keep in mind when writing their models:

EcoNet models are case sensitive, so both Zooplankton and zooplankton cannot be used to refer to the same compartment. On the other hand, users can name two different compartments Zooplankton and zooplankton in the same model without causing any problems.
Compartment names should not contain special characters such as "$%?&:;*)(!" or spaces. Use of "." and "_" are allowed.
Compartment names may contain numerical values in them, but cannot begin with one, so Zooplankton1, Zoo1plankton2 are valid compartment names while 1Zooplankton is not.
"c" cannot be used as a compartment name, as it is already used to represent donor controlled flow type. Users should avoid using single small letters to name compartments, as EcoNet will feature other flow types in the near future and may utilize other small letters for this purpose. Capital single letters can be used without reservation.
EcoNet treats the space and tab characters equally, and users can use them freely to create well organized models. However no space should be used between a flow type and "=" character. So "c=2" and "c= 2" are valid while "c =2" and "c = 2" will give errors. There is no restriction for initial condition definitions, so "Zooplankton = 3" is a valid description.
All numerical values can be represented using scientific notation. EcoNet will interpret "0.012", "1.2e-2", ".012", ".12e-1", "12e-3" as the same value 0.012. Rational numbers are not accepted. For example, use ".25" instead of "1/4".

While flexibility is a great feature, it also enables users to create disorganized but functional models. So we equipped EcoNet a good error tracking feature that generates meaningful error messages when EcoNet notices mistakes in the model. For example, miss-spelling a compartment name, say zooplankton, when defining its initial condition will receive the following complaint from EcoNet: "No initial condition exists for compartment zooplankton".

Next: How to run an EcoNet model?

DHTML Menu By Milonic JavaScript