User's Reference (SBPD)

Most up-to-date information I try to keep the information in this user's reference up-to-date. However, since I do have a job it is not always 100% possible. You find the most up-to-date information when calling "help SBPD" in MATLAB.

Project Representation - Overview

Project Syntax	Projects are described using an intuitive and user-friendly folder structure. Learn more here!
Project Representation	Projects contain models, experiment descriptions, and corresponding measurement data. They are the basis for the parameter estimation and tuning functionality. Furthermore, they allow a clear and useful organization of your modeling task. This section explains the internal storage format of SBPDprojects.

MEX Simulation Function - Overview

MEX Simulation Function	The SBPD package creates and uses MEX simulation functions. These functions are compiled C-code versions of SBmodels linked together with the CVODES integrator and a MATLAB interface. In this way a simulation performance of stand-alone software applications is obtained, while still keeping MATLABs flexibility in handling the returned simulation data and the models.

Functions - Overview

Installation of SBPD
installSBPD	Installation script for the SBPD package.
helpSBPD	SBPD help function (requires internet connection).
registerSBPD	Registration of SBPD (free of charge for non-commercial use).
Project Creation and Handling
SBPDproject	Creating a new SBPDproject.
SBPDgui	Graphical User Interface for parameter estimation on projects.
SBPDstruct	Returns the internal data structure of an SBPDproject.
SBPDexportproject	Export a project to a directory structure.
SBPDsaveproject	Save a project in a MAT file (extension: .sbp).
isSBPDproject	Checks if the given argument is an SBPDproject.
SBPDinfo	Display information about the project.
SBPDplotmeasurements	Visualize all measurements in the project.
SBPDgetmodel	Get specified model from project.
SBPDgetexperiment	Get specified experiment from project.
SBPDgetmeasurement	Get specified measurement from project.
SBPDcomparemeasurements	Compare measurements to model in project.
SBPDupdatemodel	Update or add a model in a project.
SBPDupdateexperiment	Update or add an experiment in a project.
SBPDupdatemeasurement	Update or add a measurement in a project.
SBPDexportestimation	Export estimation settings to a flat file.
MEX Model Creation and Handling
SBPDmakeMEXmodel	Creating a MEX simulation function for a given SBmodel.
makeTempMEXmodelSBPD	Creating a temporary MEX simulation function for a given SBmodel (in systems temp folder).
mexcompileSBPD	Compilation of a given C model function to a MEX simulation function.
makeparamvecSBPD	Creating full parameter vector and changing given parameters to given new values.
makeinicondvectorSBPD	Creating full initial condition vector and changing given states to given new values.
getparamindicesSBPD	Get parameter indices for given parameter names.
getstateindicesSBPD	Get state indices for given state names.
Modeling Functions
SBPDdirectoptss	Tune a model to a desired steady-state by adjusting the velocity parameters of the reaction kinetics.
Kinetic Rate Laws	Several standard kinetic rate laws are inbuild in the SBPD package (listed at the bottom of this page).
Simulation Functions
SBPDsimulate	Wrapper function for simulation of MEX models and SBmodels.
SBPDsensitivity	Function for computing sensitivities of states, variables, and reactions in the model with respect to parameters.
SBPDinsilicoexp	Performs an insilico experiment for given SBmodel and SBexperiment. Visualizes result or exports it to a SBmeasurement representation. Also Excel or CSV measurement files can directly be generated.
SBPDinsilicoexpproj	Performs an insilico experiment directly on a model and experiment within a project. Per default a CSV measurement files is created.
Parameter Identifiability Functions
SBPDidentifiability	Function for determining parameter identifiability based on correlation analysis of sensitivity trajectories. Directly applicable to SBPDprojects.
SBPDparametercorrelation	Function for determining parameter correlations based on parametric sensitivities.
Model Reduction Functions (Require the Symbolic Toolbox)
SBPDreducerateexpressions	Application of the reaction rate expression reduction to a model in a project.
Parameter Estimation Functions
SBPDmanualtuning	Graphical user interface allowing to manually tune the models present in a project.
SBPDmodeltuning	Graphical user interface allowing to manually tune a model to measurements (w/o the need of a project).
SBPDparameterestimation	Allows to estimate parameters for the models in a project, using the experiments and measurements that are defined in the project.
getparamictextSBPD	Auxiliary function to easily construct the text that is necessary to define the parameters and initial conditions to estimate + their upper and lower bounds.
createrunestimationscriptSBPD	Auxiliary function creating a template m-script for running parameter estimations on a given project.
SBPDanalyzeresiduals	Determines and analyzes the residuals for a given project.
SBPDparameterfitanalysis	Generates data to analyze the obtained parameter fit with respect to correlations, local minima, etc.
SBPDfahist	Plots histograms for the parameter values that have been estimated using the SBPDparameterfitanalysis function.
SBPDfaclustering	Performs hierarchical clustering based on Euclidean distance of the parameter sets estimated using the SBPDparameterfitanalysis function.
SBPDfaboxplot	Plots a box-and-whisker diagram for the estimation data, obtained using the SBPDparameterfitanalysis function.
SBPDfacorr	Determines the correlation matrix for the parameter sets determined with the SBPDparameterfitanalysis function.
SBPDfasigncorr	Determines a matrix of p-values for testing the hypothesis of no significant correlation based on the results generated by SBPDparameterfitanalysis.
SBPDfadetcorr	Plots detailed pairwise correlations between parameters.
cutoffdataSBPD	Used to select a cut-off threshold for the estimation data collected during the fit analysis.
Symbolic Math Functions (require the Symbolic Toolbox)
SBPDsymjacobian	Determines the Jacobian of an SBmodel symbolically (requires the symbolic toolbox).
Parameter Estimation Benchmark Projects
Benchmarks	The SBPD package includes several SBPDprojects that can be used as benchmarks for the evaluation of parameter estimation methods.

Project Syntax - Full Description

The syntax of projects, as it is used by the SBTOOLBOX2 and SBPD, is best described by well documented examples. For this purpose there are plenty of examples included in the SPBD package. Below you will find to almost each function description an executable example. Additionally there is an introductory tutorial available that can be found here:

• Introductory tutorial to projects, MEX functions + a little more

Project Representation - Full Description

The SBPDproject object collects models, experiment descriptions, and measurement data for modeling projects.

The internal data structure of an SBPDproject object has the following fields:

name	Name of the project (string)
notes	Notes about the project (string)
models	Cell-array with SBmodels as entries (cell-array)
modeltypes	Vector with 0 or 1 entries, determining the type of the present models: 0=TEXT model, 1=TEXTBC model (vector)
experiments.name	Name of the experiment (string)
experiments.notes	Notes about this experiment (string)
experiments.experiment	=0: SBexperiment object (SBexperiment)
experiments.measurements	Cell-array with SBmeasurement objects corresponding to measurement data for the current experiment (cell-array)
estimations	Not used yet (empty)

Several models can be present in a project. These can, for example, represent different model hypotheses which then are evaluated against the experiments and measurement data that is available in the project. Several experiments can be present. Each experiment can have one or more measurement data object assigned to it.

MEX Simulation Function - Full Description

MEX simulation functions, created by the SBPD package, have the following calling syntax and functionality. 'filename' relates to the name of a MEX simulation function.

output = filename(): returns a vector with the models initial conditions
output = filename('states'): returns a cell array with the models state names
output = filename('parameters'): returns a cell array with the models parameter names
output = filename('parametervalues'): a returns a vector with the models parameter values

The following calls to a MEX simulation function perform simulation of the corresponding model and return the obtained data as a MATLAB structure:

output = filename(timevector)
output = filename(timevector, initialconditions)
output = filename(timevector, initialconditions, parametervector)
output = filename(timevector, initialconditions, parametervector, options)

timevector: Vector of time instants for which simulation data is to be returned
initialconditions: Vector of initial conditions
parametervector: Vector containing a full set of parameter values that are to be used instead of the nominal parameters, stored in the model
options: Structure with options for the integrator. The available fields of this structure and their possible settings are described below. If a certain field is not present in the options structure, default values are used instead for the corresponding setting.
options.abstol: Absolute tolerance (default: 1e-6)
options.reltol: Relative tolerance (default: 1e-6)
options.minstep: Minimal integrator step size (default: 0)
options.maxstep: Maximal integrator step size (default: inf)
options.maxnumsteps: maximum number of steps to be taken by the solver in its attempt to reach the next output time (default: 100000)
options.xdotcalc: =0: integration is done, =1: the output argument consists of the RHS of the ODEs evaluated at the given state and parameter values. Time information is neglected and it is assumed that time=0.

Event handling: If events are present in the model and they are fired during simulation the output data structure contains information about the time instants at which the events fired. For each such time instant it is also specified which event has fired (important in the case of more than one event in the model).

