20 Structural Model Syntax
IQR Tools implements a general and powerful ODE and biochemical reaction expression based model description language, allowing to describe most models used in systems biology, systems pharmacology, and pharmacometrics. Tools are available to support the development, manipulation, and simulation of models.
Models are coded in plain text files and can be formulated in two different representations, i.e. ODE based or using biochemical reaction representation. Often, a dosing definition needs to be combined with the structural model to build the complete model for a particular application.
This section contains technical details on
- Model representation elements
- Predefined mathematical function to be used in model equations (#functions)
- Model and dosing objects
20.1 Model sections
An IQRmodel is defined by a number of model sections:
| Section | Description |
|---|---|
| MODEL NAME | Name of the model |
| MODEL NOTES | Notes about the purpose, background, and properties of the model |
| MODEL STATES | Description of ODEs and initial conditions (ODE-based only) |
| MODEL STATE INFORMATION | Description of ODEs and initial conditions (biochemical reaction representation only) |
| MODEL PARAMETERS | Description of model parameters |
| MODEL VARIABLES | Description of model variables |
| MODEL REACTIONS | Description of model reactions |
| MODEL FUNCTIONS | Description of functions used in the model |
| MODEL EVENTS | Description of model events (instant changes in state variables and parameter values) |
| MODEL C FUNCTIONS | Optional model section, allowing to define relatively arbitrary C code functions |
Note that depending on which model formulation is used, the some elements differ and it is is also recommended to indicate the formulation with an appropriate file suffix:
ODE based models IQRmodels using an ODE-based description contain the
MODEL STATESsection but noMODEL STATE INFORMATIONsection. Each model section apart fromMODEL STATES, can potentially be left empty. However, the empty sections should be kept in the model and not be removed. ODE-based models are saved in .txt files.Biochemical reaction representation IQRmodels using the biochemical reaction representaion only contain “MODEL STATE INFORMATION” section but no
MODEL STATESsection. Each model section apart fromMODEL STATE INFORMATIONandMODEL REACTION, can potentially be left empty. However, the empty sections should be kept in the model and not be removed.
Each model section starts with 10 stars in the (i.e., **********) followed by the name of the section written with capital letters. Comments can be included in the model description with a “#”-character, either on an empty row or at the end of the row on which a component of the model is defined. However, for an IQRmodel described by ODEs (ie., not a biochemical model description), it is not possible to define comments on the same row as initial conditions (the model may still be simulated but comments will not be saved).
20.1.1 Model name
The name of an IQRmodel should be short, descriptive, and written on a single line of the model txt-file.
20.1.2 Model notes
In this section the purpose, background, and properties of the model should be described in sufficient detail. There is no upper limit for the number of text rows in this section.
20.1.3 Model states
In the MODEL STATES section the ordinary differential equations (ODEs) and initial conditions of the model are defined.
Each ODE is defined on a separate row starting with d/dt(STATE_NAME), where STATE_NAME is the name of the state variable
(typically representing the concentration or number of molecules) whose time evolution is described by the ODE.
On the right hand side of the ODE are model terms for reactions and inputs affecting the state variable. A typical example is:
where STATE_A is the name of the state variable and R0 and R1 are reactions (defined in the “Model reactions” section).
Each model has to contain at least one ODE, and there is no upper limit for the number of (potentially non-linear and coupled) ODEs in the model.
The right-hand-side of the ODEs may be composed of reactions, variables, inputs, state variables, and parameters.
However, analysis functions in which the stoichiometric matrix is computed only use the reactions on the right-hand-side of the ODEs.
The initial conditions (ICs) for the state variables should be defined after the ODEs.
Each IC is defined on a separate row starting with STATE_NAME(0), where STATE_NAME is the name of the state variable.
A typical example is:
which means that state variable STATE_A is set to 100 at time t=0.
At time points other than t=0 the value of state variables can be defined in the MODEL EVENTS section.
If the IC of a state variable is not defined it is by default set to 0.
The RHS of an IC can either be a numeric value or a parameter.
An advantage of defining the RHS with a parameter is that the value of the IC may be estimated from data.
It is not possible to included comments on the same rows as ICs, but any comments should instead be added at the end of the corresponding ODE.
20.1.4 Model state information
In the MODEL STATE INFORMATION section only the initial conditions of state variables are defined.
The initial conditions are defined in the same way as for models on the text format, but comments may be included at the end of each row for initial conditions.
It is also possible to define ODEs explicitly in biochemical reaction models, with the same syntax as for models on the text format, and it is possible to mix the two approaches for defining ODEs.
20.1.5 Model parameters
The model parameters are defined in the MODEL PARAMETERS section, with one parameter per row starting with the name of the parameter on the left-hand-side and the value of the parameter on the right-hand-side.
A typical example is:
where parameter k is defined to be equal to 20.
Model parameters that have been defined in the Model parameters section can be used in reactions, variables, ODEs, and used as input arguments in functions. It is possible to change the value of parameters during model simulations by defining events in the Model events section.
20.1.6 Model variables
Model variables are defined in the MODEL VARIABLES section of the model description text, with one row for each variable.
A typical example is:
where variable v1 is defined to be equal to the value of parameter k1 plus 10 times the value of parameter k2.
The right-hand-side of variables can contain state variables, parameters, and functions.
For most practical purposes there is no difference between variables and reactions, except for that variables are not considered as reactions by functions with which the stoichiometric matrix is computed.
Reactions may be functions of variables (in the MODEL REACTIONS section”), but reactions cannot be used to define a variable.
When fitting a model to data, model predictions to be compared to observations need to be defined as model outputs, i.e. variables named OUTPUT1, OUTPUT2, OUTPUT3, etc.
The right-hand-side of an output definitions should not contain mathematical expressions, but only a single pre-defined variable. For example:
********** MODEL VARIABLES
Cc = Ac / Vc # (ng/ml) Plasma concentration
OUTPUT1 = Cc # (ng/ml) Output variable where Ac, Vc, and Cc are the amount, volume, and concentration of the drug in the central compartment, respectively.
Models can contain an arbitrary number of outputs, and the outputs must be sequentially defined starting from 1 (i.e., OUTPUT1, OUTPUT2, OUTPUT3, etc.). Output variables are not allowed to depend on dosing input components.
20.1.7 Model reactions
For ODE models, the model reaction rates to describe the state changes in the ODE equations can be defined in this section of the model description text, with one row for each reaction. However, this is not mandatory. A typical example is:
where reaction r1 is defined to be equal to the value of parameter kA times the value of state variable STATE_A.
A reaction can be defined as reversible by including a flag at the end of the row of a reaction (but before the comment if any), for example:
********** MODEL REACTIONS
r1 = kA * STATE_A - Emax * STATE_B /(KM + STATE_B) {reversible} # comment about reaction r1where kA, Emax, and KM are parameters and STATE_A and STATE_B are state variables.
The reversible flag is not important for simulations of the model, but only for function used to infer the stoichiometric matrix.
For models on the biochamical reaction format both the reaction rate expressions and the stoichiometry are defined in the Model reactions section.
For example, a reversible reaction R1 for the binding of state variables A and B into a complex C may be defined as follows:
where k1 and k2 are parameters, A, B, and C are state variables, vf is the reaction in the forward direction (from C to A and B)
and vr is the reaction in the reverse direction (from A and B to C).
Irreversible reactions can be defined by leaving one side of the arrow empty as for reaction R2 and R3 below:
where the forward reaction for R2 is constant.
20.1.8 Model functions
In the MODEL FUNCTION section of the IQRmodel description it is possible for the user to define own functions.
Examples may for example be kinetic rate laws and other complicated expressions that are repeatedly used in the model.
A function for saturation (Michaelis-Menten) kinetics may for example be defined:
where x is the state variable and kA and kB are parameters.
Note that parameters defined in the MODEL PARAMETERS section cannot be directly used within functions if not explicitly defined as function arguments.
Only basic operators such as “+”, “-”, “sin”, or “in” and predefined toolbox functions (e.g., “piecewise”) should be used in functions.
20.1.9 Model events
Events are defined in the MODEL EVENTS section of the model description.
Events can be used to define discrete state events (i.e., instant changes of state variable values) and changes in parameter values.
For example, assume that a state variable STATE_A cannot take values smaller than 0.
Therefore, if STATE_A reaches values smaller than 0 it is reset to 0.
We also assume that in such cases another state variable, STATE_B, should be reset to 1.
Such an event can be implemented as:
It is also possible to use time as an explicit argument in model events or to use expressions for the value to be set, for example:
where the value of parameter k1 is increased by 5 when time equals 10.
An arbitrary number of events that can be defined in a model, as well as and arbitrary number of state variables that should be updated when an event is triggered.
The following help functions are useful in the definition of piecewise statements:
gt (greater than), ge (greater or equal than), lt (less than), le (less or equal than), and (and-function for logical statements), and or (or-function for logical statements).
20.1.10 Model C functions
IQR Tools allows the user to define C code functions inside an IQRmodel.
This is done in the MODEL C FUNCTIONS section, which is the only optional section in IQRmodels.
The use of these C functions should be handled with care and the user needs to know what he or she is doing. But the availability of this option increases the flexibility of IQRmodels considerably. It is required that the C code functions that are called from inside one of the other model sections need to return a double value.
********** MODEL C FUNCTIONS
/* test3 is called by test1 */
void test3() {
Rprintf("Hello World\n");
}
/* test1 can be called from within the other model sections */
double test1() {
test3()
return(1);
}
/* test2 can be called from within the other model sections */
double test2(double x, double y) {
if (x > y) return(x);
return(y);
}Text that is entered into the MODEL C FUNCTIONS section is copied as is into the C code model file.
20.2 Pre-defined functions
| Function | Description |
|---|---|
| ^ | Power operator |
| abs | Absolute value |
| cos | Cosine |
| eq | Equal to |
| exp | Natural exponential function |
| ge | Greater than or equal to |
| gt | Greater than |
| interp0 | Zero order interpolation |
| interp1 | First order (linear) interpolation |
| interpcs | Cubic spline interpolation |
| le | Less than or equal to |
| lt | Less than |
| log | Natural logarithm |
| max | Maximum of array elements |
| min | Minimum of array elements |
| mod | Modulus |
| piecewise | If-then-else statement |
| sin | Sine |
| sqrt | Square root |
| tan | Tangent |
| nthroot | n-th root |
20.3 IQRmodel object
Models in IQR Tools are typically defined in a text editor and the model is saved as a text file with extension “.txt” (the extension is however arbitrary).
However, once a model has been loaded with IQRmodel() it is an IQRmodel object and information about specific model parts can also be directly obtained in R.
For model details the name of the R model object followed by an “$”-character is stated in the R console window (e.g, “modelA$parameters”).
The IQRmodel structure consists of the following parts (note that a few model parts also contain sub-parts):
| Model parts | Model sub-parts |
|---|---|
| name | - |
| notes | - |
| states | name, IC, ODE, type, compartment, unittype, notes |
| parameters | name, value, type, compartment, unittype, notes, estimate, regressor |
| variables | name, formula, type, compartment, unittype, notes |
| reactions | name, formula, notes, reversible, fast |
| events | name, trigger, assignment (variable and formula), notes |
| functions | name, arguments, formula, notes |
| inputs | IMPORTANT: only used internally, inputs converted to variables at model import |
| outputs | name, formula, notes, varindex |
| Cfunctions | Contains only a string with the C code functions. Only present if C code functions available |