Model Building and Model Components
After having made yourself familiar in the previous chapters with the building block concept and with the general structure of the program and projects (“MoBi® - First Steps”), this section describes the practical approach how to build MoBi® models by stepwise entering content into the building blocks. Also, this knowledge is of use to upgrade models imported from PK-Sim®, as will be described in Setting up a Simulation.
Always watch for the helpful tool tips that appear when hovering for a few seconds with the mouse pointer over an input box or its description.
MoBi® - Projects
New Project
Your first step is to create a new project.
To create a new project select New Project on the File ribbon tab or alternatively press Ctrl+N.
The ribbon bar Modeling & Simulation with the different Ribbon Groups for creation of building blocks, simulations, and more will appear. Empty building blocks are now present for Molecules, Reactions, Spatial Structures, Passive Transports, Observers, and Events and are shown in the Building Block Explorer. You can now edit a building block by double-clicking the corresponding entry.
Other project actions in the File tab
Open a Project
To open a project select Open Project (Ctrl+O) on the File tab.
A File Selection Dialog will open in which a project file (mbp3 file) can be selected. Alternatively, you can also choose one of the Recent documents.
After selection, the MoBi® project is opened.
You can alter the Number of recently opened projects: on the Utilities tab click Options and select the General tab.
Only one project can be opened at a time! This project may, however, contain several simulations. To work on more than one project in parallel, MoBi® can be started several times.
Close a Project
Close a project by selecting Close Project in the File tab. A confirmation dialog opens if there are unsaved changes.
Save a Project
Parameters, Formulas, and Tags
In all building blocks that are now created, there may be a need to create and edit parameters, to work with formulas or other elements like tables. This section describes the general options you have for parameters and formulas, and the general procedures to work with them.
Parameters are typically listed in a separate tabbed view, named "Parameters"; compare the figures within this Chapter for their exact location which will vary, depending on the building block. A parameter is used to describe physical or physiological properties of a molecule, a reaction or transport, a spatial structure, an event or an application.
Parameters can be newly created, copied, moved, edited, or loaded from a pkml file:
Instead of newly creating a parameter, you may also load it from a file. Use the Load Parameter button or context menu entry for this purpose and select a pkml file (e.g., a previously saved building block or simulation) that already contains a suitable parameter.
A third option is to copy and paste parameters between building block items by pressing Ctrl+C (on the source parameter, like from an already entered molecule or reaction) and Ctrl+V after moving to the target area and after clicking into the empty parameter space. Instead of Ctrl+C to copy a parameter, you can use Ctrl+X to cut a parameter from its current position.
Within the different building blocks, there are slight differences in the procedure and in the selectable options which will be explained in the corresponding sections in this chapter. In the Molecules and Reactions building blocks, parameters may be of different types: Local, Global, and Property. As these names already suggest, the differences are the following:
Parameters defined as Local can only be used locally, i.e., within the corresponding reaction or for a molecule where a local parameter is defined.
Parameters defined as Global can also be used in other formulas, i.e., they appear in the reference lists described in Working with Formulas. Furthermore, they are located in different places of a simulation hierarchy, as described in Molecular Properties.
Parameters defined as Property are identical to Global parameters except that they will not be listed and set in the parameter start values.
A change of the parameter type will influence the path wherever this parameter is used in a formula (compare Working with Formulas).
Furthermore, this different path will make this parameter appear in different locations within the simulation hierarchy. Global parameters appear below the reaction list in the top level hierarchy, local parameters below the reaction list in the container level where the reaction occurs.
Any parameter needs to have a Dimension assigned to it or the option Dimensionless has to be selected from the Dimension combobox. This feature is needed for the automatic dimension validation provided by MoBi®. Typical dimensions are concentration, volume, time, or the more complex dimensions for flow or rate constants.
A parameter can be assigned to a Group using the combobox of the field. This information is only used for display purposes to show the list of parameters in e.g. a given container and will enable a grouped view instead of default flat view. You can switch from flat to grouped view by ticking the Group parameters box.
In the combobox of the field Formula Type, you can select if the parameter is defined as:
a constant, consisting of a numeric value and a unit;
a formula, having a formula name and a formula string (i.e., a mathematical expression) including references to the formula items;
a table, using individual data pairs from which a value is interpolated over the simulated time;
a value distributed around a constant value or between two limits (only available for parameters of spatial structure containers);
a calculation method parameter, whose formula will be defined depending on the selected calculation method of each molecule in the model (only available for parameter of spatial structure container). Currently, this calculation method cannot be edited within MoBi® and is imported from PK-Sim® together with the parameter.
In the bottom part of the Create or Edit window are several input options that have different effects on the parameter:
For all parameter types, a description can be added into the input box at the bottom, for example to quote a reference. Clicking into the text field will open an edit dialog into which you can enter or paste any text of your choice.
You may also add tags to any parameter which is done by first clicking the Tags
tab in the parameter window. This will switch you to the tag list view.
To add a tag, click the "Add Tag" button and enter the tag in the input box.
To delete a tag, click the symbol that appears behind every tag in the list.
Parameter tags are used for the evaluation of formulas of the type "Sum", see Sum Formulas. The general rationale behind tags is explained in, How Tags are used.
Each parameter can be edited by selecting it from the parameter list, upon which the parameter edit dialog right of the list is updated to show the selected parameter, then allowing to edit it.
Working with Constant and Distributed Parameters
A constant parameter is simply entered as a number in the field Value. You may use decimal points, exponential notation, and minus signs (e.g., 2.34; 1.2E-6;
-150). Next to the value, its unit will be shown; the default unit is selected by your choice in the Dimension field, but it can be changed to other units listed in the combobox, e.g. from 1/min to 1/sec or 1/h.
Examples for constant parameters are given below, like the property "Molecular weight" for a molecule (see Molecule Parameters) or the rate constant for a reaction (see Reaction Kinetics).
Distributed parameters (only available for parameters of spatial structure containers) describe a variation around a constant value or between two numerical limits. Within a given MoBi® simulation, a distributed parameter has a fixed value (default defined by the value in the field value). A distributed parameter can be used only to calculate the percentile of the parameter value given a certain distribution. Distributed parameters are useful if population statistical data are to be defined within a model. To define such a parameter, use the Create Distributed Parameter command from the context menu of a spatial structure item, like for containers (e.g. organ sizes) or neighborhoods (e.g., blood flow rate). In addition to what is entered for constant parameters, the Distribution Type has to be selected. Available options are:
Discrete Distribution, which is identical to a constant parameter; this feature is implemented for the purpose of simply disabling the distribution function without going through the parameter creation process again.
Uniform Distribution, where a parameter will be uniformly distributed between a Minimum and a Maximum, both have to be defined as numeric values. This is done by the same rules for value and units as used for the constant parameter value.
Normal Distribution, where a parameter is varied around a Mean value using a Standard Deviation - both values have to be specified.
LogNormal Distribution, where a parameter is logarithmically varied around a Mean value using a Geometric Standard Deviation - both values have to be entered.
If you use one of the different distributions, a percentile will be automatically calculated for the parameter value define in field value given the defined distribution. The functionality of this feature is particularly useful in combination with the script toolboxes for MoBi®.
Working with Formulas
A parameter can be defined by a formula that may also use other parameters. A formula string defines the formula. Additionally to parameters, formulas are used in the kinetics equations of reactions and transport processes as well as in the monitor equation of observers. See the corresponding sections for a description. To define a formula, select Formula in the combobox Formula Type.
It is a good idea to use a name related to the object where the formula is used (e.g., parameter, reaction, observer) - you may even use identical names here.
Useful workflows with parameter aliases or with reference paths to aliases are described below, see Reaction Kinetics and Passive Transports.
In a formula, the following characters may be used:
numbers can be entered as described for constants
the arithmetic operation signs +, -, *, /, ^ (for exponents)
round brackets ( )
the constants pi and e
the mathematical functions ACOS, ASIN, ATAN, COS, COSH, EXP, LN, LOG (identical to LN, natural logarithm), LOG10, MAX, MIN, POW, SIN, SINH, SQRT, TAN, TANH; if two operators are required (MAX, MIN, POW), a semicolon is used for separation, e.g., POW(3;2) which corresponds to 3^2
the random number generator functions RND and SRND, both to be used with the dummy argument ()
if conditions, using the notation
<condition> ? <formula string for true> : <formula string for false>in the conditions, the operators <, >, <>, >=, <=, = ; alternatively: LT, GT, NEQ, GEQ, LEQ, EQ, for which the use is
<function>(<expression1>;<expression2>)conditions can be composed out of sub-conditions that are logically connected by AND, OR, or inverted by NOT. An alternative symbol for AND is &; an alternative symbol for OR is |. Besides logical conditions, the numbers 0 and 1 can be used as arguments.
The above mathematical functions are defined as in the C programming language. For standard reaction kinetic models, these functions are not required at all. It is recommended to use events rather than "if conditions" in a formula.
Furthermore, defined aliases can be used in a formula as described in the next paragraph.
As opposed to mathematical functions, constants, and operators aliases are case sensitive.
Below the formula name and above the formula string, there is a Reference Table showing a header line above the columns named Alias, Path, and Dimension. On the right hand side of the reference table, there is a second table (separated by a vertical bar) titled References to add. From this left part, references are moved to the right Reference Table part by drag & drop.
In some cases, e.g. when working with formula-defined molecule parameters, it may be helpful to expand this window to have enough working space. To do so, use the vertical bars between the window sections and drag them with the mouse.
References can be of two different kinds:
An absolute path reference specifying the complete path to a referenced object (e.g., parameter, another formula). An example for this would be "Organism| Organ|Volume".
A relative path reference specifying the truncated path relative to the current formula. The expression ".." is used for "one level up", using a structure similar to that of file systems paths. An example for such a relative reference would be "..|..|Volume".
You need to choose between absolute and relative path by selecting the corresponding radio button in the References to add a section of the window. If you select relative, you will be asked for a Local Reference Point. This reference point depends on the level on which you create your formula (e.g., the organism or an organ level) and may be specified in the expandable selection tree (see below). Recommendations of how to choose your reference point are given within this chapter. Click OK to finalize your selection.
The selected local reference point will be displayed with its absolute path in the "References to add" window. In case you need to correct or alter the local reference point, click on the ... icon right of the path. This will re-open the reference point selection window.
To add a reference to a formula, after having selected the reference point:
Find the reference by name in the Possible Referenced Objects tree. Click on the + signs in the displayed tree to get to deeper levels of selectable points.
Click on the object's name, then drag it to the Reference Table area left to it; drop it there by releasing the mouse button. The object will be added to the list, usually with its name as the alias. If that name already exists in the list, the alias name is automatically renamed by adding a number. The path and dimension of the object are also added.
Not all entries in the tree are allowed to be moved to the left, depending on the context of the formula. A + sign displayed next to the mouse pointer indicates an allowed reference.
If needed, you may edit the alias name of the object manually. Alias names need to be identical to the names that are used in the formula string. Simply click on the alias name and change or override (or copy/paste) the name. For example, if you added several "Concentration" parameters from different molecules to a reaction kinetics equation, it may be helpful to manually add the molecule name next to them.
In the same way as for aliases, it is also an option to manually edit the path. However, the standard procedure would be to remove the object and add it again, using a new local reference point.
Dimensions can be changed by clicking on the displayed dimension and selecting a different one from the combobox.
A reference path may also contain a global part, like "|MOLECULE", which is recognizable by being written in all capital letters. The reference to "|MOLECULE" means that this part of the path refers to a parameter or property of the currently evaluated molecule, whatever its name. This is useful in formulas that are computed for all molecules present in a container. Compare the formulas in Observers or Passive Transports. A global reference is selected automatically by MoBi® where appropriate.
To remove an object from the reference list, right-click it and select Removefrom the context menu.
Clicking on the Formulas tab in the edit window will show a list of all formulas used in the reaction building block. This list is a quick overview of formula names within one building block. Clicking on a formula in the list will show the references and the equation for the selected formula. Right-clicking on a formula in the list opens a context menu that allows you to Rename, Clone and Remove formulas.
Sum Formulas
In addition to the formulas described in the previous section, sum formulas can be used to calculate sums of a specified parameter name. As a selection criterion, parameter tags can be specified.
To define a parameter or a reaction by a sum formula, use the following procedure:
Select Sum Formula in Formula Type combobox.
In the Formula Name combobox, you may alternatively select an existing sum formula name.
In the Parameter Criteria field, right click into the empty white space and select either a New match tag condition. (The New not match tag condition is available too if needed). You will then be asked to enter a tag to match; or select one after clicking the combobox arrow. All parameters carrying the specified condition will be summed; if more than one condition is used, they will be connected with a logical AND. The general rationale behind tags is explained in (How Tags are used](#how-tags-are-used).
Conditions can also be removed using the context menu that appears when right-clicking into the white space in the Parameter Criteria field.
Working with Tables
A parameter can be defined by a table that is made up out of pairs of simulation- time and corresponding functional value. The parameter value as a function of time that is used in the simulation will be interpolated between these values. To enter a table:
Select Table as Formula Type. A table layout will open below the Formula Type combobox.
In the Formula Name combobox, you may alternatively select an existing table formula name.
A formula name needs to be entered or selected before entering any value points.
To add a data point, click the Add Value Point button.
Enter a time value in the X (Time) input box and a parameter value in the Y value input box. Units of the values can be selected as described for a constant parameter value.
You may check Restart Solver box in case the solver generates errors when arriving at these time points.
More data points can be entered by clicking Add Value Point again, or by clicking on the button in the right to the values lines. You can delete a data pair by clicking the delete button .
If you would like to use the first derivative of the interpolation, check Use Derivative Values. Values before the first and after the last data point of the series are set to 0.
Data points cannot be edited, but have to be deleted and newly entered. Data point units can be changed, leading to a recalculation of the associated value to its new unit.
Working with Table Formulas with Offset
A table described in Working with Tables may need to be reused and shifted by a constant time value. For example, PK-Sim® uses this logic to build up repeated advanced application protocols (compare PK-Sim® - Administration Protocols). To enter a table formula with offset:
Select Table Formula with Offset as Formula Type.
In the Formula Name combobox, you may select an existing table formula with offset.
Below the table object path, there is a selection to a path with an offset object. Upon clicking the "..." icon, you can select one such object from a path tree. This must be a parameter containing a time, i.e., its dimension has to be Time.
State Variable Parameters
How Tags are used
Containers and neighborhoods within a spatial structure, elements of an application, or parameters may be labelled with tags. These tags, together with the name given to a container or neighborhood, may be used for selectively enabling observers, active or passive transports, or events. They are used for formula evaluations of the formula type "sum".
Tags can be entered when creating or editing a tag-carrying entity. The detailed procedures are described within this chapter in the corresponding sections describing spatial structures, observers, events, or parameters. Generally, one or more names are entered in a special input window of the corresponding entity.
Tags are evaluated in fields of observers, transports, or event groups titled "In Container with" or "Between Containers with". More than one condition can be used, being one of the following classes:
Match tag condition: the condition is fulfilled when the tag name is matched.
Not match tag condition: the condition is fulfilled when the tag name is not matched.
Match all tag condition: the condition is fulfilled for all tags (not available for transport processes or sum formulas).
More than one condition can be combined for evaluation; the combinations are connected with a logical AND. The detailed procedures when and how to enter tag conditions are described in this chapter (Sum Formulas, Transport Processes, Observers, Events and Applications).
Models generated in PK-Sim® make extensive use of tags: For example, open a PK-Sim® model and look under Passive Transports for one part of the blood flow through the organs of an organism called "MassTransferBloodPool2OrgPl". This is a passive transport process that occurs from the arterial plasma compartment to the plasma compartments of all organs except for the lung. Consequently, this transport process is occurring under the following conditions:
Source container: tagged with "Arterial Blood" and tagged with "Plasma".
Target container: tagged with "Plasma" and not tagged with "Arterial Blood" and not tagged with "Lung".
Similarly, observers or events can be included or excluded from being created in different parts of the spatial structure. The molecule observer "Fraction excreted", for example, makes use of the tag "Urine", so this observer is only created in the urine container.
Spatial Structures
A spatial structure can be an organism consisting of organs, cells and other substructures. Alternatively, it can be a laboratory setup, like a test tube or a flow chamber with interconnected compartments. Typically, each structure is described by physical parameters, in particular by volume. Containers of a spatial structure can be defined as Physical, which may contain molecules in the simulation. They can also be defined as Logical, meaning they do not represent a real container with molecules but instead just representing a grouping of sub-containers. Containers are also grouped in categories like Organism, Organ, and others. This way, the physical makeup of an organism is described.
In the process of this and the next sections of this chapter, you will create an example project. An already completed project file named "ManualModel_Sim.mbp3" is automatically installed together with MoBi® in the default program data directory. The entry "Examples" in the program start menu in the "MoBi" group will lead you to the proper path.
A very simple spatial structure named "Organism" has already been automatically created by executing the New Project command. For becoming familiar with editing spatial structures, proceed further:
Click on the + sign next to "Spatial Structures" in the Building Block Explorer.
Edit the "Organism" by double-clicking on it or by using the Edit command of the context menu that appears after right-clicking on Organism.
The screen should now look as shown in the following figure:
In the Edit window of a spatial structure, you have a diagram area like in the
Edit Reactions mode, which is used here to display the physical and logical arrangement of organs or reaction vials and their interactions. On the left of the Diagram Area is a miniature view of the entire diagram which is thought to be helpful in navigating within larger spatial structures. Below the miniature view is a tree view of the spatial structure including any neighborhoods.
Creating a Spatial Structure
For continuing with our example project, construct a simple spatial structure which consists of a surrounding top level container having two interconnected sub-containers. A common tag will be added to both sub-containers which will be used later for restricting some computations (e.g., observers) to be only done for the two sub-containers. Tags are also used for restricting events or selecting source and target for transport processes. Check the corresponding sections for their use.
You will be asked for a new name. Enter "BigVial" and press Enter or click OK.
A new window named "New Container" opens, similar to the creation of molecules or reactions. Enter "Vial1" as name, and leave the Container Type on Organ. Select Physical Container in the right combobox below the name input box.
Click the Add Tag button below the Container Type. You are asked for a tag name. Enter "Obs" as a tag name.
Finally, click OK or press Enter.
After this step, the top container "BigVial" has expanded in the Diagram Area, and a new oval "Vial1" has appeared within the expanded range. Now, repeat the "Create Container" steps 4 to 7. Make sure to right-click into the green-shaded "BigVial" area surrounding "Vial1", but not into "Vial1" and not in the white area outside the outer "BigVial"! A good place would be some distance to the right of "Vial1". Name the second sub-container "Vial2" and tag it also with "Obs". You can then expand the view by dragging "Vial2" to a more distant point from "Vial1" using the mouse. The screen should now look like this:
Any container or sub-container may have parameters associated with it. They can describe physical or biological properties of the container that are required for processes like transports or reactions. What is needed in our practice model is the volume parameter which is used to calculate concentrations required for kinetic equations or for plotting concentrations after a simulation has been performed.
As for molecules or reactions, parameters become accessible after clicking the "Parameters" tab in the lower section of the edit window. To enter a spatial structure parameter:
Click on "BigVial" either in the Diagram Area or in the edit tree.
Click the "Parameters" tab.
Enter "Volume" into the Name input box, select Volume in the Dimension input box, then enter "1" into the Value input box. The Formula Type remains on "Constant".
Finally, click OK, and the new parameter "Volume" will appear in the parameter list.
Repeat this procedure for the sub-containers "Vial1" and "Vial2", but set their volume values to smaller values, like 0.1 and 0.2 liters.
A Spatial Structure (whole or in part) can also be loaded from or saved to a template (pkml) file. Right-clicking into the Diagram Area will open a context menu that show a Load Container and a Save As entry.
To save a Container of a Spatial Structure as pkml file:
Right-click on it in the Diagram Area or in the tree view, and select Save As from the context menu.
In the file browser window that will open, select a location where it is saved and choose a name to save it.
The selected container, including all its sub-containers, parameters and neighborhoods between the sub-containers will be saved.
To load a Container into a Spatial Structure from a pkml file:
Right-click onto the desired target position for it in the Diagram Area or in the tree view, and select Load Container from the context menu.
Select a folder and then a pkml file from the file browser window that will open.
If the pkml files contains more than one container, select the desired container.
The selected container, including all its sub-containers and neighborhoods between the sub-containers, will be loaded. If duplicate names occur, you may be asked to enter a new name. Any desired neighborhood relations (see Creating Neighborhoods) to already existing containers in the spatial structure will have to be newly created.
You may also load and save an entire Spatial Structure building block as pkml file. This is described in detail for molecules in Loading, Editing, and Saving Molecules and applies also for a spatial structure.
A collection of template files with predefined building blocks is automatically installed together with MoBi® in the default program data directory. The entry "Templates" in the program start menu in the "MoBi" program group will lead you to the proper path.
Creating Neighborhoods
Within a spatial structure, transport processes may occur (see Active Transporter Molecules or Passive Transports). If you plan to define a transport process within a project, it is necessary to define a neighborhood for a transport to become active. Creating a neighborhood works similar to connecting reaction partners with a reaction triangle:
Hold the left mouse button and drag the connection, displayed by a line, to the container you want to have as a second neighborhood partner until the line hits its rim. In our case, connect "Vial1" with "Vial2".
You will be asked for a neighborhood name that is required to proceed. Enter "V1V2Connection" and click OK. In the Diagram Area, the thin initial line is replaced by a bold line showing a circle half-way in the connection. Also, the neighborhood appears in the tree view of the spatial structure.
The screen now looks like this:
Like the containers, the neighborhood may contain parameters and may carry tags. These parameters could describe the physical makeup of a neighborhood, and these values may later be used in the formulas of transport processes. If you look at simulations imported from PK-Sim®, you will see examples for such parameters. The spatial structure of such a PBPK model is much more complex, but editing it works in the same way as described for our simple example.
Molecules
The Molecules building block contains all molecules with their default start values, molecule-specific parameters and properties. A molecule has a name, typically the name of the compound. Parameters and properties can be defined by you to describe the physico-chemistry, like solubility or lipophilicity. These parameters may later be used in reactions, passive and active transport processes, or may influence events. Also, active transporter molecules and transport processes are defined for each molecule, if relevant for the model.
Start by opening a Molecules building block for editing. In the Building Block Explorer, open the Molecules folder and edit the Molecules building block by either right-clicking it and selecting "Edit", or by double-clicking on it. A new tab with an empty space will open. This is the work space where you can add new molecules or load molecules from other projects. You may notice that the ribbon of the MoBi® window has changed, being tabbed "Edit Molecule", to offer you clickable ribbon buttons for molecule-related actions (compare in Enter Molecules).
Creating New Molecules
To create a new molecule:
Enter a molecule name into the "Name" input box.
Alternatively, a molecule can be created based on a PK-Sim® template. This can be achieved by using the button PK-Sim Molecule in the Add ribbon or Add PK-Sim Molecule from the context menu in the diagram area.
Enter a name for the PK-Sim molecule and the four physicochemical properties as listed.
At this point, you may already input a value for the "Default Start Amount" which is set to zero by default. Also, you may define molecule parameters after clicking on the "Parameters" tab of the "New Molecule" window (see below). Both operations, however, can also be done after the molecule is created (see below), which is finalized by pressing the Enter key or by clicking OK. The newly created molecule name now appears in the left part of the Molecules edit tab, and a tab on the right shows the properties of the molecule.
Loading, Editing, and Saving Molecules
Alternatively to newly creating a molecule, molecules can be loaded from a pkml file. This file can be
a PK-Sim® export containing molecules (see Export to *.pkml file for MoBi®, for how to create such a file),
an entire previously saved MoBi® simulation,
a saved Molecules building block from a previous project,
or a previously saved molecule file.
A collection of template files with predefined building blocks is automatically installed together with MoBi® in the default program data directory. The entry "Templates" in the program start menu in the MoBi program group will lead you to the proper path.
Use one of such files an proceed in the following way:
Select a folder and then a pkml file from the file browser window that will open.
If the pkml file contains more than one molecule, select one or more from the list that is displayed. If one or more molecule names are already in use in the current project, you will be asked for alternative names.
You can edit the molecule properties for the molecule in the tree that is currently being highlighted.
The Default Start Amount determines what default value will be used whenever "Molecule Start Values" are created (see “Molecule Start Values”). The value should be left on 0 for all molecules which only will be created in the process of the simulation. For complex spatial structures, it might be an alternative strategy to set all default start amount values to 0 and set everything manually in the molecule start values for those containers where a molecule is present in known concentrations.
The Used Calculation Methods at the bottom right of the edit window shows three comboboxes for the selection of calculation methods for the distribution of the molecule within a model exported from PK-Sim®. The calculation method defines which method is used to calculate parameter values of parameters located in the "Spatial Structure" ("MoleculeProperties") which have the Formula Type Calculation Method. These selections are only needed if you want to use distribution methods from PK-Sim®. Otherwise, leave them on No Calculation Method. For further information on this subject, please refer to the discussion of the different distribution models in the PK-Sim® manual (Simulations). If you select a certain "Calculation Method" you can get tool tip information on the equations and specific parameters used in the "Calculation Method" by hovering with the mouse over the "Category" entry.
To save a molecule as pkml file:
Right-click on its name in the molecules tree, and select Save As from the context menu.
Select a location where it is saved in the file browser window that will open and select a name to save it.
In a similar way, you can save an entire molecules building block.
Go to the Building Block Explorer, right-click your building block (the default name would be "Molecules", it would be the level under the building block group "Molecules"), and select Save As from the context menu.
Select a location where it is saved in the file browser window that will open and select a name to save it.
You can load such a molecules building block into any project by right-clicking the building block group (top level) and selecting Load Molecules Building Block. Also, you can use any saved molecules building block to load individual molecules from it into other projects, using the Load Molecule function described above.
If you are frequently building models in MoBi® where new molecules have to be defined, it is a good idea to once configure your typical default molecule and save it in your working directory. You can then compile your molecules building blocks by repeatedly loading your default molecule and each time changing the name to your desired molecule names.
Any molecules building block can also be removed (i.e., deleted), renamed, or cloned (i.e., copied under a different name) using the corresponding context menu functions.
The above operations, including save and load, are functions available for all other building blocks through the context menu that appears on right-clicking with the mouse at the corresponding positions.
Molecule Parameters
Molecule parameters can created, loaded, copied, or changed after clicking on the Parameters tab in the right half of the window. For comprehensive information on parameters and parameter handling, see above Parameters, Formulas, and Tags.
A molecule parameter needs to have a name, a parameter type (Local, Property, or Global), a dimension, a value or a formula, and it may be a state variable.
A typical local parameter is "Concentration", defined by the formula "Amount/ Volume".
A typical property is "Molecular weight" which is used for calculating weight- based concentrations.
An example for a global parameter might be a total start amount from which the start amounts of differently bound molecules are calculated.
A description can be added into the input box a the bottom, like for giving a literature reference from where you obtained this value.
More examples for molecule parameters can be found by looking at a molecule in a simulation imported from PK-Sim®. If you enter a formula-defined or a state variable parameter, please refer to the general section defining how to use this functionality.
As an example, we create the property "Molecular weight" for the molecule created above.
Enter "Molecular weight" as parameter name.
Select the Parameter Type Property from the combobox and confirm the security question.
Select MolecularWeight in the Dimension combobox - you can narrow down your search by entering the first few characters after clicking this combobox field.
Leave "Formula Type" on Constant and enter the molecule's molecular weight in g/mol into the "Value" input box.
Finally, press the Enter key or click OK. The screen should look like in the screen shot below.
As a second example, load the parameter "Concentration" from a PK-Sim® simulation export (see Export to *.pkml file for MoBi® for how to create such a file).
Click the Load Parameter button or select it from the context menu.
Select a pkml file that you previously generated in PK-Sim® and select Concentration from the list. This local parameter is defined by a formula, and it is useful to have it in every molecule which is later used in a reaction kinetic equation.
For a detailed description of the creation and use of formulas see below, Reactions.
Active Transporter
In addition to the molecules described so far, active transporter molecules and transport processes related to them can be created. Since their use requires that a spatial structure and neighborhoods have been created, they and the dependent active transport processes are described below in Active Transporter Molecules.
Reactions
In a Reactions building block, all (bio-)chemical reactions which are of interest for the current project are defined. Like a molecule, each reaction has to have a unique name, a reaction kinetics equation, may have parameters, and it also needs reaction partners.
Like in the Molecules section, you first need to select a reaction building block for editing.
In our newly created project, open the Reactions folder and edit the Reaction building block by either right-clicking it and selecting Edit, or by double- clicking on it.
A new tab with an empty diagram area will open. This is the work space where you can add new reactions and molecules or load reactions from other projects. Again, the ribbon of the MoBi® window changes to a reaction-related view, named "Edit Reaction".
Working with reactions is done mostly using the Reaction Diagram. We describe the most important features in this section, for more details see Diagrams Overview
Reactions and Molecules
When creating a simulation (see Setting up a Simulation) the reactions defined in this building block are combined with the molecules from the Molecules building block. When we use the term Molecule in this section we refer to Molecule names only, which define the relationship between the Reactions to the Molecules from the Molecules building block.
If you insert a molecule that has not yet been defined in the Molecules building block, this may cause an error later when setting up a simulation. Remember to define that molecule later.
To have access to molecules as reaction partners for the reactions you want to create, it is advisable to first insert the molecules that you need into the Diagram Area, our work space. Alternatively, you may insert the molecules after reactions are created. To insert molecules:
You can either enter a name manually into the "Molecule Name" input box, or select as many as you wish from the list below this input box. Multi-select is done in the standard Windows® way by keeping the Shift key (for a contiguous part of the list) or the Ctrl key pressed (for individual selection) followed by clicking with the mouse on the desired molecule range or molecule names.
Click OK to execute the operation. For each molecule, a green circular symbol appears in the diagram area.
The added molecules can be moved by the mouse within the diagram area. To do this, left-click a molecule on its dark-green center, hold the mouse button and drag it with the mouse. Release the mouse button when the molecule sits at its desired place.
To create a new reaction:
Enter a reaction name into the "Name" input box, e.g. "R1".
Next, you can choose the Formula Type from a combobox - by default, Formula is selected.
You may then continue to create reaction parameters (like rate constants) and the reaction formula, but that can be done later as well.
Finally, press Enter or click OK.
For completing our example and to get more practice, repeat steps 1 to 6 to enter a second reaction that you name "R2".
The blue circle, by default on the left, is where the educts are to be connected (see where already two reactions are present).
The green circle, by default on the right, is where the products are connected.
The red circle on the top is where reaction modifiers, like catalysts or inhibitors, are connected - i.e., those molecules that do not change in the course of the reaction, but influence the reaction kinetics.
Like molecules, reaction triangles can be dragged with the mouse to a desired position within the diagram area. Click into the grey center of a reaction triangle and hold the left mouse key to drag the reaction symbol.
Connecting Molecules and Reactions
Now you may want to connect molecules to the reaction and verify or change the stoichiometry. There are two ways to connect a molecule to a reaction as educt, product, or modifier:
You can either click on the corresponding circle of the reaction triangle (i.e., blue for educt) and drag it towards the desired molecule, holding the left mouse button pressed and releasing it when the connection line that is protruding from the triangle connects to the proper molecule.
Alternatively, you can drag the light-green rim of a molecule symbol towards the desired position of a reaction triangle until the connection line connects to the correct target circle.
In case a wrong connection is established, you can click on a connection, after which it is highlighted by light green squares, and then press the Delete key on the keyboard.
Now, continue and check the reaction's stoichiometry. If you have connected one or more molecules to the reaction, you should see them appearing in the properties tab of this reaction.
Click the reaction triangle. Below the Diagram area, the Properties Editor, a three-tabbed window, is shown.
Click the Properties tab, and you see the Alias names (how they will be used in the formula, see next section), the path, and the dimension of the amount of molecules .
Clicking on the Stoichiometry tab will list the educt and product stoichiometric coefficients. By default, these coefficients are set to 1, and you need to change that manually if your reaction has a different stoichiometry, e.g. if two molecules form a dimer.
Reaction Kinetics
You are now ready to define Reaction Parameters, like kinetic rate constants, Michaelis-Menten parameters (kcat or KM), or binding constants. These parameters will then be used for the equation that defines the reaction kinetics. A new reaction parameter is defined by the following procedure:
Click the Parameters tab in the edit reactions window.
Enter a parameter name, like "k1" as a first order rate constant in our example.
Select the parameter type (Local/Property/Global). For a rate constant only used in one single reaction, the recommendation is to choose Local, whereas Global is the right choice if several reactions need this parameter and you want to define it only once.
Select the proper dimension in the Dimension combobox, which is Inversed Time for the first order rate constant in our example.
Enter a value for your parameter, 0.01 as an example. If needed, select a different dimension unit in the combobox to the right of the value input box. The parameter may also be defined by a formula or data table, or you may make the parameter state variable (compare Parameters, Formulas, and Tags).
Optionally you may enter a description.
Finally, press Enter or click OK.
Alternatively to entering it manually, you may also load it from a file or copy and paste it from another reaction in the same way as described above, see Parameters, Formulas, and Tags. Any setting of a parameter can be edited later, and as many parameters as you need can be added to a reaction. The figure below shows what the screen would look like after one parameter has been added.
The following steps describe how to enter a kinetic equation to the reaction:
If you want to use relative paths, select the corresponding radio button on the right hand side, and then the corresponding reference point in the tree window that pops up.
All variables you use in the kinetic equation will have to be present in the reference list. The molecules that were previously drawn to the reaction (educts, products, or modifiers) are already present with their corresponding amount parameters.
To add the reaction parameters that you defined before to the reference list, click on the + sign next to the reaction name in the tree display in the "Possible Referenced Objects" part of the window. Drag and drop all reaction parameters that you want to use in your formula into the references area left of the tree, where product and educt molecule references are listed.
If you need molecular concentration parameters in the formula, select Relative path and choose one container. Open this container in the possible referenced objects tree by clicking on the + sign next to it, then open MoleculeProperties underneath it, open the needed molecule and drag the concentration parameter (which needs to be created beforehand in the Molecules building block, see Molecule Parameters) into the references area left of the tree. Finally, you may want to edit the automatically generated alias names to have molecule names as part of the aliases. Just click into the alias name field and edit the name.
Besides reaction and molecule parameters, parameters of other building blocks, like the volume of a spatial structure, might be needed. They have to be defined first, so look up the corresponding sections in this chapter to see how to do that.
To complete reaction R2 (created above, see Reactions and Molecules) which you will need for continuing with the model building, connect molecule "B" as educt to R2, then "C" as product, as done for R1 in the previous section. Then define another k1 parameter for R2, this time set it to 0.005. Note that the name k1 appears twice, but is assigned to different reactions - thus they can both be separated. Next drag k1 to the references list, then enter k1*B as reaction kinetics formula. We will need a working reaction system if we move on to setting up a simulation later on.
If using the same rate constant name for two different reactions is too confusing, use different names for the rate constants in different reactions.
Additional Features for Editing Reactions
There are more features available to handle reaction building. Some of which are briefly described here:
you can delete an object using the Delete key or the context menu,
you can zoom, for instance by pressing the Shift key and selecting a rectangle by dragging the mouse,
different layout features like usage of templates and auto layout mechanisms are available.
To get more details on which techniques are available in all diagrams, see Diagrams Overview.
Instead of the diagram area, the graphical display of all reactions, you can switch to a list view by clicking the List tab in the upper part of the edit window. Reactions are listed by name with their stoichiometry and kinetic equations. Right-clicking the lines allows you to edit, rename, save, and remove any reaction by selecting the corresponding entry in the context menu.
Transport Processes
In MoBi®, passive and active transport processes use common logics in their setup. However, for technical reasons they are defined in different building blocks: a separate passive transports building block for those passive processes that are generic for all molecules, while the active and passive transport processes specific to the molecules are defined in the molecules building block. Typical examples for all groups are mentioned in the sections below.
Passive Transports
For creating a new transport or loading one from a previously saved file:
Enter a name for this transport process, for example "Diffusion".
Define descriptors for target and source containers:
Right-click into the corresponding empty space below "Condition" and "Tag", then either select New match tag condition or New not match tag condition.
A window where you will be asked for the tag name will open.
A tag can simply be the name of a container of a spatial structure; you can select from the available names by clicking the drop-down arrow. In our example project, select "Vial1" as "New match tag condition" for "Source Descriptor", and select "Vial2" as "New match tag condition" for "Target Descriptor". Selecting the "not match condition" will simply invert the selection.
The arrangement of neighborhood connections set up in the spatial structure (see Creating Neighborhoods) will restrict the pattern of transport streams.
In order to define a transport rate, go to the Tab Kinetic. Select Formula in the Formula Type combobox.
Next you need to compile the referenced values for the diffusion formula. To have more space for easier navigation, you may either click OK and edit the formula in the larger space of the edit window, or you may increase the size of the window by pulling on its rims with the left mouse button pressed.
A diffusion equation typically requires you to use concentration differences between two connected containers. Also, a diffusion constant is required which may be molecule-dependent.
To have such values as molecule parameters available, you need to go back to edit the Molecules building block and introduce them (see Molecule Parameters).
If transport rates depend primarily on the processes rather than on the molecular properties (e.g., blood vessel flow rates), it might be better to attach such parameters to the neighborhood (see Creating Neighborhoods).
If only one global diffusion coefficient is needed (e.g., if all molecules diffuse rather similarly), you may define it as a parameter to the transport process. Use the "Parameters" tab in the edit window of the newly created passive transport, and create a diffusion constant in the way described for the other building blocks, using the "New Parameter" button.
Another alternative is to just enter a diffusion constant as a numerical value into the formula input box, as it is done below.
In any of the above cases, the tree view within the field "Possible Referenced Objects" allows you to pick parameters from a variety of building blocks.
If you notice later that a parameter would rather be placed at another location, you can move a parameter by clicking to the left of it, pressing Ctrl+X and inserting it with Ctrl+V at the proper position. However, all "Possible Referenced Objects" list entries pointing to this parameter need to be entered again manually.
Continuing with our example, let us enter a simple diffusion equation based on a constant multiplied with the concentration difference between source and target container.
Make sure that the molecules created above all have a "Concentration" parameter. If not, see Molecule Parameters how to proceed.
To make the concentrations available for the diffusion formula, work with the "Possible Referenced Objects" tree view, as described in Reaction Kinetics. Select "Relative path", and choose "BigVial|Neighborhoods|V1V2Connection" as reference point. The relative path will result in source and target molecule paths that are generic for all molecules, whereas selecting an absolute path will be molecule-specific.
Successively expand the "Possible Referenced Objects" tree view by clicking on the + signs to the left of "BigVial", then again "BigVial" in the level that opened, there on "Vial1", then on "MoleculeProperties", then on "A" (or any other molecule name). The "Concentration" parameter should now appear, if present.
Drag and drop exactly this "Concentration" parameter to the white references area to the left of the tree. The alias name "Concentration" and the path "SOURCE|MOLECULE|Concentration" should appear in the list.
Then open the tree below "Vial2" -> "MoleculeProperties" -> "A" and drag exactly this "Concentration" parameter into the references as well. This time, the alias should be named "Concentration1" and the path should read "TARGET|MOLECULE|Concentration".
Compare your screen to to the images below. If you want to change the aliases manually, you can do so by clicking on any name input box and replace the corresponding name with another.
The resulting formula is a generic formula. The example model has 3 different molecules, "A", "B", and "C". Each of them will be transported by the above passive transport, as long as they are all present in the compartments "Vial1" and "Vial2" and the checkbox "All" is selected, which is the case in our example.
Molecule-specific Passive Transports
Besides generic transport processes, molecule-specific passive transports may be required. An example is a molecule's clearance from the body which is not further characterized and cannot be attributed to specific enzymes or transporters.
As with generic passive transports, molecule-specific transports only affect non-stationary molecules. Following the logic of MoBi®, molecule-specific transport processes are to be defined in the "Molecules" building block. Refer to Creating New Molecules and open your Molecules building block for re-editing by double-clicking or by use of the context menu. If it is still open, you can click the Molecules tab in the edit window.
To create a molecule-specific transport process:
In the molecules building block and in the molecules tree, right-click on the molecule that you want to be transported.
Select Create Passive Transport from the context menu.
A "New Passive Transport" window opens.
Then follow the same protocol as given for the generic passive transports, “Passive Transports”.
Like with the generic passive transports, you may also load an existing process from a pkml file. Existing passive transports appear below the affected molecule in the tree view. Selecting such a process by clicking it will display an edit window as for the active transports.
Active Transporter Molecules
An active transport process, as opposed to a passive transport, requires a transporter molecule (like a protein channel) that works similar to an enzyme. Unlike a chemical reaction, however, this process does not change a molecule but transfers it between containers, for example, from the intercellular space into a cell. As with passive transports, active transports only affect non-stationary molecules. Following the logic of MoBi®, all active transporter molecules and their transport processes are to be defined in the "Molecules" building block. Refer to Creating New Molecules and open your Molecules building block for re-editing by double-clicking or by use of the context menu. If it is still open, you can click the Molecules tab in the edit window.
First, an active transporter molecule needs to be defined:
In the molecules building block and in the molecules tree, right-click on the molecule that you want to be transported.
Select Create Transporter Molecule from the context menu.
You are asked for a transporter name. Either enter a new name (e.g., "PGP"), or the name of an already existing transporter molecule if the very same transporter is active for several molecules in your list and has been previously defined.
Press Enter or click OK. In the molecules tree, a transporter molecule is displayed, and a transporter entry is added to the molecule selected in step 1.
In the transporter entry below the selected molecule, you may enter a description and parameters, as for any molecule.
Click on the transporter molecule at the top level of the molecules tree to modify this molecule's parameters, as described above in, Molecule Parameters. This may be the initial amount of transporter or a concentration parameter.
Right-click on the transporter attached to the molecule to be transported, and select Create Transport from the context menu. A window named "New Active Transport" opens.
Enter a name into the Name input box, like "PGP Transport". Then, follow the steps described in the previous section “Passive Transports” for selecting source and target, define a transport rate parameter and entering a transport kinetics formula.
Continuing with our example project, let us enter a transport called "PGP" for molecule "A" and a transport process called "PGP Transport A" which runs in the opposite direction of the above passive transport, i.e., from "Vial2" as source to "Vial1" as target. As references for the transport equation, you need the concentration parameters of "PGP" and of "A" from the references tree. The alias of the PGP concentration is renamed to "C_PGP", and that of molecule "A" to "C_A" by just overriding the default names. The equation to be entered is "0.001*C_PGP*C_A". The figure below shows what the screen should look like after everything is properly set up.
If more than one molecule is transported by the very same transporter, you just create the same transporter molecule twice, i.e., with the same name under the second molecule. This will only create a new active transport, but no duplicate transporter molecule. You can then proceed like for the first molecule and create a transport process.
If two molecules compete for the same transporter, you can add inhibition terms to the transport equations that use all molecules, either as transporter substrate or as transporter inhibitor.
Observers
An observer which can be displayed in a chart (see Simulation Results) is an output derived from one or several molecules or parameters by a defined formula. There are two classes of observers: molecule observers and container observers; creating and editing of both classes will be explained in this section. The main difference between those two classes is that a container observer can be computed for every molecule in every container (or for a selectable subset of both), whereas an molecule observer can be used to compute a value from one or more molecules specified in its formula, but for all or a selectable subset of containers.
In our example project, a spatial structure named "Observer" has already been created by initially executing the New Project command. To proceed further, click on the + sign to the left of "Observers" in the building block explorer, and then open the "Observer" for editing by double-clicking on it or by using the Edit command of the context menu that appears after right-clicking on "Observer". In the edit window, you can choose between the tabs "molecule observer" (the default selection on opening) and "Container Observer".
Each observer class has a conditions attached to it that determines for which molecules and in which parts of the spatial structure an observer is calculated. Observers can be selected by inclusion or exclusion criteria based on their tags by selecting New match tag condition or New not match tag condition. Tags are either the name of a container or they can be manually added (compare “Creating a Spatial Structure”). All conditions entered for one observer are connected by a logical "and". Make sure you have entered proper data into these fields, or otherwise an observer is not generated in a simulation and warnings will be reported when creating a simulation (see Create a Simulation). As a further option, you may select the Add match all tag condition, which selects all containers.
All conditions, parameters, formulas, names, and paths that have been defined for any observer may later be edited, renamed, or deleted. Use the corresponding context menus, or override the entries in input boxes, comboboxes, or checkboxes.
Molecule Observers
To work with molecule observers, make sure the tab "Molecule Observer" in the edit window is selected. To create a new molecule observer, use Create Molecule Observer as described above, upon which the "New Molecule Observer" window opens (see image below). For our test project, we want to create an observer that calculates the molar concentration from the amount of molecules, doing so for each molecule and each compartment except for "BigVial".
Enter the name "MolarConcentration" in the Name input box, and select Concentration as Dimension below.
Check the box "All" in the section "Calculated For Molecules".
Then right-click into the white space below "In Container with", and select New match tag condition from the context menu.
You are asked for a tag name. Select "Obs" from the combobox or enter it manually. The "New Molecule Observer" window should now look like:
The next step is to create the Monitor formula which defines how the value of the observer is calculated from the molecule or parameters. At this point, at least a formula name is required for the observer creation; all other data like the observer formula can be defined at a later point, if needed. Click on the "Monitor" tab in the "New Molecule Observer" window.
• You can now continue to create the formula in the "New Molecule Observer" window. In this case, it is advisable to enhance the size of this window to have more work space.
• Alternatively, you can click OK or press Enter and return to the edit window, where you need to click the "Monitor" tab again. Let us continue our example in the edit window since there is more space to select references.
On the right hand side of the Monitor window, you will see the "References" column. The screen now looks like in the screen shot below:
The formula for molecular concentration you will need to enter is the ratio of molecule amount and container volume. For both, you need the references, similar to all previously described formulas. For the amount of molecules, this is straightforward: just drag and drop the word "MOLECULE" from the "Possible Referenced Objects" tree on the right to the white space below "Alias/Path/Dimension" on the left. The alias "M", the path "..", and the dimension "Amount" will appear. This alias "M" stands for the corresponding amount for each molecule the observer is calculated for, according to the conditions defined previously, visible under the "Properties" tab.
Since our concentration observer should be computed for containers of different hierarchical levels (in case the spatial structure will be extended in the future), you need to select "Relative Path" by clicking the corresponding radio button on the right. The first time you do that in this window, you will be asked for entering a path by the window shown below. To completely visualize the path, press the * key or click on all + symbols to the left of the names. You may select any of the containers here and then use its corresponding Volume parameter; however, do not use any of the "MoleculeProperties" branches, as that would invalidate the path. To complete our example observer, click on "Vial1" and then on the OK button; see the following image.
On the right hand side of the edit window, the "Possible Referenced Objects" tree, "Vial1" is now highlighted. Open the "Vial1" tree by clicking on the + symbol to the left of "Vial1". You will see the parameter "Volume" below it, after "MoleculeProperties".
Drag and drop exactly this "Volume" to the left, below the "M". The alias "Volume", the path "..|..|Volume", and the dimension "Volume" should appear. Compare the screen shot below with your monitor window.
The warning symbol disappears, you can see the still highlighted "Volume" that was used to drag the reference path, and you will see the amount of molecules M. In case there was a mistake and you need to reset the Local Reference Point, click on the ... symbol to the right of the path and re-enter it. Wrong references above the formula can be deleted by right-clicking on them and selecting Remove from the context menu.
If you have already loaded or created a concentration parameter when building the molecules (see Molecule Parameters), you may wonder why you cannot use this reaction parameter for the observer. This is indeed an alternative option. Instead of dragging and dropping "M" and "Volume", you can use the "Concentration" parameter with the correct relative path, which can be found under "Vial1/MoleculeProperties/A", if you repeatedly click on the corresponding + signs to open up the paths. As formula, this time just insert "Concentration", and you are done. you will use this method again for the container observers, so it will be further elaborated there.
Examples for many other molecule observers can be best studied when opening the observer building block in a simulation exported from PK-Sim®.
Container Observers
To work with container observers, make sure the tab "Container Observer" in the edit window is selected. For our test project, we want to create an observer that calculates the sum of our two metabolites, B and C. This creation procedure is almost identical to molecule observers, but the paths you get are different, and you will use different properties and formulas.
To create a new container observer, use "Create Container Observer" as described above, upon which the "New Container Observer" window opens, similar to the molecule observer.
Enter "SumMetabolites" as Name, "Concentration" as "Dimension".
Then click the "Add Molecule" button within the section "Include List". You will be asked for a molecule name; select or enter "C" and click OK. Select the Add match all tag condition, which means that the observer will be calculated for all containers.
You need to select a target container tag in the "In Container with" field in the same way as described in Molecule Observers or for "Source" or "Target" in Transport Processes. For our example project, use the same condition as for the example molecule observer: select New match tag condition from the context menu and then Obs from the combobox.
Since the display returns to the properties tab, you need to click the "Monitor" tab again. Set the relative path as described for the Molecule Observer to "Vial1".
In the "Possible Referenced Objects", open the "Vial1" paths all the way down until you see the "Concentration" parameters for molecules "B" and "C".
Drag and drop both of them successively to the reference list.
The screen should look like in the screen shot below:
Events and Applications
An event is used to change an entity, like the amount of molecules or a reaction rate, when a given condition is met. This condition can be, for example, that a given simulation time is reached, or that the concentration of a molecule has exceeded a certain value. Thus, such a programmed event is used to reflect external changes to the simulation, like the application of a drug or a sudden physical change in the spatial structure, like a vessel rupture.
In the drug delivery case, however, you rather want to use an application instead of an event to have more options available for drug release and repeated applications. Since the generation of an application in MoBi® can be rather complicated and is beyond the scope of this manual, we will restrict the description to adapting applications that were previously imported from PK-Sim®, where complex applications schemes can be generated more easily.
Events and applications are grouped in an events building block, where events are sub-grouped in event groups. To create such a structure, you may need to create a new events building block using the context menu of the building block explorer or the corresponding ribbon button of the Modeling & Simulation tab. In our example, an empty events building block named "Events" has already been created automatically. Simulations imported from a PK-Sim® project also contain such a building block that contains the applications.
To add events or applications to the project, you need to open the events building block for editing. This can be done by double-clicking on it or by using the Edit command of the context menu in the building block explorer.
Event Groups and Events
To create a new event group, either
A window named "New Event Group" will open. Then proceed with:
Enter a unique name into the Name input box, like "EventGroup1".
Enter a condition to define for which containers the event will be applicable. In order to do so, click into the white space below the "In Container with" field, and select New match tag condition or New not match tag condition - depending if you want to include or exclude containers with a specific name or tag. You can enter more than one condition, which will be combined by a logical "and". A further option is to select the Add match all tag condition, which selects all containers.
After this, you will be asked to enter a container tag for your condition, where you can select from available tags in a combobox. In our example project, select BigVial as a New match tag condition. This will make the event group effective for the entire spatial structure you created above.
As always, you may enter a description into the input box at the bottom.
Click OK or press Enter to finalize the event group. The new event group should now be listed in the left part of the event building block edit window. The right part should show the previously specified event group tag conditions.
As in other instances, you may define parameters for an event group. To access the parameters window, click on the "Parameters" tab in the right part of the edit window. Entering a parameter entry works in the same way as described for molecules, reactions, or for spatial structure containers. Examples for event group parameters are values for event timing or amounts of molecules that you want to set within the individual events of this event group.
After the event group is created, individual events can be defined for this group. Right-click your event group, and you will see the options you have in the context menu. These are:
Edit - this has the same function as selecting the name.
Rename
Save As - saves the selected event group to a pkml file.
Remove - deletes the selected event group.
Create Application - see Applications.
Load Application - see Applications.
Create Event - creates a new event within the current event group.
Load Event - loads an existing event from a pkml file.
Create Event Group - creates a new event group below the highlighted event group.
Load Event Group - loads an existing event group from a pkml file below the highlighted event group.
Create Container - see Applications.
Load Container - see Applications.
To create an event, click the Create Event option. A window named "New Event" will open (see image below). Then proceed with the following steps:
Enter an event name in the Name input box, e.g. "E1".
The section "Condition" below the checkbox requires that you enter an event condition name, which is comparable to a formula name of a reaction or a parameter. Enter "E1" into this input box.
To have more space for building the condition, close this window now by clicking OK or pressing Enter to complete the event building in the edit window. However, all required data could also be entered in the "New Event" window.
Continue working with the right part of the edit window with building the event in the "Properties" tab. From the Possible Referenced Objects tree, you need the TIME variable, which reflects the simulation time. The procedure is the same as described for referenced objects used in reaction equations (see Reaction Kinetics): Drag the TIME with the mouse to the left hand side and release it in the white space below the "Alias" header under the "Condition". "Time" should appear in this field.
Enter "E1Time" as parameter name.
Select Time from the combobox "Dimension".
Enter "500". If you prefer to do this in other units than minutes, you may change the dimension (e.g., to "h") in the combobox to the right of the value.
Click OK or press Enter. The new parameter will appear in the parameters list.
Click the "Properties" tab. Drag and drop the newly created parameter "E1Time" from the Possible Referenced Objects list on the right into the white space below the already added "Time" reference. To find this parameter, you need to look below the E1 event, so click on the + sign to open that part of the reference tree. In case you have defined the parameter under the event group, you will find it below the event group.
What is still needed is the assignment which determines what will happen when the event condition is fulfilled. As an example, we will set the amount of molecule "A" in the container "Vial1". To proceed, click the button Add Assignment. A window named "New Event Assignment" will open.
Enter "SetA" as name into the Name input box.
Click the ... on the left hand side of the "Changed Entity" input box below Name. A window named "Select Changed Entity" will open. Select the molecule "A" in "Vial1" as target. To see it and be able to click it, you need to open the levels BigVial|BigVial|Vial1 by clicking successively on the + sign to the left of them. Then click on A. The window should look like the following screen shot.
Instead the amount of molecules, an event allows for changing a number of assignments, like reaction or transport rate constants, container volumes or neighborhood parameters. The entire formula of a reaction or transport may be changed by not checking "Use Assignment As Value" during the creation of an assignment, and by selecting Formula instead of Constant in "Formula Type". Also, you may change several assignments upon one condition: just click the button "Add Assignment" again, and you can go through the above steps 14 to 18 again and have another value changed.
An assignment can be changed by the following actions:
Click the ... symbol to the right of "Changed Entity Path", and you will see the Select Changed Entity window again to alter the above choice.
In the "New Formula" input box (or row in case of several assignments), you can change between different values or formulas for the target assignment.
The above actions allow for basic editing of assignments. For all other and deeper changes, the recommended workflow is to delete and re-create an assignment.
Applications
An application is basically an event group with a more complex structure than that described in the previous section. In almost all cases, the application will be created within PK-Sim®and then transferred to MoBi®. The scope of this section will be limited to working with this recommended workflow.
The image below shows two example applications imported from PK-Sim®, one
i.v. and one oral. You can see the two application in the tree view of the event edit window. Each application consist of the application group, the application start event, and the protocol schema item. To make changes, look at the parameters of the protocol schema item, as displayed in the image.
You may make changes in the following parameters of this group:
Altering DosePerBodyWeight will change the dose per kg body weight. This will only work if it was used in the original PK-Sim® project, which can be recognized by having a formula in the Dose parameter.
Altering Dose will let you change the absolute drug dose administered. If the original PK-Sim® project contained a dose per body weight, that formula will be overridden by the absolute value.
The time where the drug administration starts can be altered by changing the
Start time parameter.
The volume of water per body weight can be changed for oral applications only by using the parameter Volume of water / body weight. This will only work if it was used in the original PK-Sim® project, which can be recognized by having a formula in the Amount of water parameter.
Altering Amount of water will let you change the absolute amount of water administered with the drug. If the original PK-Sim® project contained a volume of water per body weight, that formula will be overridden by the absolute value.
The other parameters of this block should not be changed.
The descriptions at the bottom section of each parameter gives you more information on each parameter.
More complex changes, like changing complex dosing schemes or changing dissolution patterns are much easier to achieve using the user interface of PK- Sim® and then exporting the corresponding simulation. Within a MoBi®project, you may then combine drug applications from several PK-Sim® exports. The following describes the workflow for this operation:
Save all applications of interest as PK-Sim® simulations to pkml files (see Export To MoBi®).
Load your MoBi® project.
Enter the name and location of your pkml file. You may be asked for a new building block name. A new Events building block is created.
When creating a simulation (Create a Simulation), you can now select between several possible application building blocks.
A collection of template files with predefined building blocks is automatically installed together with MoBi® in the default program data directory. The entry "Templates" in the program start menu in the MoBi program group will lead you to the proper path.
Molecule Start Values
Molecule start values are needed to define the initial amounts of all molecules present in the molecules building block used in a simulation for all containers. These values are either imported when loading a simulation, or they can be created automatically and edited manually, if needed.
Molecule and Parameter Start Values can also be created within the Simulation Creation Wizard (compare Create a Simulation).
To automatically create molecule start values by MoBi®:
Right-click the entry Molecule Start Values in the building block explorer.
Select Create Molecule Start Values Building Block from the context menu that appears.
A window called "Create new start values" opens. Enter a unique name for the building block.
In the comboboxes below, you can select between different molecules or spatial structure building blocks from which the start values are calculated.
Click OK or press Enter.
If the name you have entered is already in use, you may be asked for entering a new name.
An edit window opens, containing all created parameters.
All molecule or concentrations are automatically set to their default values as defined in the selected molecules building block, and these values are used for all containers in the selected spatial structure. All molecules are set to the status IsPresent in all physical containers.
Start values which are defined by a formula are displayed as "" at this stage, which means that their values are not determined before the simulation is created.
Instead of creating molecule start values, you may load them from a previously saved simulation or a saved molecule start value building block, a pkml file.
Right-click the entry Molecule Start Values in the Building Block Explorer.
Select Load Molecule Start Values Building Block from the context menu that has appeared.
Select the pkml file in the file explorer window.
Molecule start values can also be imported from Excel-files which is detailed below.
manually override the start concentrations or dimensions for every molecule in every container;
manually change the "IsPresent" state for each molecule;
Restricting the presence of molecules to certain organs may improve your computing performance, but use it carefully to keep your model valid!
Restricting the presence of molecules to certain organs may improve your computing performance, but use it carefully to keep your model valid!
A complete start values building block can be saved as pkml file by
Right-clicking on its entry in the Building Block Explorer.
Select the command Save As.
Select a folder and file name under which it is saved for later use.
A start values building block can also be cloned by choosing the Clone command from the context menu in the Building Block Explorer. The name "Clone of <\building block name>" is chosen by default, and you may be asked for a different name if it is not unique. Cloning is particularly useful if you want to create several sets of similar start values building blocks with few manual changes to test different simulation scenarios.
Every start values building block can also be renamed by choosing the Rename command from the context menu in the Building Block Explorer. This operation allows you to choose more descriptive names for cloned building blocks.
Parameter Start Values
Parameter Start Values are needed to define the values of various parameters present in the molecules and spatial structures building blocks used in a simulation. For example, this is true for the volume parameters of containers. These values are either imported when loading a simulation, or they can be created automatically and edited manually, if needed. Handling of this building block is very similar to the procedure described in the previous section for Molecules Start Values. In particular, cloning, loading from and saving to a pkml file is done in the same fashion (see previous section).
To automatically create Parameter Start Values by MoBi®:
Select Create Parameter Start Values Building Block from the context menu that opens.
A window called "Create new start values" opens. Enter a unique name for the building block.
In the combo boxes below, you can select between different molecules or spatial structure building blocks from which the start values are calculated.
Click OK or press Enter.
If the name you have entered is already in use, you may be asked for entering a new name.
An edit window opens, containing all created parameters.
All parameter start values are set to the values used in the corresponding building block.
To edit a parameter start value building block, double-click on it or use the context menu in the building block explorer and select Edit. An edit window opens, analogue to the one that is used for creating new start values. You can now
manually override the displayed values or dimensions.
Again, cloning and manual parameter changes at this level allow for quickly switching among different simulation scenarios.
The example model is now ready for setting up a simulation which is described in the next chapter (see Create a Simulation).
Import Molecule and Parameter Start Values from Excel
A major new feature of MoBi®™ 3.5 allows import of Molecule and Parameter Start Values from Excel files on an existing building block. This features enables easier maintenance of start values and exchange with other software tools. The import is started through the context menu of the respective building block.
Files might be of older (.xls) or newer format (.xlsx). The Excel®™ file may include several worksheets and selection of relevant worksheets is part of the import workflow. The workflow includes an import step that validates and creates a start value on each row. Once the import step is successfully completed and all rows are validated, the start values are transferred into the selected building block. This workflow prevents improperly specified or formatted data from from being partially imported.
It is not necessary that the target building block of the import is empty. If there is a collision of existing and imported start values (a collision is defined by matching name and path), the imported value takes precedence.
A valid Excel file for import of Molecule Start Values must have columns specified for Path, Molecule Name, Is Present, Value, Unit, Scale Divisor and columns must appear in that order.
You may update Molecule Start Values by importing a file of a valid format that contains new values only and is empty otherwise. Upon import for updating, existing Molecular Start Values matching the empty columns remain as is and only those matching the non-empty columns are updated.
| Path | Molecule Name | Is Present | Value | Unit | Scale Divisor |
|---|---|---|---|---|---|
M|W | A | 1 | 30 | µmol | |
M|W | B | 50 | µmol | 3.5 |
Upon import, the heading row will be ignored and can contain any values indicating the purpose of this column; however, all columns must have a heading.
Scale divisor: Internally, very small numerical values are divided by the scale divisors to get to an order of magnitude which is reasonable for the solver. The purpose is to reduce numerical noise and to enhance computation performance. This is also important when working with a broad variety of magnitudes of values. The scale divisors specify a typical scale for each species. Per default, all scale divisors are set to 1. The scale divisors are defined in the Molecule Start Value building block for each start value. If you work with with very small amounts and/or a broad variety of magnitudes of values and your simulation yields implausible results (numerical noise, negative values etc.), use the Calculate Scale Divisor to adjust the scale divisor for computational purposes.
A valid Excel file for import of Parameter Start Values must have columns specified for Path, Parameter Name, Value and Unit and columns must appear in that order.
| Path | Parameter Name | Value | Unit |
|---|---|---|---|
M|W | B | 321 | g/mol |
Editing of Molecule and Parameter Start Values
Start values can be edited which allows the user to quickly modify the list of start values. However, the user has to take care that the data entered manually makes sense within the existing building block. Refreshing a start value will allow the user to revert any modifications made to a start value, formula or dimension and use the values for start value, formula and dimension in the original builder. This is realized by finding the original builder using the container path of the start value.
Last updated