If several events are fired at the same time the event assignments are executed based on the same statevector, present at the time at which the events happened.

Important: If events are present in the model do not use to large timesteps in the timevector.

Functions - Full Description and Examples

Installation of SBPD

installSBPD
Usage	Installation function for the SBPD package. Prior to running it you should edit its contents to match your system. Standard calling syntax: >> installSBPD This function can be called with the optional syntax: >> installSBPD('quick') This adds the SBPD and all subdirectories to the MATLAB path. If you are in a computer environment in which MATLAB is not able to store the path settings you can run this quick installation function each time when starting MATLAB. Note that the quick installation does not build the necessary libraries. This is only done by calling installSBPD without the optional argument. Use this the first time when installing a new version of the package.
Examples	>> installSBPD Clears the workspace and the desktop, closes all open figures, and sets the paths needed for the package.

helpSBPD
Usage	helpSBPD: SBPD help function displaying the web based user reference information using the MATLAB web browser. To be able to use this function you need to have an active internet connection. USAGE: ====== helpSBPD helpSBPD 'helpSBPD functionname' EXAMPLES: ========= helpSBPD helpSBPD SBPDmanualtuning

registerSBPD
Usage	The unregistered version of SBPD is valid for 30 days after installation. If you want to use it further, please register it. For non-commercial use it is, of course, free of charge. Registration can be done by running this script. USAGE: ====== registerSBPD() allows you to obtain a registration key registerSBPD('put the registration key here') finalizes the registration

Project Creation and Handling

output = SBPDproject(input)
Usage	This function creates an SBPDproject object containing models, experiments, measurements, and additional information. input=[] input=[structure] input=[projectin] input=['file.sbp'] input=['foldername'] Invoking SBPDproject without arguments returns an empty SBPDproject. Otherwise SBPDprojects can be created from a data structure that corresponds to the internal project data structure, described above, from a previously defined project projectin, from an MAT file file.sbp in which the project has been stored. Furthermore, a project can be read in from its folder structure, described above. The output consists of an SBPDproject object.
Examples	An example project is available in the SBPD/_EXAMPLES/Projects folder. Change into this folder, have a look at the project folder Example Project. This project can be imported to an SBPDproject by typing: >> project = SBPDproject('Example Project') Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDgui(input)
Usage	SBPDgui: Graphical user-interface for running parameter estimation tasks. More information you find in the "Help" menu of this GUI.
Examples	Just run SBPDgui from the MATLAB command line and have a look at the documentation in the "Help" menu.

output = SBPDstruct(input)
Usage	This function returns the internal data structure of an SBPDproject. input=[project] project is the SBPDproject for which to return the data structure. output=[structure] The output consists of the internal data structure of project, defined above. Note that instead of SBPDstruct also the MATLAB struct command can be used, resulting in exactly the same output.
Examples	First run the example from SBPDproject above. Then type: >> structure = SBPDstruct(project) This returns the internal data structure of the SBPDproject. Please have also a look at the runExample.m script in which many of the examples here are collected.

SBPDexportproject(input)
Usage	Exports a given project to a projectfolder. input=[project] input=[project,foldername] project: SBPDproject object to export foldername: Name of the project folder to export to (default: foldername derived from project name) Note that even though Excel and CSV measurement data files are allowed in projects, during export only CSV files are used. These are much faster to import and a lot more portable accross platforms.
Examples	First run the example from SBPDproject above. Then type: >> SBPDexportproject(project,'exported project') Please have also a look at the runExample.m script in which many of the examples here are collected.

SBPDsaveproject(input)
Usage	Save an SBPDproject object as a binary MATLAB MAT file with .sbp as extension. The name of the project object variable is the same as the name of the file. input=[project] input=[project,filename] project: SBPDproject object to export filename: Name of the project folder to export to (default: filename derived from project name)
Examples	First run the example from SBPDproject above. Then type: >> SBPDsaveproject(project,'project file') Note that the space character in the filename disappears. The saved MAT file can be loaded by: project = SBPDproject('projectfile.sbp') Please have also a look at the runExample.m script in which many of the examples here are collected.

output = isSBPDproject(input)
Usage	This function has a single input argument and simply checks if the input argument is an SBPDproject. If it is an SBPDproject 1 is returned. Otherwise 0.
Examples	First run the example from SBPDproject above. Then type: >> isSBPDproject(project) >> isSBPDproject(523523) Please have also a look at the runExample.m script in which many of the examples here are collected.

SBPDinfo(input)
Usage	Quick dump of contents of an SBPDproject. Mainly used to check if everything is correct and to determine the model, experiment, and measurement indices. input=[project] project: SBPDproject to get the information for.
Examples	First run the example from SBPDproject above. Then type: >> SBPDinfo(project) Please have also a look at the runExample.m script in which many of the examples here are collected.

SBPDplotmeasurements(input)
Usage	SBPDplotmeasurements: Plots all measurements in the given SBPDproject using SBplot. Very useful to get a quick overview over measurement results. The function opens a simple GUI where you in the upper left corner can select the experiment and measurement to display. If error bound information is available in the measurement data this is displayed. USAGE: ====== [] = SBPDplotmeasurements(project) [] = SBPDplotmeasurements(project,experimentindices) project: SBPDproject object experimentindices: vector with indices of the experiments for which to plot the measurement data. Per default the measurement data of all experiments is plotted.
Examples	First run the example from SBPDproject above. Then type: >> SBPDplotmeasurements(project) Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDgetmodel(input)
Usage	Extract model(s) from the given project. input=[project] input=[project,modelindices] project: SBPDproject from which to get (a) model(s). modelindices: indices of the models in project to return (scalar or vector of indices). If no model indices are specified, all the models are returned in a cell-array. If only a single model is returned the model is not stored in a cell-array. If a modelindices argument is specified the corresponding model(s) will be returned.
Examples	First run the example from SBPDproject above. Then type: >> allmodels = SBPDgetmodel(project) >> firstmodel = SBPDgetmodel(project,1) >> allmodels_reversed = SBPDgetmodel(project,[2 1]) Note that the location of a model in the folder does not necessarily determine the model index. The index of the model is easiest determined using the SBPDinfo function. Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDgetexperiment(input)
Usage	Extract experiment(s) from the given project. input=[project] input=[project,experimentindices] project: SBPDproject from which to get (an) experiment(s). experimentindices: indices of the experiments in project to return (scalar or vector of indices). If no experiment indices are specified, all the experiments are returned in a cell-array. If only a single experiment is returned the experiment is not stored in a cell-array. If an experimentindices argument is specified the corresponding experiment(s) will be returned.
Examples	First run the example from SBPDproject above. Then type: >> allexperiments = SBPDgetexperiment(project) >> firstexperiment = SBPDgetexperiment(project,1) >> someexperiments = SBPDgetexperiment(project,[2 1]) Note that the location of an experiment in the folder does not necessarily determine the experiment index. The index of the experiment is easiest determined using the SBPDinfo function. Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDgetmeasurement(input)
Usage	Extract measurements(s) from the given project and experiment. input=[project,experimentindex] input=[project,experimentindex,measurementindices] project: SBPDproject from which to get (an) experiment(s). experimentindex: index of the experiment for which to get the measurements. measurementindices: indices of the measurements in project and experiment to return (scalar or vector of indices). If no measurement indices are specified, all the measurements for this experiment are returned in a cell-array. If only a single measurement is returned the measurement is not stored in a cell-array. If an measurementindices argument is specified the corresponding measurement(s) will be returned.
Examples	First run the example from SBPDproject above. Then type: >> measurements_exp5 = SBPDgetmeasurement(project,5) Note that the location of a measurement in the experiment folder does not necessarily determine the measurement index. The index of the measurement is easiest determined using the SBPDinfo function. Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDcomparemeasurements(input)
Usage	SBPDcomparemeasurements: Simulates the experiments in the project for the models in the project and compares the simulated results to the measurements. USAGE: ====== []/[plotdata] = SBPDcomparemeasurements(project,modelindices) []/[plotdata] = SBPDcomparemeasurements(project,modelindices, experimentindices) []/[plotdata] = SBPDcomparemeasurements(project,modelindices, experimentindices,OPTIONS) project: SBPDproject object modelindices: indices of the models in the project to use for comparison (scalar or vector) experimentindices: vector with indices of the experiments to do the comparison for OPTIONS: structure with integrator options. OPTIONS.abstol: abs tolerance OPTIONS.reltol: rel tolerance OPTIONS.minstep: min step-size of integrator OPTIONS.maxstep: max step-size of integrator OPTIONS.maxnumsteps: maximum number of steps to be taken by the solver in its attempt to reach the next output time DEFAULT VALUES: =============== modelindices: comparison carried out for all models in the project if modelindices is not given experimentindices: all experiments in the project OPTIONS.abstol: 1e-6 OPTIONS.reltol: 1e-6 OPTIONS.minstep: 0 OPTIONS.maxstep: inf OPTIONS.maxnumsteps: 500 Output Arguments: ================= If no output argument is given, the function plots the data using SBPDplot. Otherwise a datastructure (plotdata) is given back that can be used as input argument for SBPDplot.
Examples	First run the example from SBPDproject above. Then type: >> SBPDcomparemeasurements(project) >> plotdata = SBPDcomparemeasurements(project,2) >> SBPDplot(plotdata) Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDupdatemodel(input)
Usage	Update or add a model in a project. input=[project,model] input=[project,model,modelindex] project: SBPDproject in which to update or add a model. model: SBmodel to add or to use for updating. modelindex: index of the model to be updated. If omitted the model is added to the project as last model. The output of the function is the resulting project with updated or added model.
Examples	First run the example from SBPDproject above. Then type: >> firstmodel = SBPDgetmodel(project,1) >> project_new = SBPDupdatemodel(project,firstmodel) This adds the first model in the project as last (third) one. Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDupdateexperiment(input)
Usage	Update or add an experiment in a project. input=[project,experiment] input=[project,experiment,experimentindex] project: SBPDproject in which to update or add an experiment. experiment: SBexperiment to add or to use for updating. experimentindex: index of the experiment to be updated. If omitted the experiment is added to the project as last experiment. The output of the function is the resulting project with updated or added experiment.
Examples	First run the example from SBPDproject above. Then type: >> firstexperiment = SBPDgetexperiment(project,1) >> project_new = SBPDupdateexperiment(project,firstexperiment) This adds the first experiment in the project as last (third) one.

