OptiPa - KU Leuven [PDF]

OptiPa (v. 6.2p) User Manual

1 / 134

Table of contents OptiPa, a MatLab interface ................................................................................................ 4 General information ....................................................................................................... 5 Legal disclaimer ............................................................................................................ 6 Installing OptiPa ............................................................................................................ 7 Structure of the working folders ................................................................................... 13 Parallel computing ....................................................................................................... 14 Model implementation ...................................................................................................... 16 Model implementation: experimental data ................................................................... 17 Model implementation: condition file ........................................................................... 19 Model implementation: linkage data ............................................................................ 21 Model implementation: model definition file ................................................................. 22 The different time concepts ......................................................................................... 29 Using a spreadsheet to create ASCII input files .......................................................... 30 Using the proper MatLab syntax.................................................................................. 31 Graphical User Interface .................................................................................................. 34 GUI: File menu ............................................................................................................ 37 GUI: Options menu ...................................................................................................... 45 GUI: Help menu........................................................................................................... 51 GUI: Model control menu............................................................................................. 54 GUI: Preparing the optimisation .................................................................................. 57 GUI: Selecting an optimisation method ....................................................................... 61 GUI: Optimisation control ............................................................................................ 64 GUI: Transformations .................................................................................................. 65 Removing outliers........................................................................................................ 67 Model simulation .............................................................................................................. 68 Graphical simulation output ......................................................................................... 69 Numerical simulation output ........................................................................................ 73 Model optimisation ........................................................................................................... 75 Graphical optimisation output ...................................................................................... 76 Numerical optimisation output ..................................................................................... 77 Statistical optimisation output ...................................................................................... 78 Optimisation per experiment ............................................................................................ 84 Optimisation per experiment: procedure ..................................................................... 85 Optimisation per experiment: output ............................................................................ 86 Confidence regions .......................................................................................................... 90 Confidence regions: procedure ................................................................................... 91 Confidence regions: output.......................................................................................... 93 Sensitivity analysis ........................................................................................................... 97 Sensitivity analysis: procedure .................................................................................... 98 Sensitivity analysis: output ........................................................................................ 100 Bootstrapping................................................................................................................. 102 Bootstrapping: procedure .......................................................................................... 103 Bootstrapping: output ................................................................................................ 104 Monte Carlo simulations ................................................................................................ 107 Monte-Carlo simulations: procedure.......................................................................... 109 Monte-Carlo simulations: output ................................................................................ 114 Draw from distributions .................................................................................................. 119 Draw from distributions: procedure............................................................................ 120 Draw from distributions: output .................................................................................. 124 Background.................................................................................................................... 125 Levenberg-Marquardt method ................................................................................... 126 2 / 134

Lagrange multipliers .................................................................................................. 130 Model based error resampling bootstrap technique .................................................. 131 Generating random correlated non-Gaussian parameters ........................................ 132 Cholesky decomposition ........................................................................................... 134

3 / 134

OptiPa, a MatLab interface The MatLab program, OptiPa, was developed to estimate model parameters on ODE based models. This help file describes the functionality of OptiPa and some of the backgrounds. This help file will subsequently highlight the following topics:

           

General information How to prepare your model input files How to prepare your model definition file How to operate the graphical user interface How to run a simulation How to run an optimisation How to run an optimisation per experiment How to determine the conditional joint confidence regions for your model parameters How to do a sensitivity analysis How to run a bootstrap analysis How to run Monte-Carlo simulations How to generate random co-varying variables

In case of any problems please contact the author and email your input files to enhance diagnosing your problem. The text of this help file is also available in PDF format. Maarten Hertog KU Leuven BIOSYST-MeBioS Faculty of Bioscience Engineering W. de Croylaan 42 - bus 428 BE - 3001 Heverlee Belgium www.mebios.be

4 / 134

General information OptiPa was developed because of an urgent need for a flexible and versatile interface to estimate model parameters on ODE based models leaving only a minimum of programming for the end user. One of the innovative aspects of OptiPa is that it readily allows the user to identify the different sources of variation in a model as it allows, for instance, estimating certain model parameters either in common, per experiment, per treatment condition or per experimental unit. Analysing data this way enhances the interpretation of experimental data and the subsequent application of the model to different situations.

System requirements OptiPa is developed within the MatLab environment (The MathWorks, Inc., Natick, MA, USA). From the MatLab program a Windows standalone executable has been compiled which is what is being distributed to the end users. As a result OptiPa can be used without having MatLab installed. OptiPa has been compiled to suit 64 bit Windows based systems.

Important update notes 

OptiPa version v6.2p has been largely improved with regard to user-friendliness. o First of all, the structure of the model OMF-files has been simplified.While the old structure is still supported users are encouraged to build their models following the new template. Check the help files to find out about the new model definition of the model OMF-files. o In addition, proper syntax checking of the model OMF-files has been introduced resulting in clear indications of the syntax errors including its line and position numbers. o Furthermore, the statistical output of OptiPa has been completely revamped with the ASCII text output being replaced by rich HTML output combining text and graphical results together. o Finally, the way users should be addressing the variables from the condition file has been simplified (but creating a possible incompatibility with old OMF-files).