output = SBPDupdatemeasurement(input)
Usage	Update or add a measurement in a project. input=[project,experimentindex,measurement] input=[project,experimentindex,measurement,measurementindex] project: SBPDproject in which to update or add an experiment. experimentindex: Index of the experiment to add the measurement to. measurement: SBmeasurement to add or to use for updating. measurementindex: Index of the measurement to be updated. If omitted the measurment is added to the experiment as last measurement. The output of the function is the resulting project with updated or added measurement.
Examples	First run the example from SBPDproject above. Then type: >> measurement = SBPDgetmeasurement(project,4,1) >> project_new = SBPDupdatemeasurement(project,4,measurement) This adds the first measurement of the fourth experiment as last (second) to the same experiment.

output = SBPDexportestimation(input)
Usage	SBPDexportestimation: Exports the selected estimation settings in an SBPDproject into a flat text file. USAGE: ====== SBPDexportestimation(project,estimationindex,filename) project: SBPDproject estimationindex: the index of the estimation to export filename: name of the file to write the estimation to (*.est)
Examples

MEX Model Creation and Handling

SBPDmakeMEXmodel(input)
Usage	This function converts an SBmodel to an executable C-code MEX model and links it with the CVODE integrator from SUNDIALS. USAGE: ====== [] = SBPDmakeMEXmodel(model) [] = SBPDmakeMEXmodel(model, MEXfile) [] = SBPDmakeMEXmodel(model, MEXfile, doNOTcompileFlag) model: SBmodel MEXfile: the name of the MEX file (default: models name) doNOTcompileFlag: =0 (default): create executable MEX simulation file =1: only create the source code but do not compile
Examples	As example we create a MEX simulation file for the Novak Tyson Cell-Cycle model. Please change into the SBPD/_EXAMPLES folder and type: >> model = SBmodel('NovakTysonModel.txt'); >> SBPDmakeMEXmodel(model,'novaktysonsim'); The last command creates a MEX file with the name 'novaktysonsim'. To learn more about the input and output arguments please read the section "MEX Simulation Function - Full Description" above. Here we are simply running a simple simulation over 400 time units and plot the results. >> simdata = novaktysonsim([0:1:400]) >> plot(simdata.time,simdata.statevalues); >> legend(simdata.states); The SBPDmakeMEXmodel function can also be used to create the C-code for the model without compiling it to a MEX simulation function: >> model = SBmodel('NovakTysonModel.txt'); >> sourceflag = 1; >> SBPDmakeMEXmodel(model,'novaktysonsim',sourceflag); The last command creates a .c and a .h file. You can look at these files to get an idea about how you could write your own C-code models (if so wanted). When specifying a model as .c and .h files you can use the command mexcompileSBPD to create a MEX simulation function for this model.

makeTempMEXmodelSBPD(input)
Usage	This function can be used to create a temporary MEX simulation function. Temporary means that it is created in the systems temp directory and that no name can be chosen, but that a unique temporary filename is automatically chosen and returned. USAGE: ====== [MEXmodel, MEXmodelfullpath] = makeTempMEXmodelSBPD(model) model: SBmodel to convert to a temporary MEX simulation function OUTPUT ARGUMENTS: ================= MEXmodel: name of the MEX simulation function (filename without .mex extension) MEXmodelfullpath: complete path to the created MEX simulation function (including mex extension). This information can be used to delete the function as soon as it is not needed anymore.
Examples	This function should be self explaining and does not need any example.

mexcompileSBPD(input)
Usage	Compiles an SBmodel that has been converted to a mexfile.h and mexfile.c and links it with the CVODE integrator from the SUNDIALS suite (http://www.llnl.gov/CASC/sundials/). USAGE: ====== [] = mexcompileSBPD(mexfile) mexfile: Basename of the model files (mexfile.c and mexfile.h)
Examples	First we create a C-code model. For this change into the SBPD/_EXAMPLES folder and type: >> model = SBmodel('eventExample.txt'); >> doNOTcompileFlag = 1; >> SBPDmakeMEXmodel(model,'Ccodemodel',doNOTcompileFlag); Have a look at the created Ccodemodel.c and Ccodemodel.h files. The compilation to an executable MEX simulation model is done by: >> mexcompileSBPD('Ccodemodel') The model can now be simulated by typing: >> time = [0:1:300]; >> simdata = Ccodemodel(time)

output = makeparamvecSBPD(input)
Usage	The mex simulation functions take a full parameter value vector as an input. In order to construct such a vector while changing some but possibly not all parameter values this function can be used. USAGE: ====== [paramvector] = makeparamvecSBPD(model,parameters,parametervalues) model: SBmodel, ODE file model, or MEX file model parameters: Cell-array of parameter names for which to change the parametervalues parametervalues: Vector with the corresponding values for the parameters OUTPUT: ======= paramvector: Constructed initial condition vector
Examples	Please change into the SBPD/_EXAMPLES folder. We first create a MEX simulation function and simulate it using the default parameters. >> model = SBmodel('Glycolysis.txt'); >> SBPDmakeMEXmodel(model,'test'); >> simdata = test([0:0.1:20]); >> plot(simdata.time,simdata.statevalues); Now we want to change the parameter Glcx0 to 10 and simulate again. This does not require rebuilding the MEX simulation function, but instead you can type: >> parametervector = makeparamvecSBPD('test',{'Glcx0'},[10]); >> simdata = test([0:0.1:20],[],parametervector); >> plot(simdata.time,simdata.statevalues); You can also change several parameters at a time by specifying several names in the cell array and corresponding values in the vector.

output = makeinicondvectorSBPD(input)
Usage	The mex simulation functions take a full initial condition vector as an input. In order to construct such a vector while changing some but possibly not all IC values this function can be used. USAGE: ====== [icvector] = makeinicondvectorSBPD(model,states,statevalues) model: SBmodel, ODE file model, or MEX file model states: Cell-array of state names for which to change the ICs statevalues: Vector with the corresponding values for the ICs of the states. OUTPUT: ======= icvector: Constructed initial condition vector
Examples	This function should be self explaining and does not need any example.

output = getparamindicesSBPD(input)
Usage	Determines a vector of model parameter indices, the order corresponding to the parameters argument. USAGE: ====== [output] = getparamindicesSBPD(model,parameters) model: SBmodel, ODE file model, or MEX simulation model parameters: Cell-array of parameter names OUTPUT: ======= output: Vector of parameter indices
Examples	This function should be self explaining and does not need any example.

output = getstateindicesSBPD(input)
Usage	Determines a vector of model state indices, the order corresponding to the states argument. USAGE: ====== [output] = getstateindicesSBPD(model,states) model: SBmodel, ODE file model, or MEX simulation model states: Cell-array of state names OUTPUT: ======= output: Vector of state indices
Examples	This function should be self explaining and does not need any example.

Modeling Functions

output = SBPDdirectoptss(input)
Usage	This function applies the direct optimization method to impose a desired steady-state (in terms of state concentrations and reaction rates) on the given model by adjusting the velocity rate parameters of the reactions. Due to the latter, the function is only applicable to models whos ODE right hand side are described by reactions and stoichiometric coefficients. The adjustment of the velocity parameters is done by multiplying determined numerical factors to the rate expressions. Example: R = k1*A - k2*B is changed to: R = factor*(k1*A-k2*B) REFERENCE: The function is based on the method presented and used in: F. Hynne, S. Danø, P.G. Sørensen (2001) Full-scale model of glycolysis in Saccharomyces cerevisiae, Biophysical Chemistry, 94, 121-163 input=[model, ssStates, ssReactions] model: SBmodel to optimize ssStates: Desired steady-state of the model ssReactions: Reaction rates at desired steady-state The output argument is the optimized model.
Examples	This function should be self explaining and does not need any example. Just try it and you will see :-)

Simulation Functions

output = SBPDsimulate(input)
Usage	Function allowing to simulate SBmodels and MEX simulation functions. SBmodels are first converted to temporary MEX simulation functions, so that a conversion overhead is present. USAGE: ====== output = SBPDsimulate(model) output = SBPDsimulate(model, time) output = SBPDsimulate(model, time, ICs) output = SBPDsimulate(model, time, ICs, paramNames, paramValues) output = SBPDsimulate(model, time, ICs, paramNames, paramValues, ... OPTIONS) model: Name of MEX simulation function OR SBmodel time: Either simulation end time (scalar) or simulation time vector. ICs: Vector of initial conditions. paramNames: Cell-array with the names of the parameters for which the values are to be changed to given values. paramValues: Vector of parameter values for the given parameters. OPTIONS: structure with integrator options. OPTIONS.abstol: abs tolerance OPTIONS.reltol: rel tolerance OPTIONS.minstep: min step-size of integrator OPTIONS.maxstep: max step-size of integrator OPTIONS.maxnumsteps: maximum number of steps to be taken by the solver in its attempt to reach the next output time DEFAULT VALUES: =============== time: 20 ICs: values stored in the model paramNames: {} do not change any parameters paramValues: [] OPTIONS.abstol: 1e-6 OPTIONS.reltol: 1e-6 OPTIONS.minstep: 0 OPTIONS.maxstep: inf OPTIONS.maxnumsteps: 100000 Output Arguments: ================= If no output arguments are given, the result of the simulation is plotted after finished simulation. The output of SBPDsimulate is realized as a structure: output.time: vector with time instants for the results output.states: cell-array with state names output.statevalues: matrix with state values. Each row corresponds to one time instant output.variables: cell-array with variable names output.variablevalues: matrix with variable values. Each row corresponds to one time instant output.reactions: cell-array with reaction names output.reactionvalues: matrix with reaction values. Each row corresponds to one time instant In the case events are present in the model the following fields are present in the output structure additionally: output.events: cell-arra with the names of the events output.eventtimes: vector with time instants at which events happened output.eventflags: matrix of dimension: 'number of events' x 'number of event time instants'. Each column in this matrix correponds to one timeinstant in the output.eventtimes vector. The row numbers correspond to the numbers of the events. A "1" element in the matrix indicates that the corresponding event has happened at the corresponding time. A "0" element tells you that the event has not been fired at the corresponding instant.
Examples	Please change into the SBPD/_EXAMPLES folder and type: >> model = SBmodel('eventExample.txt'); >> SBPDmakeMEXmodel(model,'test'); >> options.reltol = 1e-8; >> simdata = SBPDsimulate('test',[],[],{},[],options) >> plot(simdata.time,simdata.statevalues) Please have a look at the simdata output of the simulation. The structure contains also information about the times at which events in the model fired and in the case that several events are present which event fired at what time. If you want to redo a simulation for a different parameter setting you do not need to edit the SBmodel and create the MEX simulation function again. You can instead specify the name of the parameters you want to change and the new values: >> time = 40; >> inicond = []; % use nominal initial conditions >> parameters = {'k1'} % change parameter k1 >> paravalues = [0.1]; % to the value of 0.1 (nominal is 1) >> simdata = SBPDsimulate('test',time,inicond,parameters, paravalues, options) >> plot(simdata.time,simdata.statevalues);

output = SBPDsensitivity(input)
Usage	This is a wrapper function for MEX simulation functions for forward sensitivity analysis (parameters and initialconditions). The function can be used on SBmodels and MEX simulation functions. USAGE: ====== output = SBPDsensitivity(model, timevector) output = SBPDsensitivity(model, timevector, parameternames) output = SBPDsensitivity(model, timevector, parameternames, ... statenames) output = SBPDsensitivity(model, timevector, parameternames, ... statenames, options) output = SBPDsensitivity(model, timevector, parameternames, ... statenames, options, nomparamvalues, ... nomicvalues) model: SBmodel or MEX simulation function timevector: a vector of time steps at which to return the simulation data parameternames: cell-array containing the names of the parameters for which to calculate the sensitivities. (default: all parameters in the model) statenames: cell-array containing the names of the states for whose initial conditions to calculate the sensitivities. (default: no states) options: structure with options for the integrator and sensitivity calculation options.pertfactor: relative perturbation if parameter not equal to zero. Otherwise absolute peturbation options.abstol: absolute tolerance options.reltol: relative tolerance options.minstep: minimal integrator step size options.maxstep: maximal integrator step size options.maxnumsteps: maximum number of steps to be taken by the solver in its attempt to reach the next output time nomparamvalues: vector of nominal parameter values nomicvalues: vector of nominal initial condition values DEFAULT VALUES: =============== parameternames: (all parameters) statenames: (no states) options.pertfactor: 1e-5 options.abstol: 1e-6 options.reltol: 1e-6 options.minstep: 0 options.maxstep: inf options.maxnumsteps: 100000 nomparamvalues: parameter values stored in the model nomicvalues: initial condition values stored in the model Output Arguments: ================= If no output arguments are given, the result of the simulation is plotted after finished simulation (only states, variables, reactions). The sensitivities are not plotted! The output of SBPDsensitivity is realized as a structure: output.time: vector with time instants for the results output.states: cell-array with state names output.statevalues: matrix with state values. Each row corresponds to one time instant The following fields are only present in case options.simdata = 'all' is defined. output.variables: cell-array with variable names output.variablevalues: matrix with variable values. Each row corresponds to one time instant output.reactions: cell-array with reaction names output.reactionvalues: matrix with reaction values. Each row corresponds to one time instant In the case events are present in the model the following fields are present in the output structure additionally: output.events: cell-arra with the names of the events output.eventtimes: vector with time instants at which events happened output.eventflags: matrix of dimension: 'number of events' x 'number of event time instants'. Each column in this matrix correponds to one timeinstant in the output.eventtimes vector. The row numbers correspond to the numbers of the events. A "1" element in the matrix indicates that the corresponding event has happened at the corresponding time. A "0" element tells you that the event has not been fired at the corresponding instant. Sensitivity trajectoried are returned as follows: output.sensparameters: cell-array containing the names of the parameters for which sensitivities are determined output.paramtrajectories.states: cell-array containing one entry for each parameter in output.sensparameters (same order). Each entry consists of a matrix, where the columns correspond to state sensitivities wrt to the parameter and the rows correspond to the different integration time points, given in output.time. output.paramtrajectories.variables: same as above just for variables output.paramtrajectories.reactions: same as above just for reactions output.sensicstates: cell-array containing the names of the states for which initial conditions sensitivities are determined output.ictrajectories.states: cell-array containing one entry for each state in output.sensicstates (same order). Each entry consists of a matrix, where the columns correspond to state sensitivities wrt to the initial conditions and the rows correspond to the different integration time points, given in output.time. output.ictrajectories.variables: same as above just for variables output.ictrajectories.reactions: same as above just for reactions
Examples	Please change into the SBPD/_EXAMPLES folder and type: >> model = SBmodel('NovakTysonModel.txt'); >> senssimdata = SBPDsensitivity(model,[0:1:400]) Please have a look at the senssimdata output of the simulation. The field 'senssimdata.sensparameters' contains a cell array with the names of the parameters for which the sensitivities have been computed. The field 'sensimdata.paramtrajectories' is a structure with three fields, containing the state, variable, and reaction sensitivities. Each element in these fields contains the sensitivity trajectories for the correponding parameter in the 'senssimdata.sensparameters' array (same order). (Same for initial condition sensitivities in the fields: 'senssimdata.sensicstates' and 'sensimdata.ictrajectories').