From version v6.1p onwards OptiPa supports parallel computing. Please read the information on this topic as this has some impact on the operation of OptiPa. In older OptiPa versions the model files were saved as m-files (with the extension *.m). In the current OptiPa version the model files have been renamed to OMF-files (with the extension *.omf). To move models from previous OptiPa versions just rename the model m-files to OMF-files by changing their extension from *.m to *.omf.



5 / 134

Legal disclaimer While we have made every attempt to ensure the reliability of OptiPa, KU Leuven or its employees cannot be held responsible for any errors or omissions, or for the results obtained from the use of OptiPa. OptiPa is provided "as is", with no guarantee of completeness, accuracy, timeliness or for the results obtained from the use of this information, and without warranty of any kind, express or implied, including, but not limited to warranties of performance, merchantability and fitness for a particular purpose. In no event will KU Leuven, or employees thereof be liable for any decision made or action taken in reliance on the information provided by OptiPa or for any consequential, special or similar damages.

License agreement     

The LICENSER authorizes the LICENSEE to use OptiPa without any fee for scientific purposes only. The LICENSER does not adhere to any problems that arise directly or indirectly from using OptiPa. The copyright for OptiPa remains with the LICENSER. The LICENSEE has to ensure that OptiPa or parts of it are not distributed outside the institution of the LICENSEE. When publishing results, gained by using OptiPa, the LICENSEE has to mention OptiPa with appropriate citations (ask the author for an appropriate list of references. Publishing of comparative results with other similar forms of OptiPa, is to be arranged with the LICENSER.

6 / 134

Installing OptiPa OptiPa comes as a self-extractable installation file that will install the MATLAB Compiler Runtime, the OptiPa program files and a folder with some demo models. Just follow the instructions on screen. On running the installation file the user is asked to accept a simple disclaimer to keep us safe...

Fig. 1 OptiPa disclaimer. Subsequently you are asked to provide a destination folder for the OptiPa program. This can be anywhere on your hard disk, but not in the official program folders. Make sure to provide a proper folder name as by default OptiPa will just unpack in the folder from where you activated the installation file.

don NOT install OptiPa in the windows Program Files folder as OptiPa will need writing rights to be able to work properly. Instead install OptiPa to one of your user folders

7 / 134

Fig. 2 Provide the OptiPa destination folder. On confirming the destination folder the installation will start to unpack itself.

Fig. 3 OptiPa is unpacking the installation file. Once unpacked the Matlab Runtime Component Installer will be started. The MATLAB Compiler Runtime (MCR) is a standalone set of shared libraries that enables the execution of compiled MATLAB applications or components on computers that do not have MATLAB installed. The current version used is 8.5 for 64 bits Windows based systems that comes as part of Matlab release 2015a.

8 / 134

Fig. 4 The Matlab Compiler Runtime installer is being extracted

First time installation of Matlab Runtime Component If MCR is not detected on your machine you will have to go through the full installation procedure as pictured below which will take about 10 minutes. You will need administrator's rights to install the Matlab Compiler Runtime.

Fig. 5 Full installation process of a first time installation of the Matlab Runtime Component

Repeat installation of Matlab Runtime Component 9 / 134

If you already have this version of the Matlab Compiler Runtime v8.5 (Matlab 2015a, 64 bit) installed on your machine you can skip the installation by pressing Cancel in the first screen (Fig. 6).

Fig. 6 Press Cancel if you know for sure you already have Matlab Compiler Runtime v8.5 (Matlab 2015a, 64 bit) installed Once finished with installing the Matlab Runtime Component the help file of OptiPa is automatically started. Please take some time to read it carefully as everything you ever wanted to know about OptiPa is in here.

Fig. 7 OptiPa help file is automatically launched on installation After installation, the OptiPa folder should look something like below. A simple shortcut is created in your Start menu as well.

10 / 134

Fig. 8 Structure of the OptiPa installation folder.

Starting OptiPa To start OptiPa, either select the OptiPa link created in your Start menu or go to the installation folder and start OptiPa by double clicking the file optipa.exe (Fig. 8). The very first time you start OptiPa it will take a bit longer as the program still has to be unpacked from its archive (Fig. 9). The black Console-window will remain visible throughout the operation of OptiPa serving as a progress monitor on which some of the OptiPa output can be monitored. This screen replaces the MatLab command window.

Fig. 9 OptiPa is initiating. After unpacking the archive, OptiPa is automatically started. On first time startup you might get a firewall message. This has to do with the fact MatLab can potentially make use of multiple computers connected through your network. However, OptiPa is not making use of this feature. Therefore you can cancel this request for network access (Fig. 10).

11 / 134

Fig. 10 OptiPa is initiating.

The startup window will be shown while OptiPa is being initialised. Once finished the startup screen will disappear and control is rendered to the actual program.

Fig. 11 The startup screen of OptiPa. If multiple cores have been selected there will be a further delay related to the initiation of the cores

Important notes

  

Closing the black Console-window results in terminating the whole OptiPa program. You can minimise it though...... OptiPa won't add any entries in the registry of your computer. By deleting the OptiPa folder the program is gone MCR needs to be uninstalled through the official way (via the windows control panel)

12 / 134

Structure of the working folders Working with OptiPa implies working with different file types. First of all one can supply a total of four user defined files: one obligatory ASCII experimental data file, containing the dependent measured experimental data you want to model, one non-obligatory ASCII condition file, containing any independent variables describing the experimental conditions under which the experiments were performed, one non-obligatory ASCII linkage file, linking the experimental data to the condition profles defined, and one obligatory OptiPa model definition file (OMF-file) containing the actual definition of your mathematical model. While running OptiPa several output files are generated during simulation, optimisation, bootstrapping and Monte-Carlo simulation. To keep everything organised OptiPa works with so-called projects. A project is organised around a certain modelling topic. It generally includes a limited number of experimental data files in combination with several model versions all relating to those same experimental data files. These models can be seen as different attempts to describe the data. Each model saves its output in a separate folder (Fig. 1). The default location for saving all OptiPa projects is the subfolder …\projects relative to where the OptiPa program files are located. However, this project root can be changed through the options menu. In the example below this project root was changed to D:\OptiPa Projects. Within this project root you find the project folders as shown in Fig. 1 for the Demos project and the projects ModelTopic1, ModelTopic2 and ModelTopic3. Within such a project folder three main folders exist: data, models and settings as is shown for the Demos project. These folders are automatically generated when generating a new project through the file menu. The data folder should contain the model data files with experimental data file, the condition file and the linkage file (if applicable). The models folder contains all model definition OMF-files On generating a new model through the file menu a corresponding output folder is automatically generated in the models folder to save output from that particular model.

Fig. 1 Structure of the work folders generated by OptiPa. Manipulation of projects and folders is done through the file menu on the menu bar from the main OptiPa window.

Important notes

   

In previous OptiPa versions the model files were saved as m-files (with the extension *.m). In the current OptiPa version the model files have been renamed to OMF-files (with the extension *.omf). To move models from previous OptiPa versions just rename the model m-files to OMF-files. If one creates a new project by hand (not going through the OptiPa file menu) one has to manually create the sub folders data, models and settings outlined above. The name of a project and that of a model are not allowed to contain spaces. When creating a new project/model spaces will be automatically replaced by an underscore. If one creates a model OMF-file by hand (not going through the OptiPa file menu) one has to manually create a corresponding output folder in the models folder as well. If the model OMF-file is named: MyNewModel.omf the corresponding output folder should be named: OUTPUT [MyNewModel]

13 / 134

Parallel computing As of version 6.1p OptiPa has been extended with the possibility of parallel computing. Thanks to the Parallel Computing Toolbox™ from MatLab, computationally and data-intensive problems can be processed using multicore processors. OptiPa has been completely restructured and various of the numerical algorithms have been parallelised. Matlab, and therefore also OptiPa, supports the use of up to 12 cores to execute applications on a multicore desktop. The number of cores used can be set through the options menu .The maximum number of cores depends on your system but is limited to 12. When you select one single core you effectively rule out all parallel computations.

Benefits of parallel computing The number of cores initiated will dramatically affect the efficiency of OptiPa during the following tasks:

 





 





Simulation: When the data includes multiple experiments simulations of the individual experiments are executed in parallel speeding up the simulation task. Optimisation: Any of the optimisation methods are based on an iterative process of changing parameter values and simulating the model with the new parameter values. When the data includes multiple experiments simulations of the individual experiments are executed in parallel speeding up the optimisation task. Except for LSQnonlinear all optimisation methods support parallel computing. These genetic/evolution/population based approaches are all based on simulating large sets of model copies. Even when the data consists of only a single experiment the model copies generated by the various optimisation methods are processed in parallel speeding up these global optimisation approaches. Optimisation per experiment: When optimising the model per experiment the optimisation of the individual experiments are started in parallel speeding up the overall optimisation task. Except for LSQnonlinear all other optimisation methods support parallel computing and benefit from the parallelisation as indicated above. Calculating conditional joined confidence regions: Joined confidence regions are calculated based on an initial optimisation which benefits from the parallelisation as indicated above. Subsequently by scanning the parameter space for each pair of model parameter values, joined confidence intervals are calculated. This computationally intensive algorithm is now completely parallelised further speeding up this task of calculating conditional joined confidence regions. Do a sensitivity analysis: This task is based on simulating the model several times with slightly different model parameter values. While these runs were previously done sequentially they are now run in parallel speeding up the sensitivity analysis. Bootstrapping: Bootstrapping starts from an initial optimisation which benefits from the parallelisation as indicated above. Subsequently the model is repeatedly fitting to a large number of artificially generated bootstrap datasets. These optimisations are now started in parallel further speeding up the overall bootstrap process. Monte-Carlo simulation: Monte-Carlo simulations are based on simulating the model many times with different model parameter values. While these runs were previously done sequentially they are now run in parallel speeding up the Monte-Carlo simulations. Also the initial optimisation used benefits from the parallelisation as indicated above. In case started from an initial bootstrap dataset the Monte-Carlo analysis starts by fitting the SKN distribution to the bootstrap parameter distributions to generate random correlated sets of variables. This fitting of the distributions is implemented in parallel as well. Draw from distributions: This task is based on fitting the SKN distribution to a set of variables to generate random correlated sets of variables. This fitting of the distributions is implemented in parallel as well.

Memory Usage When deciding on the number of cores be aware that OptiPa might take up all the memory that you assign to it. If you need to do other work on your machine as well it might not hurt to leave at least one core free for other processes. To help you in monitoring the memory usage a small CPU indicator is included with OptiPa. Whenever you start OptiPa a white bar at the top of your screen will show the current load on your CPU ranging from 0 to 100 %.

14 / 134

Fig. 1 OptiPa with the CPU memory usage indicator visible at the top border of the screen.

Freezing of your system Sometimes when OptiPa is using full resources and you are trying to manipulate the screen, OptiPa seems to freeze and becomes unresponsive. As long as the CPU indicator remains active or remains at 100 % all OptiPa processes are still operational and there is no reason to worry. Just be patient. When frozen (but still operational) the STOP and BREAK buttons might no longer work. In this case you can stil use CTRL-ALT-F11 to stop the calculations or CTRL-ALT-F12 to break the calculations. Please press these key combinations until you notice on the Console window the message 'interrupted by user'. When the system has frozen and the CPU indicator shows almost no activity (say less than 10 %), most likely the parallel processes stalled. Then you have no other choice but killing OptiPa (by simply closing the black Console window).

Output files When parallel computation is activated by selecting more than 1 core, the order in which processes are handled becomes unpredictable. As a result the order of subsequent runs when optimising per experiment, when doing multiple a sensitivity run, and when running multiple Monte-Carlo simulations will have been scrambled depending on the number of cores involved during the parallel computations. This has no real consequences except for the fact that you will have to sort some of the output files yourself afterwards. This can always be done using the run number printed in the output files.

Important notes

 

The only situation when no benefit is obtained is when optimising data from a single experiment using the LSQnonlinear optimisation routine; this is the only routine that does not support parallelisation and with only one experiment there is nothing to simulate in parallel. When you select one single core you effectively rule out all parallel computations.

15 / 134

Model implementation To implement a model for use with OptiPa, four user defined files have to be generated: one obligatory ASCII experimental data file, containing the dependent measured experimental data you want to model, one non-obligatory ASCII condition file, containing any independent variables describing the experimental conditions under which the experiments were performed, one non-obligatory ASCII linkage file, linking the experimental data to the condition profles defined, and one obligatory OptiPa model definition file (OMFfile) containing the actual definition of your mathematical model.

16 / 134

Model implementation: experimental data The ASCII data file with experimental data contains measured data on one or more of the dependent model variables. The experimental data is organised in numbered experiments that each coincides with a single model run (Fig. 1). If replicate measurements were taken they can either be organised in a single experiment with replicates or in as many experiments as there where replicates. This would be the case when non-destructive measurements are taken from multiple fruit resulting in a complete time course for each fruit. In this case, the results of each single fruit can be considered a single experiment.

Fig. 1 Layout of the experimental data file. Panel A shows an example of experimental data with replicate measurements organised in as many experiments as there were replicates, while panel B shows a comparable example with replicates within an experiment.

Important notes

  

  

The first row of this file will be interpreted as column headings. The first column of this file must contain experiment number. The numbering of the experiments is allowed to be out of order or to omit certain numbers. The second column of this file must contain experimental time. Time should be in ascending order, but should not necessarily be equidistant. Multiple observations at a single time point can be included by introducing multiple rows with all the same time, but different observation values (Fig. 1, panel B). Subsequent columns can contain any kind of numerical information. Column headings used for these columns should be unique and not overlap with the names used in the condition file nor used as model variables in the model definition file. Missing numbers can be indicated using: NaN The file should be saved as some kind of delimited ASCII file using either: o , (comma)

17 / 134

o ; (semicolon) o | (tabular stop) o _ (white space)



This experimental data file is obligatory to supply as it is used by OptiPa to identify the simulation time of the model for each of the experiments included. If one does not have any experimental data (yet) and only wants to use OptiPa to do a simulation one can prepare a dummy experimental data file only containing two rows per experiment defining the time interval t=tmin and t=tmax (the maximum simulation time) while filling in NaN values in the experimental data column such as given below.



Whenever you change the data file you need to reload the file through the model control menu.

18 / 134

Model implementation: condition file The so called condition file contains the model input variables but is not mandatory to provide. Besides for defining model input variables this file is also used to define a possible (sub)grouping of the experiments (Fig. 1). A possible grouping could be based on characterisations like cultivar, fruit, grower, orchard, year or harvest. This enables OptiPa to estimate separate multiple values for a single parameter depending on these groupings.

Fig. 1 Layout of the condition file showing an example of a condition file containing the independent variable time, a grouping variable cultivar and the input variables temperature and O2.

Important notes

  

 

The first row of this file will be interpreted as column headings. The first column of this file must contain experiment number. The numbering of the experiments should be in agreement with the numbering used in the experimental data file. If NOT a linkage file should be provided. The second column of this file must contain experimental time. Time should be in ascending order, but should not necessarily be equidistant. If data from the condition file is used to provide independent input variables to the model and interpolation is used to generate a continuous data flow, the time span given for each of the experiments should start at t=0 and should at least cover the time span covered by the corresponding experimental data from the experimental data file. Generally one should at least provide two rows of condition data per experiment, at t=0 and at t=tmax. Multiple observations at a single time point are NOT allowed. The sample frequency presented in the condition file will affect the integration process. When small time steps are introduced the maximum time step allowed for the integrator is small as well. This is to prevent the ODE solver from overlooking short lasting events. When larger time steps are used the 19 / 134

  



maximum integration step is larger as well. Using smaller time steps than required (providing temperature data for every second while a typical event will take hours) will unnecessarily slow down the ODE solver and thus the whole simulation/optimisation process. In this case the input data should be reduced to the appropriate resolution. Check out the Discontinuity strategy for more options. Subsequent columns can contain any kind of numerical information. Column headings used for these columns should be unique and not overlap with the names used in the experimental data file nor used as model variables in the model definition file. Missing numbers are not allowed in this file. The file should be saved as some kind of delimited ASCII file using either: o , (comma) o ; (semicolon) o | (tabular stop) o _ (white space) Whenever you change the condition data file you need to reload the file through the model control menu.

Update note



As of v6.2p the user variables provided in the condition file are available as functions with the same names as given in the condition file. These functions require a single input, being time, and will generate as an output the interpolated value of the column variable it is referring to. As a result, the interpolated condition data is immediately available for use in the model definition file. At the same time this creates the one incompatibility issue with previous versions as the variables from the condition file are no longer available as column vectors, only as a function. So any existing user defined interpolations in the model definition file will generate an error. In previous versions to access the current temperature at time t users would typically define this in the model definition file using the interpolation function as: TempCurrent = interp1(t_cond,temp,t); As of v6.2p this should be replaced by the function named after the variable defined in the condition file using: TempCurrent = temp(t);

20 / 134

Model implementation: linkage data If independent input variables are required to run the model these should be provided through the condition file using the same numbering of the experiments as was used in the experimental data. However situations might occur where several experiments all relate to one and the same condition. This would require to repeat the same definition of that condition for all of the experiments involved. If these conditions are defined by some variable temperature regime obtained from a temperature logger the condition file might quickly grow too large. In this case one can prepare a linkage data file that tells OptiPa which condition from the condition file to use for which experimental data from the experimental data file. If no linkage file is provided the condition file and the experimental data file are assumed to be linked one to one through the experimental numbers mentioned in the first columns of both files. If a linkage file is needed it should be located in the data folder of the project.

Fig. 1 Layout of the linkage data file showing an example of a linkage data file containing per row a number of one of the experiments and the number of a condition to which it should be linked.

Important notes

   



The first row of this file will be interpreted as column headings The first column of this file must contain experiment numbers from the experimental data file. The second column of this file must contain experiment numbers from the condition file. The file should be saved as some kind of delimited ASCII file using either: o , (comma) o ; (semicolon) o | (tabular stop) o _ (white space) Whenever you change the data file you need to reload the file through the model control menu.

21 / 134

Model implementation: model definition file The OptiPa model file (OMF-file) containing the model definition (Fig. 1) should be located in the model folder of the project. The template for a new model definition file can be created through the file menu. It consists of four distinctive parts: model initialisation (Fig. 1a, line 1-63), data pre-processing (Fig. 1b, line 65-94), the actual model definition (Fig. 1c, line 96-124) and the model post-processing (Fig. 1d, line 126163).  All text starting with the %-sign (the green text) are comments to help you implementing the model.  All text marked by the yellow bars, indicate the various sections of the model definition and should be left unchanged. They consist of pairs of tags opening and closing each section, are enclosed within broken brackets with the closing tag containing an additional forward slash.  The text marked by the blue bars are tags to mark the model parameters, the model ODE state variables, and other output variables generated from them.  The text marked in green are functions to define the derivatives of the model state variables.

22 / 134

The model initialisation part

Fig. 1a The model initialisation consists of two sections: the parameter definition section (line 15-36) and the state definition section (line 49-63). In the first part of the parameter definition section (line 16-26) global named model constants can be 23 / 134

defined (either or not using some initial calculations in the free programming space) that will be available to the rest of the model definition by their name. The parameter definition section subsequently defines the model parameters for the estimation procedure in terms of their names and their initial values (line 27-35). Each parameter is preceded by the tag. In the state definition section, the ODE state variables are declared in terms of their names and their initial values (line 59-61). The initial values can be obtained using some initial calculations in the free programming space. As these initial values for the ODEs are initialised for each experiment simulated, experiment specific values of the input variables can be used. These initial values for the ODEs can also be incorporated as model parameters to be estimated. Each state variable is preceded by the tag.

The pre-processing part

Fig. 1b The pre-processing part (line 65-94) can be used for analytical manipulations of the original experimental data. This can be used to transform the original experimental data. No new variables can be generated, so the transformed data should always replace one of the existing data columns. This option was especially designed for cases where the transformation parameters need to be estimated as part of the whole model fitting process. If not required lines 82-93 can just be deleted or commented out by adding a percentage sign at the start of each line. Do not delete the opening and closing tags of the section. See demo files for examples of how to use this section.

24 / 134

The model definition part

Fig. 1c The model definition part (line 96-124) is where the actual model is being defined. Depending on the model this section might look differently. However, in all cases it should contain a definition of the derivatives for each of the state variables defined in the state definition section using the Deriv(...) function in combination with the correct name of the ODE state variable. When one wants to use the model input variables identified in the condition file, one can access these by using the functions with the same names as given in the condition file. See demo files for examples of how to use this section.

25 / 134

The post-processing part

Fig. 1d The post-processing part (line 97-115) can be used for analytical manipulations of the ODE model results. This can be used to calculate simple dependent variables that are directly derived from the ODE model results or to do additional transformations (change the output to the appropriate units for instance). Newly created output variables should be preceded by the tag. If not required lines 145-162 can just be deleted or commented out by adding a percentage sign at the start of each line. Do not delete the opening and closing tags of the section. See demo files for examples of how to use this section.

Most important note of all notes in OptiPa



All model parameter values are by definition assumed to be positive. The actual sign of the parameter is determined by the way it is used in the ODEs. So it is up to the user to determine on beforehand whether a parameter has an additive or subtractive effect. This was done to prevent complete garbage when the optimisation routine accidentally would change the sign of a parameter from positive to negative or the other way round. The consequence is that one should be suspicious for any parameter that keeps on going towards zero. In such case one might try to change the sign of the model parameter to check whether one might have made the wrong assumption about the sign of that particular parameter.

Important notes

   

All text starting with the %-sign (the green text) are comments and can be deleted. All section tags marked by the yellow bars should be left unchanged. If a section is not in use their tags should remain but the programming code they are enclosing can be removed. A model should at least contain one parameter, one state variable and its corresponding derivative. 26 / 134

 

 

  



  

Therefore, each OMF-file should at least contain one tag, one tag and one Deriv(..) function. The tag is not obligatory as it is only required when you want to define additional non-ODE variables The model parameters identified in the model initialisation part are declared through their names followed by initial starting values. Subsequently these named model parameters can be used in the remainder of the model definition part. In the pre-processing part the experimental data can be transformed. The experimental data is available through column vectors with the same names as given in the experimental data file. The experimental time vector is given as: t_exp irrespective of its name in the header of the experimental data file. These transformations are calculated per experiment simulated, so you can make use of experiment specific conditions or parameter values. The current condition data is available through functions with the same names as given in the condition file. The condition time vector is given as: t_cond irrespective of its name in the header of the condition data file. In the pre-processing part only transformation of existing experimental variables is allowed, not the creation of additional new variables. In the model definition part a continuous data flow can be generated to provide the model with independent input variables based on the condition file using linear interpolation. The current condition data is available through functions with the same names as given in the condition file. These allow you to access the condition data in a continuous way by linear interpolation using: MyConditionColumnName(t) which will give you the value of MyConditionColumnName at the current time t. There is a standard procedure available to calculate an Arrhenius based temperature dependence for your model parameters. The syntax for this is: karr(kref, Ea, Temp, Tref) Make sure all of the parameters declared in the model initialisation part that needs estimation are used in one way or another in the model definition part. In the post-processing part, the model output can be transformed. The results of all ODE variables are available through column vectors with the same names as declared in the section (see at top). The model time vector is given as: t_mod. New output variables require declaration using the tag. These transformations are calculated per experiment simulated, so you can make use of experiment specific conditions or parameter values. The current condition data is available through functions with the same names as given in the condition file. These allow you to access the condition data in a continuous way by linear interpolation using: MyConditionColumnName(t_mod) which will give you the value of MyConditionColumnName at all modelled time points of t_mod. Constants, variables and parameters used in the model definition should be unique and not overlap with the names used in the experimental data file nor with the names used in the condition file. In defining the model, the user can use any function available in the MatLab base system while adhering to the syntax rules from Matlab. Whenever you change the model you need to reload the OMF-file through the model control menu.

Once the model OMF-file has been coded, as illustrated above, OptiPa can be started to analyse the experimental data using the model. The actual programming required to implement a new model is thus limited to the bare essentials.

Update notes



As of v6.2p the user variables provided in the condition file are available as functions with the same names as given in the condition file. These functions require a single input, being time, and will generate as an output the interpolated value of the column variable it is referring to. As a result, the interpolated condition data is immediately available for use in the model definition file. At the same time this creates the one incompatibility issue with previous versions as the variables from the condition file are no longer available as column vectors, only as a function. So any existing user defined interpolations in the model definition file will generate an error. In previous versions to access the current temperature at time t users would typically define this in the model definition file using the interpolation function as: TempCurrent = interp1(t_cond,temp,t);

27 / 134

As of v6.2p this should be replaced by the function named after the variable defined in the condition file using: TempCurrent = temp(t);





In older OptiPa versions the model files were saved as m-files (with the extension *.m). In the current OptiPa version the model files have been renamed to OMF-files (with the extension *.omf). If you want to move models from previous OptiPa versions just rename the model m-files to OMF-files by changing their extension from *.m to *.omf.. If OptiPa finds m-files in the current model folder it will offer to rename them for you into OMF-files.

28 / 134

The different time concepts During the preparation of the input files (experimental data file and condition file) and the model OMF-file (model definition) you have run into the various usages of time.  The experimental data file contains a column time which refers to the time points at which experimental data was collected.  The condition file contains a column time which refers to time points at which data was collected on independent experimental variables (e.g. temperature) somehow serving as an input to the model. The time range covered in the condition file should at least cover the time period during which experimental data was collected but can be collected at different time points and can be more or less frequently collected.  The model definition file contains multiple references to time: o In the part where experimental data can be transformed the user has access to the time vector from the experimental data file. This experimental time vector is addressed as: t_exp, irrespective of the name given by the user in the actual experimental data file. o Throughout the model file (when Initialising ODEs, when transforming experimental data, when defining the model, and when transforming ODE model output) the user has access to the time vector from the condition data file. This experimental time vector is addressed as: t_cond, irrespective of the name given by the user in the actual condition file. o The ODE model definition part where the actual ODE's are defined is called by the ODE solver when numerically integrating the model. At every single time step during the integration the current time is available through the scalar t. So, to define an ODE which is function of time or when interpolating variables from the condition file to calculate their value at the current point in time, you should use this scalar t which at any point during the simulation will refer to the current time. o Once the ODE model integration is finished the ODE model output is available for transformations or to generate new additional variables. The ODE model output comes with a time vector t_mod which contains all time points at which the integrator generated the ODE output.

Update note



t_cond has become obsolete from v6.2 onwards as the user does no longer need access to this time vector as OptiPa is automatically taking care of the linear interpolation of all the condition data (see here).

29 / 134

Using a spreadsheet to create ASCII input files To prepare the ASCII input files (experimental data file, condition file and linkage file) one can use a spreadsheet program like Excel. The spreadsheet should be saved as some kind of delimited ASCII file using either: o , (comma) o ; (semicolon) o | (tabular stop) o _ (white space) If you prepare your data in Excel just save the file using for instance: o CSV (comma delimited) (*.csv) o Text (TAB delimited) (*.txt) o Formatted text (space delimited) (*.prn) If things go fine the spreadsheet should result in the corresponding ASCII file as shown below (Fig. 1). If, by accident, your spreadsheet contains some cells containing spaces this results in exporting empty columns and rows to the ASCII file (Fig. 2) which can be recognised from the redundant delimiters. This will generate an error message in OptiPa. You can either remove the redundant delimiters or remove the seemingly empty columns and rows from the spreadsheet file. A quick way to check for these ghost rows or columns is by opening the spreadsheet and pressing the key combination which will make your cursor move to the bottom right position in the file (marked in Fig. 1 and 2 by the position of the marked cells).

Fig. 1 Correct layout of the spreadsheet file with the corresponding ASCII file generated from it.

Fig. 2 Wrong layout of the spreadsheet file with the corresponding ASCII file generated from it.

30 / 134

Using the proper MatLab syntax To prepare the model definition file the user has to adhere to the basic programming syntax from MatLab. Any line of code typed in the model definition needs to be evaluated by the MatLab compiler. Any syntax error will be indicated through an OptiPa error message. The full description of the functions supported through the MatLab Base system (and thus available for defining your OptiPa model) can be checked on the MatLab website. The most important aspects are however covered below. First of all, familiarise yourself with the overall structure of the model definition file as described in detail elsewhere. Subsequently, have a look at the various demo model files to get some ideas of what is possible or not. Some of the MatLab features will be discussed below using the Demo files as examples. We encourage you to play around with them and learn from the consequences! From our experience most models can be properly defined using the limited MatLab instructions outlined below. For more info check out the online Matlab help.

Comments % (percentage sign): anything following the %-sign up to the next line break will be ignored Add as many comments as you like to your model files to make them readable and to help you remember why you did what you did. If you wrote some lines you want to ignore but keep save for the future just comment them out by adding the %-sign.

Example: The following line shows an example where additional info is given after the %-sign. Only the first part of the line is executed: >> Tref=10;

% my current reference temperature for Arrhenius law

The following line shows an example where the whole line is commented out by adding a %-sign at the start of the line. The whole line is ignored: >> % Tref=20;

% my old reference temperature for Arrhenius law

Suppressing output ; (semicolon): Adding a semicolon to a statement suppresses the output of this statement to the screen. You can experiment with this by removing any of the semicolons from an existing OMF-file and check the output on screen. The output generated by your model will now become visible in the black Consolewindow showing the multiple evaluations of the various statements.

Example: The following statement without a semicolon at the end results in displaying the output a follows. >> Tref=10 Tref = 10

The same statement with a semicolon at the end suppresses the output. >> Tref=10;

When forgetting to include the semicolon, simulation or optimisation of the model results in a continuous echoing of output to the black Console-window slowing down the operation of OptiPa.

Rules for variable names MATLAB variable names must begin with a letter, which may be followed by any combination of letters, 31 / 134

digits, and underscores. MATLAB distinguishes between uppercase and lowercase characters, so A and a are not the same variable. Although variable names can be of any length, MATLAB uses only the first 63 characters of the name, and ignores the rest. Hence, it is important to make each variable name unique in the first 63 characters to enable MATLAB to distinguish variables. When naming a variable, make sure you are not using duplicate names.

Assigning data to variables Variable names are used as placeholders for data. First you have to assign some data to variables before you can use them.

Example



Each model definition file start with a section to define fixed constants. Following the guideline above the definition of these scalar variables should look something like: >> VariableName = NumericalValue; And again, feel free to add some explanatory comments: >> Hmin=124; >> Tref=15;

% the asymptotic hue value at minus infinite time % reference temperature for Arrhenius law

Arithmetic operators + * / ^ () ...

Addition Subtraction Multiplication Division Power Specify evaluation order 'Soft' line break to spread out long expressions over multiple lines

Example >> Deriv(PGact) = ka_PG*PG_pre*PG_act - ki_PG*PG_act; >> Deriv(FRC_C_U) = S00_C*ADP_C*k_SUSY_C + S10_C*ADP_C*k_SUSY_C ... - G6P_C_T*FRC_C_U*ATP_C*k_SUSYR_C + FRC_V_U*k_FRC_VCt/Vcy ... - FRC_C_U*k_FRC_CVt/Vcy - FRC_C_U*ATP_C*k_FRP_C ... + S00_C*k_INV_C + S10_C*k_INV_C - GLC_C_T*FRC_C_U*k_INVR_C ... - k_ISO_C*FRC_C_U + k_ISOR_C*GLC_C_U; >> Deriv(O2) = -Vmax*O2 / (km + O2); >> EH_SS = Enz_0/(((10^(-pH))/KE1)+(KE2/(10^(-pH)))+1);

These examples are taken from the ODE model definition part where the core of the model is defined. At every single time step the ODE integrator will evaluate these statements to calculate the change over time to get to the next time step. All variables involved in these calculations are scalars (single values). This is true for the model constants (e.g. a Tref, Rgas, ...) the model parameters (e.g. ka_PG, ki_PG, Vmax, km, Enz_0, KE1, KE2), but also the model output variables (e.g. PG_pre, PG_act, O2, pH) as they just contain the current value at the current time step of the ODE integrator.

Function calls Depending on the need of the model program, calls to external functions can be made assuming these functions are part of the MatLab base system which is available in this runtime version of OptiPa.

Example Elementary Math Trigonometric (in radians) Y=sin(X) Y=cos(X) Y=tan(X) Y=asin(X) Y=acos(X)

Trigonometric (in degrees) Y=sind(X) Y=cosd(X) Y=tand(X) Y=asind(X) Y=acosd(X)

sine cosine tangens inverse sine inverse cosine

32 / 134

Exponential Y = exp(X) Y = log(X) Y = log10(X) Y = sqrt(X)

exponential Natural logarithm Common logarithm Square root

Y=atan(X)

Y=atand(X)

inverse tangens

Temperature dependency according Arrhenius k=karr(kref,Ea,Temp,Tref) OUTPUT: k: value(s) of rate constant valid at temperature Temp PARAMETERS: kref: a single reference value for rate constant k valid at reference temperature Tref Ea: energy of activation (J/mol) Temp: a single value, vector or matrix of temperatures (in °C) Tref: an arbitrary reference temperature (in °C) at which kref is valid USAGE: to calculate Arrhenius equation using the various model parameters as input in combination with a fixed global model parameter (Tref) and the actual temperature as interpolated from the condition file. k1=karr(k1ref,Ea1,TempAct,Tref); k2=karr(k2ref,Ea2,TempAct,Tref); kv=karr(kvref,Eav,TempAct,Tref);

Flow control MatLab functions can be used to provide additional flow control. Think of if..else or for..while statements

Example This example shows how, based on the current time point t and the levels of O2 (pO2, which is interpolated from the condition files) different values are assigned to the model variable k1ref. The O2 levels actually varies depending on the experiment that is being analysed. The constants ULO and CA are part of the parameters being optimised. %------------------------------------------------------------------------------------% choosing the correct value of k1ref depending on the O2 level %------------------------------------------------------------------------------------if t >= 244 % this is the shelflife where we have AIR conditions throughout k1ref=k1ref; elseif t