output = SBPDinsilicoexp(input)
Usage	SBPDinsilicoexp runs an in-silico experiment. Simulated data can be returned in the SBmeasurement format, plotted, or written in a CSV or Excel measurement file (the latter only under Windows). USAGE: ====== [] = SBPDinsilicoexp(model,experiment,timevector [,OPTIONS]) [] = SBPDinsilicoexp(model,experiment,timevector,measurements [,OPTIONS]) [] = SBPDinsilicoexp(model,experiment,timevector,measurements, filetypeFlag [,OPTIONS]) [] = SBPDinsilicoexp(model,experiment,timevector,measurements, filetypeFlag,filename [,OPTIONS]) [output] = SBPDinsilicoexp(model,experiment,timevector [,OPTIONS]) [output] = SBPDinsilicoexp(model,experiment,timevector, measurements [,OPTIONS]) model: SBmodel to perform the insilico experiment on experiment: SBexperiment object to apply timevector: Timevector to be used for simulation measurements: cell-array with the names of the components to measure (states, variables, reactions) filetypeFlag: 0=plot results, 1=CSV measurement file, 2=Excel measurement file filename: Name of the measurement file (or of the measurement) to generate OPTIONS: structure with integrator options. OPTIONS.abstol: abs tolerance OPTIONS.reltol: rel tolerance OPTIONS.minstep: min step-size of integrator OPTIONS.maxstep: max step-size of integrator OPTIONS.maxnumsteps: maximum number of steps to be taken by the solver in its attempt to reach the next output time DEFAULT VALUES: =============== measurements: all states are measured filetypeFlag: 0 (plot the results). If output argument is specified, the setting of the filetype flag is ignored filename: combination of model and experiment name OPTIONS.abstol: 1e-6 OPTIONS.reltol: 1e-6 OPTIONS.minstep: 0 OPTIONS.maxstep: inf OPTIONS.maxnumsteps: 500 Output Arguments: ================= output: An SBmeasurement object with the resulting data
Examples	First run the example from SBPDproject above. Then type: >> model = SBPDgetmodel(project,2) >> experiment = SBPDgetexperiment(project,6) >> SBPDinsilicoexp(model,experiment,[0:5:120]) >> SBPDinsilicoexp(model,experiment,[0:5:120],{'Th','ThMP','ThDP'},1) >> edit onemodel_Accumulation_10um_thiamine.csv Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDinsilicoexpproj(input)
Usage	SBPDinsilicoexpproj runs an in-silico experiment directly on a model and experiment within a project. Simulated data can be returned in the SBmeasurement format, plotted, or written in a CSV or Excel measurement file (the latter only under Windows). Note: In contrast to SBPDinsilicoexp, this function per default exports the insilico generated data to a CSV measurement file. USAGE: ====== [] = SBPDinsilicoexpproj(project,modelindex,experimentindex, timevector [,OPTIONS]) [] = SBPDinsilicoexpproj(project,modelindex,experimentindex, timevector,measurements [,OPTIONS]) [] = SBPDinsilicoexpproj(project,modelindex,experimentindex, timevector,measurements,filetypeFlag [,OPTIONS]) [] = SBPDinsilicoexpproj(project,modelindex,experimentindex, timevector,measurements,filetypeFlag,filename [,OPTIONS]) [output] = SBPDinsilicoexpproj(project,modelindex,e xperimentindex,timevector [,OPTIONS]) [output] = SBPDinsilicoexpproj(project,modelindex, experimentindex,timevector,measurements [,OPTIONS]) project: SBPDproject to perform the experiment on modelindex: Index of the model in the project to be used experimentindex: Index of the experiment to be used (scalar only) timevector: Timevector to be used for simulation measurements: cell-array with the names of the components to measure (states, variables, reactions) filetypeFlag: 0=plot results, 1=CSV measurement file, 2=Excel measurement file filename: Name of the measurement file (or of the measurement) to generate OPTIONS: structure with integrator options. OPTIONS.abstol: abs tolerance OPTIONS.reltol: rel tolerance OPTIONS.minstep: min step-size of integrator OPTIONS.maxstep: max step-size of integrator OPTIONS.maxnumsteps: maximum number of steps to be taken by the solver in its attempt to reach the next output time DEFAULT VALUES: =============== measurements: all states are measured filetypeFlag: 1 (export to CSV file). If output argument is specified, the setting of the filetype flag is ignored filename: combination of model and experiment name OPTIONS.abstol: 1e-6 OPTIONS.reltol: 1e-6 OPTIONS.minstep: 0 OPTIONS.maxstep: inf OPTIONS.maxnumsteps: 500 Output Arguments: ================= output: An SBmeasurement object with the resulting data
Examples	First run the example from SBPDproject above. Then type: >> SBPDinsilicoexpproj(project,2,7,[0:5:120]) Please have also a look at the runExample.m script in which many of the examples here are collected.

Parameter Identifiability Functions

output = SBPDidentifiability(input)
Usage	SBPDidentifiability: Performs parameter identifiability analysis for a given project, based on SBPDsensitivity and SBPDparametercorrelation. The model and the experiments to consider can be chosen. Timepoints to take into account are determined from the measurement data that are available in the project. More information can be found in the help text to the SBPDparametercorrelation function. USAGE: ====== output = SBPDidentifiability(project, parameters) output = SBPDidentifiability(project, parameters, options) project: SBPDproject to analyze parameters: Cell-array of parameternames for which to determine the identifiability options: structure with the following fields: options.pValueFlag: =0: plot correlations, =1: plot p-values options.pValueCutOff: pValue for which to make a decision if correlated or not. (For plotting purposes the pValues below the threshold are set to zero) options.modelindex: Index of the model in the project to consider options.experimentindices: Vector of indices indicating the experiments to consider options.integratoroptions.abstol: abs tolerance options.integratoroptions.reltol: rel tolerance options.integratoroptions.minstep: min step-size of integrator options.integratoroptions.maxstep: max step-size of integrator options.integratoroptions.maxnumsteps: maximum number of steps to be taken by the solver in its attempt to reach the next output time
Examples	First run the example from SBPDproject above. Then type: >> modelindex = 1; >> options.modelindex = modelindex; >> parameters = SBparameters(SBPDgetmodel(project,modelindex)); >> SBPDidentifiability(project,parameters,options) Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDparametercorrelation(input)
Usage	Function for determining parameter correlations based on parametric sensitivities. The result can be used to check a priori identifiability of parameters for given experimental settings. Several experiments can be combined. Measured states AND measured variables can be considered. The method is based on: Jacques, J.A. and Greif, P. (1985) Numerical parameter identifiablity and estimability: Integrating identifiability, estimability, and optimal sampling design, Mathematical Biosciences, 77, pp. 201-227 This function determines correlations between parameters. The inputs to this function are parameter sensitivity trajectories returned from the SBAOsenssim function, reflecting the sensitivity of the states and variables to parameter changes during user-defined experiments. From this information a parameter correlation matrix is determined. Off-diagonal elements in this matrix that are close to +1 or -1 indicate problems in identifying the corresponding parameters independently. Elements that are close to zero indicate that there is no important correlation between the corresponding elements and thus these parameters should be identifiable independently without problem (for the defined experiments). A priori identifiability: The identifiability is a local property. For different sets of parameter values different correlation matrices can be obtained. Since unknown parameters are, by definition, unknown this might lead to problems interpreting the results. However, one possible approach is to run the identifiability analysis for different sets of parameter values, randomly chosen in certain intervals around a best initial guess. input = [senssimdata,sensparameters,measuredcomponents] senssimdata: Cell-array with output arguments from the sensitivity analysis function SBPDsensitivity. The simulation should reflect (wrt, e.g., sampling time, stimuli) the experiments that are planned to obtain measurement data for the parameter estimation. sensparameters: Cell-array with parameter names for which to determine the correlations. measuredcomponents: structure defining the measured states and variables: measuredcomponents.states measuredcomponents.variables It is possible to specify just one set of measured components. But it is also possible to specify one set per senssimdata. When called without an output argument the parameter correlation matrix is graphically represented. For easier graphical interpretation the absolute values of the matrix elements are taken. White color indicates a perfect correlation and black color indicates no correlation between parameters. If an output argument is given, the results are returned as a MATLAB structure as follows: output.sensparameters: Cell-array with parameter names output.correlationMatrix: Parameter correlation matrix
Examples

Model Reduction Functions (Require the Symbolic Toolbox)

output = SBPDreducerateexpressions(input)
Usage	Function allowing the interactive and iterative reduction of complex kinetic rate expressions. The function is directly applicable to projects and will reduce a selected model of the project using all or selected experiments from the project. input = [project] input = [project,modelindex] input = [project,modelindex,experimentindices] input = [project,modelindex,experimentindices,options] project: SBPDproject to consider for reduction. modelindex: Index of the model to reduce (default: 1). experimentindices: Vector of indices of the experiments to consider (time-points will be taken from the available measurements. In case no measurements are available, they can be generated using the SBPDinsilicoexp function) (default: all experiments). options: Structure with possible options: options.tol: Tolerance for singularity detection (smallest SV) (default: 1e-6) options.keeporigparameters: =0: do not keep original parameters, =2: do always keep original parameters, =1: keep original parameters only if it leads to fewer parameters (default: 0) options.numeratorweighting: =1: weight numerator terms and denumerator terms such that numerators are kept, =0: dont do any weighting (default: 0) The output argument consists of the same SBPDproject as given by the input argument but with the fully reduced model added to it.
Examples	Please have a look at the example script reduceExample.m in the SBPD\examples\ModredExample folder.

Parameter Estimation Functions

output = SBPDmanualtuning(input)
Usage	SBPDmanualtuning: Allows to compare simulated experiments data to measurements and perform manual parameter tuning. Additionally it is possible to run simulations of selected experiments directly from the SBPDmanualtuning window, allowing for a deeper analysis of what happens in the system. USAGE: ====== [project] = SBPDmanualtuning(project) [project] = SBPDmanualtuning(project,modelindex) [project] = SBPDmanualtuning(project,estimation) [project] = SBPDmanualtuning(project,modelindex, ... additionalcomponents) [project] = SBPDmanualtuning(project,estimation, ... additionalcomponents) project: SBPDproject to tune manually. modelindex: The index of the model in the project to use for tuning. estimation: Same structure as used for parameter estimation (SBPDparameterestimation), defining the (global) parameters and their bounds, and modelindex. additionalcomponents: Cell-array containing the names of components (states or variables) that have not been measured but which should also be plotted in SBPDmanualtuning. DEFAULT VALUES: =============== modelindex: 1:n, where n is the number of the models in the project. This means that tuning is carried out for all models in the project if modelindex is not given estimation: all global parameters and all models, bounds: nominalvalue*[0.01 100] additionalcomponents: {} (none) Output Arguments: ================= The manually tuned project is given back.
Examples	First run the example from SBPDproject above. Then type: projecttuned = SBPDmanualtuning(project,2) Please have also a look at the runExample.m script in which many of the examples here are collected.

output = SBPDmodeltuning(input)
Usage	SBPDmodeltuning: Allows to compare and tune a model to one or more sets of data. Here: No experiment description is required, the model is assumed to already include the experimental settings. USAGE: ====== modeltuned = SBPDmodeltuning(model,data) modeltuned = SBPDmodeltuning(model,data,options) model: SBmodel to tune data: Single SBmeasurement object or cell-array with SBmeasurement objects to which to fit the model options: still unused DEFAULT VALUES: =============== Output Arguments: ================= modeltuned: The tuned model with changed parameters
Examples	Just try it out ... its straight-forward.

output = SBPDparameterestimation(input)
Usage	This function performs parameter estimation for a given SBPD project. Multiple experiments per project and multiple measurements per experiment can easily be handled. Initial conditions can be estimated, global model parameters can be estimated, but also "local" parameters that depend on each experiment. USAGE: ====== [output] = SBPDparameterestimation(project,estimation) [output] = SBPDparameterestimation(project,estimation, noStopButtonFlag) project: SBPDproject for which to do the estimation noStopButtonFlag: 0: stop button, 1: no stop button estimation: Structure that defines what to do. estimation.modelindex: index of the model in the project for which to do the estimation (default: 1) estimation.experiments.indices: vector with indices of the experiments in the project for which to do the estimation (default: []: all experiments) estimation.experiments.measurementindices: cell-array with vector entries, definining the indices of the measurements to take into account for each selected experiment (default: {} (use all measurements available)) estimation.experiments.weight: vector with weights of the experiments in the project for which to do the estimation (default: all weights "1"). estimation.experiments.measurementweight: cell-array with vector entries, definining the weight of the measurements to take into account for each selected experiment (default: all weights "1"). Note that the measurementweights, if defined, override the weights on the experiments! Experiment weights are assigned equally to all measurements within the corresponding experiment. The parameters to be estimated and their upper and lower bounds can be specified in a cell-matrix in which the first column contains the names of the parameters, the second column the lower bounds and the third column the upper bounds. This cell-matrix needs to be assigned to the following field: estimation.parameters Alternatively, parameters and lower and upper bounds can be specified as follows: estimation.parameters.names: cell-array with names of parameters to be optimized (default: {} (estimate all parameters in the model)) estimation.parameters.lowbounds: lower bounds for the parameters. If scalar, then this scalar is multiplied to the initial guesses to obtain the lower bounds. Otherwise, a vector can be specified with the same length as the number of parameters to be optimized. (default: 1e-3 (1e-3*initialguess)) estimation.parameters.highbounds: upper bounds for the parameters. If scalar, then this scalar is multiplied to the initial guesses to obtain the upper bounds. Otherwise, a vector can be specified with the same length as the number of parameters to be optimized. (default: 1e3 (1e3*initialguess)) The local parameters to be estimated and their upper and lower bounds can be specified in a cell-matrix in which the first column contains the names of the parameters, the second column the lower bounds and the third column the upper bounds. This cell-matrix needs to be assigned to the following field: estimation.parameterslocal Alternatively, local parameters and lower and upper bounds can be specified as follows: estimation.parameterslocal.names: cell-array with names of parameters to be optimized locally (independently for each experiment). Initial guesses are obtained from the nominal model/nominal experiment. (default: {} (don't do any local estimation)) estimation.parameterslocal.lowbounds: same as for the parameters above, just for the parameters to be estimated locally. (default: 1e-3 (1e-3*initialguess)) estimation.parameterslocal.highbounds: same as for the parameters above, just for the parameters to be estimated locally. (default: 1e3 (1e3*initialguess)) The states for which to estimate the initial conditions and their upper and lower bounds can be specified in a cell-matrix in which the first column contains the names of the parameters, the second column the lower bounds and the third column the upper bounds. This cell-matrix needs to be assigned to the following field: estimation.initialconditions NOTE THAT: initial conditions are always estimated independently for each experiment! Alternatively, states and lower and upper bounds can be specified as follows: estimation.initialconditions.names: names of the states for which to optimize the initial conditions. Optimization is done for one experiment at a time. No starting guesses can be specified. These are taken from the model and the experiment description + measurements. (default: {} (don't estimate initial conditions)) estimation.initialconditions.lowbounds: scalar or vector. Same procedure as for parameter lowbounds. (default: 1e-3 (1e-3*nominalvalues)) estimation.initialconditions.higbounds: scalar or vector. Same procedure as for parameter highbounds. (default: 1e3 (1e3*nominalvalues)) estimation.optimization.method: name of an optimization function. This function has to be present in the MATLAB path and the input/output interface has to be the same as in the SBTOOLBOX2 optimization methods. (default: 'simplexSB') estimation.optimization.options: options for the optimization method (third input argument to the optimization method). It is assumed that these options are defined in a structure (see simplexSB.m as example). (default: [] (default options for optimization method)) estimation.integrator.options: options for the integration using MEX simulation files. These are defined as a structure. The available fields, etc. are documented in the help text of the SBPDsimulate function. (default: [] => standard options). estimation.initialconditionsFlag: 0=nominal from model or experiment description, 1=average from first timepoint in measurements (default: 1) estimation.displayFlag: show output or not (0=none, 1=final, 2=1+iterations, 3=2+othermessages (default: 2) estimation.scalingFlag: 0=no scaling, 1=scaling by max(abs()) values in measurements, 2=scaling by mean values of measurements, 3=scaling by min/max bounds: [x_measured(ti)-x(ti)]^2/[xmax(ti)-xmin(ti)]^2 This last scaling alternative is only possible, if all max and min values for all the measurements are defined in the measurement data. estimation.timescalingFlag: timescaling is useful in cases of nonequidistant sampling, where some ranges are tightly sampled and others aren't. If equidistant sampling then this flag has no effect. Otherwise the effect is maximal im it is set to 1, with decreasing effect as it increases. (default: 0) estimation.costfunction: string with the name of a custom costfunction for the estimation. The input output interface of this function needs to be compatible with the "defaultcostparameterestimationSBPD" function. (default: 'defaultcostparameterestimationSBPD') Output Arguments: ================= The output is given as a structure: parameters: cell-array with names of optimized parameters Popt: vector with values of optimized parameters parameterslocal: cell-array with names of locally optimized parameters (for each experiment indenpendently) PLOCALopt: vector with values of locally optimized parameters icnames: cell-array with names of states for which the initial conditions have been optimized ICopt: vector with values of optimized initial conditions FVALopt: optimal cost function value projectopt: SBPDproject with updated optimized model and initial conditions in the experiment descriptions estimation: The estimation input argument
Examples	Please have also a look at the runEstimation.m script in the SBPD/_EXAMPLES/Projects folder.

output = getparamictextSBPD(input)
Usage	getparamictextSBPD: This function aids in constructing the text that is needed to define the global and local parameters and the initial conditions for parameter estimation purposes. It works both on project and models. USAGE: ====== getparamictextSBPD(model) getparamictextSBPD(project) getparamictextSBPD(project,modelindex) getparamictextSBPD(model,OPTIONS) getparamictextSBPD(project,OPTIONS) getparamictextSBPD(project,modelindex,OPTIONS) [output] = getparamictextSBPD(model) [output] = getparamictextSBPD(project) [output] = getparamictextSBPD(project,modelindex) [output] = getparamictextSBPD(model,OPTIONS) [output] = getparamictextSBPD(project,OPTIONS) [output] = getparamictextSBPD(project,modelindex,OPTIONS) model: SBmodel project: SBPDproject modelindex: The index of the model in an SBPDproject to use OPTIONS: a structure with additional informations OPTIONS.lowerbounds: scalar factor, determining the lower bound for a parameter by: factor*"original parameter value". OPTIONS.highbounds: scalar factor, determining the upper bound for a parameter by: factor*"original parameter value". DEFAULT VALUES: =============== modelindex: 1 OPTIONS.lowbounds: 0.1 OPTIONS.highbounds: 10 Output Arguments: ================= If no output argument is specified, the determined text it written out in the matlab command window. Otherwise, the information is returned in a structure: output.completeText: The complete text. output.parametersText: Only the parameters with bounds output.initialConditionsText: Only the initial conditions with bounds Note that automatically no distinction between parameters can be made that are to be estimated locally or globally. Therefore, all parameters appear in the complete text in the global parameter section. Just copy and paste when you need it!
Examples	Please have also a look at the run_ex1.m script in the SBPD/_EXAMPLES/benchmarkprojects folder. You can see there how the parameters/initial conditions and their respective upper and lower bounds are defined for parameter estimation. Now, type the following: >> novak_tyson % this loads an SBmodel into "sbm" >> getparamictextSBPD(sbm) The purpose of this helper functions should now have become clear.

output = createrunestimationscriptSBPD(input)
Usage	createrunestimationscriptSBPD: Creates a run estimation script for the given project and eventually given modelindex. This script can be seen as a template for parameter estimation and fit analysis tasks. USAGE: ====== createrunestimationscriptSBPD(project) createrunestimationscriptSBPD(project,modelindex) createrunestimationscriptSBPD(project,modelindex,filename) createrunestimationscriptSBPD(project,modelindex,filename, OPTIONS) project: SBPDproject modelindex: index of the model in the project to use filename: name of the run estimation file (*.m) OPTIONS: a structure with additional informations OPTIONS.lowerbounds: scalar factor, determining the lower bound for a parameter by: factor*"original parameter value". OPTIONS.highbounds: scalar factor, determining the upper bound for a parameter by: factor*"original parameter value". DEFAULT VALUES: =============== modelindex: 1 filename: 'runEstimation.m' OPTIONS.lowbounds: 0.1 OPTIONS.highbounds: 10
Examples	Please change into the SBPD/_EXAMPLES/benchmarkprojects folder. Load a project by typing: >> sbp = SBPDproject('ex1 - Isomerization of alpha-pinene') Then create a runEstimation.m script by typing: >> createrunestimationscriptSBPD(sbp) Have a look at the created script. In lines 11 and 12 you have to enter the name of the project file to load (*.sbp) or the name of the project folder to load. In this case: ex1 - Isomerization of alpha-pinene. Then you are ready to run an estimation on this project.

output = SBPDanalyzeresiduals(input)
Usage	SBPDanalyzeresiduals: Determines and analyzes the residuals for a given project. The function either returns the residuals and corresponding analysis information or plots the results. The residuals are statistically tested with the Null Hypothesis that they are normal with unspecified mean and variance. Currently, the means are not tested agains the hypothesis that they have all the properties of white noise. Furthermore, the autocorrelations of the (mean-free) residuals are calculated. USAGE: ====== SBPDanalyzeresiduals(project) SBPDanalyzeresiduals(project,modelindex) SBPDanalyzeresiduals(project,estimation) SBPDanalyzeresiduals(project,modelindex,alpha) SBPDanalyzeresiduals(project,estimation,alpha) [output] = SBPDanalyzeresiduals(project) [output] = SBPDanalyzeresiduals(project,modelindex) [output] = SBPDanalyzeresiduals(project,estimation) [output] = SBPDanalyzeresiduals(project,modelindex,alpha) [output] = SBPDanalyzeresiduals(project,estimation,alpha) project: SBPDproject to determine the residuals for. modelindex: The index of the model in the project to use for residual determination. estimation: Same structure as used for parameter estimation (SBPDparameterestimation), defining the experiments to take into account. Additionally, if defined the timescalingFlag is taken into account. alpha: The significance level for the test of the individual residuals against the Null Hypothesis that they are normally distributed. DEFAULT VALUES: =============== modelindex: 1 estimation: all experiments and measurements are taken into account alpha = 0.05 Output Arguments: ================= If no output argument is specified, the residuals and additional analysis information is plotted using the SBplot GUI. Otherwise, the results are returned as a structure with the following fields: output(e).name: Name of the e-th experiment output(e).measurement: Results for the measurements in the e-th experiment output(e).measurement(m).name: Name of the m-th measurement in the e-th experiment output(e).measurement(m).components: Names of the measured components for which the residuals have been determined. output(e).measurement(m).time: Timevector for the measurement output(e).measurement(m).timescalingFlag: Value of the timescalingFlag used for the analysis. This flag can be defined via the estimation input argument. Hint: Keep it either on the same value as for parameter estimation or set it to zero. output(e).measurement(m).residuals: Matrix with residuals (weighted according to the timescalingFlag setting). Rows correspond to time-points and columns to the measured components (same order as in output(e).measurement(m).components). output(e).measurement(m).pValue: are the p-values corresponding to each component residual. A pvalue is the probability of observing the given result (residuals) by chance given that the null hypothesis (residuals normally distributed) is true. Small values of pValue cast doubt on the validity of the null hypothesis. output(e).measurement(m).alpha: The significance level for the test of the individual residuals against the Null Hypothesis that they are normally distributed. (Same value as input argument "alpha" or default setting). output(e).measurement(m).H: Result of the hypothesis test for each component residuals. H=0 (alpha Null Hypothesis accepted, H=1 (alpha>=pValue) => Null Hypothesis rejected. output(e).measurement(m).autocorrelation_Rxx: Normalized autocorrelations of the (mean-free) residuals. One column per residual. output(e).measurement(m).autocorrelation_lag: The lags are useful for plotting the Rxx results.
Examples	Please have a look at the run_ex1.m and run_ex2.m scripts in the SBPD/_EXAMPLES/benchmarkproblems folder.

output = SBPDparameterfitanalysis(input)
Usage	Parameter estimation for the given project is repeated several times from randomly perturbed starting conditions. The estimated parameters values are stored and can subsequently can be used to obtain insight into correlations between parameters, local minima, etc. This function only generates the data, which then is analyzed by specialized functions (SBPDfaboxplot, SBPDfaclustering, SBPDfahist). USAGE: ====== [estdata] = SBPDparameterfitanalysis(project,estimation) [estdata] = SBPDparameterfitanalysis(project,estimation, ... ...nrestimations,perttype) [estdata] = SBPDparameterfitanalysis(project,estimation, ... ...nrestimations,perttype,noStopButtonFlag) project: SBPDproject for which to do the estimation estimation: Structure that defines what to do. Same structure as used for SBPDparameterestimation, thereforw not documented here again. nrestimations: number of estimations that are to be done from varying initial conditions perttype: =0: perturbed parameters/initial conditions chosen randomly distributed uniformly between the low and high bounds. >0: perturbed parameters obtained from an exponential distribution around the nominal values: ppert=p0*10^(randn(1)*perttype) noStopButtonFlag: 0: stop button, 1: no stop button DEFAULT VALUES: =============== estimation: same as in SBPDparameterestimation nrestimations: 50 perttype: 0.5 (exponential distribution around nominal parameter values/initial conditions noStopButtonFlag: 0 Output Arguments: ================= The output 'estdata' is given as a structure: nrestimations: number of estimations performed perttype: the chosen perturbation type parameters: cell-array with names of optimized parameters Popt: vector with values of optimized parameters parameterslocal: cell-array with names of locally optimized parameters (for each experiment indenpendently) PLOCALopt: vector with values of locally optimized parameters icnames: cell-array with names of states for which the initial conditions have been optimized ICopt: vector with values of optimized initial conditions FVALopt: optimal cost function value FVALstart: the cost at the starting conditions timeelapsed: the time needed for all the estimations
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

SBPDfahist(input)
Usage	This function plots histograms for the parameter values that have been estimated using the SBPDparameterfitanalysis function. This gives a first impression over how well the parameters can be determined. The bins are equally distributed over the parameter range given by the upper and lower bounds. Results are displayed separately for global parameters, local parameters, and initial conditions. For each estimated local parameter and initial condition a new figure is displayed, since usually there will be several experiments. USAGE: ====== SBPDfahist(estdata) SBPDfahist(estdata,nrbins) estdata: The estimation data returned by the function SBPDparameterfitanalysis nrbins: Number of bins to sort the values into
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

SBPDfaclustering(input)
Usage	This function performs hierarchical clustering based on Euclidean distance of the estimated parameter sets. If the estimates are grouped around a single minimum a single cluster tree should be seen. However, if the parameter sets lie around different local minima the tree will show several large branches. To normalize the data, the parameters are scaled such that the median of each single parameter is 1. USAGE: ====== SBPDfaclustering(estdata) SBPDfaclustering(estdata,fontsize) estdata: The estimation data returned by the function SBPDparameterfitanalysis fontsize: Fontsize for the dendrogram (default: 10)
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

SBPDfaboxplot(input)
Usage	Plots a box-and-whisker diagram for the estimation data, visualizing the spread in the results. Separate plots are shown for global and local parameters and initial conditions. Determine also mean and standard deviation for all parameters and display them next to the names. To normalize the data, the parameters are scaled such that the median of each single parameter is 1. USAGE: ====== SBPDfaboxplot(estdata) SBPDfaboxplot(estdata, OPTIONS) estdata: The estimation data returned by the function SBPDparameterfitanalysis OPTIONS: Structure containing options for the function OPTIONS.boxWidth: Width of the boxes to be drawn OPTIONS.verticalFlag: Flag determining if the boxes are oriented vertically (=1) or horizontally (=0) DEFAULT VALUES: =============== OPTIONS.boxWidth: 0.5 OPTIONS.verticalFlag: 0 (plot horizontally)
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

SBPDfacorr(input)
Usage	This function determines the correlation matrix for the parameter sets determined with the SBPDparameterfitanalysis function. The closer the magnitude of the values is to one, the more correlated the parameters. Results are generated only for the global parameters. USAGE: ====== SBPDfacorr(estdata) estdata: The estimation data returned by the function SBPDparameterfitanalysis
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

SBPDfasigncorr(input)
Usage	A matrix of p-values for testing the hypothesis of no significant correlation is computed based on the results generated by SBPDparameterfitanalysis and displayed. Each p-value is the probability of getting a correlation as large as the observed value by random chance, when the true correlation is zero. If P(i,j) is small then the correlation between these two parameters is significant. Results are generated only for the global parameters. USAGE: ====== SBPDfasigncorr(estdata) SBPDfasigncorr(estdata,alpha) estdata: The estimation data returned by the function SBPDparameterfitanalysis alpha: A number between 0 and 1 to specify a confidence level of 100*(1-alpha)%. Default: alpha=0.05
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

SBPDfadetcorr(input)
Usage	Plots detailed pairwise correlations between parameters. Parameters to display on the X and Y axis should be selected. USAGE: ====== [project] = SBPDfadetcorr(estdata) estdata: The estimation data returned by the function SBPDparameterfitanalysis
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

output = cutoffdataSBPD(input)
Usage	Function used to select a cut-off threshold for the estimation data collected during the fit analysis. Threshold can only be increased, since the cut-off data are thrown away. USAGE: ====== [estdataout] = cutoffdataSBPD(estdata) estdata: The estimation data returned by the function SBPDparameterfitanalysis Output Arguments: ================= estdataout: estdata structure (see SBPDparameterfitanalysis)
Examples	Please have a look at the runAnalysis.m script in the SBPD/_EXAMPLES/FitAnalysis folder.

Symbolic Math Functions (Require the Symbolic Toolbox)

output = SBPDsymjacobian(input)
Usage	Determines a symbolic Jacobian. This function requires the symbolic toolbox for MATLAB. input = [model] input = [model, simpleflag] model: SBmodel simpleflag: =0 => do not try to simplify (default), =1 => try to simplify (slower). output = [jacobian] jacobian: Cell-matrix containing the symbolic Jacobian.
Examples	This function should be self explaining and does not need any example.

Kinetic Rate Laws

Inbuild Kinetic Rate Laws
Usage	Some standard kinetic rate laws are built in the SBPD package and can be used in SBmodels. Here only the names of the kinetic rate law functions are shown. To obtain more documentation about these rate laws please type >> help "ratelawname" in MATLAB. kin_allosteric_inihib_empirical_rev kin_allosteric_inihib_mwc_irr kin_catalytic_activation_irr kin_catalytic_activation_rev kin_comp_inihib_irr kin_comp_inihib_rev kin_constantflux kin_degradation kin_hill_1_modifier_rev kin_hill_2_modifiers_rev kin_hill_cooperativity_irr kin_hill_rev kin_hyperbolic_modifier_irr kin_hyperbolic_modifier_rev kin_iso_uni_uni_rev kin_mass_action_irr kin_mass_action_rev kin_michaelis_menten_irr kin_michaelis_menten_rev kin_mixed_activation_irr kin_mixed_activation_rev kin_mixed_inihib_irr kin_mixed_inihib_rev kin_noncomp_inihib_irr kin_noncomp_inihib_rev kin_ordered_bi_bi_rev kin_ordered_bi_uni_rev kin_ordered_uni_bi_rev kin_ping_pong_bi_bi_rev kin_specific_activation_irr kin_specific_activation_rev kin_substrate_activation_irr kin_substrate_inihib_irr kin_substrate_inihib_rev kin_uncomp_inihib_irr kin_uncomp_inihib_rev kin_uni_uni_rev
Examples	Please have also a look at the models that are present in the project folder in the SBPD/_EXAMPLES/Projects folder. These models make extensive use of the above functions.

Parameter Estimation Benchmark Projects

Usage

The SBPD package includes several SBPDprojects that can be used as benchmarks for the evaluation of parameter estimation methods. These projects are located in the SBPD/_EXAMPLES/benchmarkproblems folder and can be run using the following scripts: run_ex1 - Isomerization of alpha-pinene run_ex2 - Irreversible inhibition of HIV proteinase run_ex3 - Three-step biochemical pathway To execute these scripts, please change into the SBPD/_EXAMPLES/benchmarkproblems folder, open the desired script and run it step by step. (Here the Cell-mode of the MATLAB editor is very useful!).

Start Doc SBTOOLBOX2 Doc SBPD Overview User's Reference Benchmark Doc SBPOP Download Installation Tutorial License Information Contact

SBPOP PUBLICATIONS Publications, discussing results obtained with the help of the SBPOP PACKAGE, are asked to reference the most relevant of the following papers and additionally the link to this webpage: Systems Biology Toolbox for MATLAB: A computational platform for research in Systems Biology, Bioinformatics, 22(4), 514-515, 2006, doi:10.1093/bioinformatics/bti799 SBaddon: high performance simulation for the Systems Biology Toolbox for MATLAB, Bioinformatics, 23(5), 646-647, 2007, doi:10.1093/bioinformatics/btl668 SBPOP Package: Efficient support for model based drug development – from mechanistic models to complex trial simulation, PAGE meeting, Glasgow, UK [abstract] Enhancing population pharmacokinetic modeling efficiency and quality using an integrated workflow, Journal of Pharmacokinetics and Pharmacodynamics, doi:10.1007/s10928-014-9370-4, 2014.

SBPOP NEWS 16th March 2015: Many small improvements ... also SBML export now fully working again 20th January 2015: Many improvements ... Windows 64bit support and compatibility with MATLAB versions >=R2014B 28th July 2014: Happy to announce that our paper about efficient conduct of popPK anlalyses has been published (doi:10.1007/s10928-014-9370-4) 3rd July 2014: Update to Revision 1361 (due to packaging bug in Rev 1352) 18th June 2014: Update to Revision 1352 (popPK modeling workflow MONOLIX and NONMEM, "median" modeling support) 25th March 2014: Update to Revision 1278 7th May 2013: Revision 1172 had a minor bug due to packaging of the public version - main impact on running SBPDgui. Fixed now in Revision 1176 2nd May 2013: SBTOOLBOX2 and SBPD are now integrated into the same package, called "SBPOP PACKAGE". The new combined package additionally includes "SBPOP", focusing on PK/PKPD/PBPK models, population modeling, nonlinear mixed effect parameter estimation, clinical trial simulation