User's Reference (SBTOOLBOX2)
Most up-to-date information
|
Model Representation - Overview
| Model Syntax | Models are described using an intuitive, user-friendly and powerful text based syntax, allowing the definition of ordinary differential equations, chemical reaction equations, etc. Additionally it is possible to define differential equations, initial conditions, variables, and reactions using a vectorized syntax. Learn more here! |
|---|---|
| Model Representation | Models are represented in 2 different ways in the toolbox, leaving the user considerable freedom and ensuring easy reuse of already available MATLAB models. This section explains the internal storage format of SBmodels. |
Experiment Representation - Overview
| Experiment Syntax | Insilico experiments are described using an intuitive, user-friendly and quite powerful text based syntax. Learn more here! |
|---|---|
| Experiment Representation | The toolbox allows the representation of experiments and the merging with models. This section explains the internal storage format of SBexperiments. |
Measurement Representation - Overview
| Measurement Syntax | The toolbox can handle measurement data, stored in comma-separated-value (CSV) and Excel (XLS) files. In both cases a certain syntax of the data in these files is required. Learn more here! |
|---|---|
| Measurement Representation | The toolbox allows handling and use of measurement data. This section explains the internal storage format of SBmeasurements. |
Functions - Overview
| Installation of Toolbox | |
|---|---|
| installSB | Installation script for the toolbox. |
| helpSB | SBTOOLBOX2 help function (requires internet connection). |
| Model Creation and Handling | |
| SBmodel | Creating a new SBmodel. |
| SBcreateTEXTmodel | Creates new SBmodel TEXT file and opens it in editor. |
| SBcreateTEXTBCmodel | Creates new SBmodel TEXTBC file and opens it in editor. |
| SBstruct | Returns the internal data structure of an SBmodel as a MATLAB structure. |
| SBedit | Graphical user interface, allowing to edit and simulate SBmodels. Allows also to export SBmodels to ODE files, SBmodel files, SBML models. |
| SBeditBC | Graphical user interface for editing SBmodels in a more biochemically oriented presentation. |
| isSBmodel | Checks if the given argument is an SBmodel. |
| cleanmodelSB | Remove unused reactions, variables and parameters from an SBmodel. |
| SBstates | Returns information about states in an SBmodel (statenames, a cell-array with names of states in model. |
| SBinitialconditions | Sets or returns a models initial conditions. |
| SBalgebraic | Returns information about algebraic rules in the model. |
| SBparameters | Returns parameter names and values in an SBmodel or ODE file model. It is also possible to change parameter values. |
| SBvariables | Returns information about variables in an SBmodel (variable names and formulas, but also the variable values for given state). |
| SBreactions | Returns information about reactions in an SBmodel (reaction names and formulas of kinetic laws, but also the reaction rates for given state). |
| SBfunctions | Returns information about functions in an SBmodel (functions names, arguments, and formulas). |
| SBevents | Returns information about events in an SBmodel (names, triggers, assignment variables, and assignment formulas). |
| SBfunctionsMATLAB | Returns information about MATLAB functions in an SBmodel. |
| isparameterSB | Checks if a given "name" is a parameter in given model. |
| isstateSB | Checks if a given "name" is a state in given model. |
| isvariableSB | Checks if a given "name" is a variable in given model. |
| isreactionSB | Checks if a given "name" is a reaction in given model. |
| stateindexSB | Returns the index of the given state in given model. |
| variableindexSB | Returns the index of the given variable in given model. |
| reactionindexSB | Returns the index of the given reaction in given model. |
| usedelaySB | Checks if the given model uses delay functions. |
| useeventSB | Checks if the given model uses events. |
| usealgebraicSB | Checks if the given model contains algebraic rules. |
| usefastSB | Checks if the given model contains fast reactions. |
| hasmoietyconservationsSB | Checks if the given model contains moiety conservations. |
| Experiment Creation and Handling | |
| SBexperiment | Creating a new SBexperiment object. |
| SBstruct | Returns the internal data structure of an SBexperiment object as a MATLAB structure. |
| SBcreateEXPfile | Exports an SBexperiment object to a text file description. |
| SBmergemodexp | Merges a model with an experiment description. |
| isSBexperiment | Checks if the given argument is an SBexperiment. |
| Measurement Creation and Handling | |
| SBmeasurement | Creating a measurement data object SBmeasurement. |
| SBstruct | Returns the internal data structure of an SBmeasurement object as a MATLAB structure. |
| SBmeasurementdata | Allows to extract information about the measurement data stored in an SBmeasurement object. |
| SBexportCSVmeasurement | Exporting an SBmeasurement object to a CSV (comma separated values) file. |
| SBexportXLSmeasurement | Exporting an SBmeasurement object to an Excel file. |
| SBexportXLSmeasurements | Exporting several SBmeasurement objects to the same Excel file. |
| SBvisualizemeasurement | Visualizing data in an SBmeasurement object graphically. |
| isSBmeasurement | Checks if the given argument is an SBmeasurement object. |
| Export of SBmodel | |
| SBcreateODEfile | Converting an SBmodel to a MATLAB ODE file. |
| SBcreateTempODEfile | Same as SBcreateODEfile but ODE file is created in the systems temporary directory. |
| deleteTempODEfileSB | Deletes the ODE file created in the systems temporary directory. |
| SBcreateTEXTfile | Converting an SBmodel to a ODE text file description. |
| SBcreateTEXTBCfile | Converting an SBmodel to a biochemically oriented text file description. |
| SBexportSBML | Exports an SBmodel to an SBML model. |
| SBconvert2MA | Takes an SBmodel and if possible returns the stoichiometric matrix, the numeric kinetic parameters, and the initial conditions. |
| Simulation Functions | |
| SBsimulate | Simulates an SBmodel or a ODE file model. Intergators, starting conditions, and other options can be chosen. |
| SBstochsim | Stochastic simulation of SBmodels. |
| Plotting Functions | |
| SBplot | (GUI) Plots time-series data. |
| SBplot2 | (GUI) Plots different kind of data where a block diagram representation is useful. So far mainly used for displaying results from parameter sensitivity analysis. |
| createdatastructSBplotSB | Generates a datastructure based on user defined inputes that can be plotted using SBplot. |
| createdatastruct2SBplotSB | Generates a datastructure based on simulation results returned from SBsimulate or SBPDsimulate to be plotted by SBplot. |
| Simple Analysis Functions | |
| SBsteadystate | Determines the steady-state of an SBmodel or ODE file model, dealing also with singular systems |
| SBjacobian | Determines the Jacobian of a system at a given state by numerical differentiation. |
| SBmoietyconservations | Determines the moitey and/or other conservations that are present in a model. |
| SBreducemodel | Allows to reduce a singular model to a non-singular by deleting algebraic realtions from the ODEs, and replacing them by variables. |
| SBstoichiometry | Determines the stoichiometric matrix for the given model. |
| SBreactantstoichiometry | Determines the stoichiometric coefficients for the reactants only. |
| SBmakeirreversible | Converts the reversible reactions of an SBmodel into irreversible ones. |
| Local Parameter Sensitivity Analysis Functions | |
| SBsensdataosc | Generating data for the parameter sensitivity analysis of oscillating systems. |
| SBsensdataoscevents | Generating data for the parameter sensitivity analysis of oscillating systems when events are present in the model. |
| SBsensamplitude | Parameter sensitivity analysis of the oscillation amplitude. Uses data generated by SBsensdataosc. |
| SBsensperiod | Parameter sensitivity analysis of the oscillation period. Uses data generated by SBsensdataosc. |
| SBsensdatastat | Generating data for the parameter sensitivity analysis of the steady-state of systems. |
| SBsensstat | Parameter sensitivity analysis of the steady-state values of states, variables, and reaction rates (can be seen as a generalized MCA). |
| SBmca | Metabolic control analysis (MCA). |
| Global Parameter Sensitivity Analysis Functions | |
| SBsensglobalfast | Extended FAST. |
| SBsensglobalprcc | PRCC (Partial Rank Correlation Coefficient). |
| SBsensglobalsobol | Sobols method. |
| SBsensglobalwals | WALS (weighted average of local sensitivities). |
| Localization of Mechanisms leading to Complex Behaviors | |
| SBlocbehavcomp | Determines the importance of components in the given biochemical system in the creation of an observed complex behavior. |
| SBlocbehavinteract | Determines the importance of interactions between components in the given biochemical system in the creation of an observed complex behavior. |
| SBlocbehavinteract2 | Same as SBlocbehavinteract but no checking of stability is done. |
| Model Reduction Functions (Require the Symbolic Toolbox) | |
| SBredallreac | Wrapper function that allows the reduction of all reaction rate expressions in a given model. |
| SBprepredreac | This function needs to be called prior to calling the SBredreac function in order to prepare the model and generate reference data. |
| SBredreac | Function that allows the reduction of the kinetic expression of a single rate expression. |
| Optimization | |
| simplexSB | Local optimization algorithm (Nelder-Mead) (constrained). |
| simannealingSB | Global optimization algorithm (constrained). |
| isresSB | Global optimization algorithm (constrained). |
| SSmSB | Global optimization algorithm for MINLP's based on Scatter Search (constrained). |
| fSSmSB | Global optimization algorithm for MINLP's based on Scatter Search ("fast" Version) (constrained). |
| pswarmSB | Particle swarm pattern search algorithm for global optimization (constrained). |
| Solvers | |
| fsolveSB | Solver for nonlinear equations based on Newton iterations. |
| Statistics | |
| princompSB | Compute principal components of a data matrix. |
| clusteringSB | Performs UPGMA on distance matrix and produces a dendrogram plot. |
| pdistSB | Determines the distance matrix for a set of points whose coordinates are given as row-vectors in the data matrix. |
| prctileSB | Determines the percentiles of a sample, based on interpolation. |
| boxplotSB | Plots a box-and-whisker diagram for the given data. |
| chi2cdfSB | Cumulative density function of the chi-square distribution |
| chi2invSB | Quantile function of the chi-square distribution |
| chi2pdfSB | Probability density function of the chi-square distribution |
| tcdfSB | Cumulative density function of the t distribution |
| tinvSB | Quantile function of the t distribution |
| tpdfSB | Probability density function of the t distribution |
| gamcdfSB | Cumulative density function of the gamma distribution |
| gaminvSB | Quantile function of the gamma distribution |
| gampdfSB | Probability density function of the gamma distribution |
| normcdfSB | Cumulative densitiy function of the normal distribution |
| norminvSB | Quantile function of the normal distribution |
| normpdfSB | Probability density function of the normal distribution |
| swtestSB | Shapiro-Wilk parametric hypothesis test of composite normality |
| Signal | |
| xcorrSB | Compute correlation R_xy of X and Y for various lags k. |
| resampleSB | resamples time series x1, which is sampled at the time instances t1 to time series x2 using a sampling defined by t2. |
| postpadSB | Extends a vector or matrix in the given dimension with given values to a given length by appending the values. |
| prepadSB | Extends a vector or matrix in the given dimension with given values to a given length by adding the values at the beginning. |
| centeredfftSB | Uses the fft function of MATLAB to determine a two sided spectrum of a data vector. |
| positivefftSB | Uses the fft function of MATLAB to determine a one sided spectrum of a data vector. |
| String handling functions (auxiliary functions) | |
| explodePCSB | Allows to decompose a string expression into separated elements. The separation character can be specified. Commas within parentheses expressions are not considered. |
| extractPSB | This function looks for the top level parentheses in the given text string and returns the substring that is located between these parentheses. |
| Special functions that can be used in models (auxiliary functions) | |
| andSB | Logical and. |
| orSB | Logical or. |
| piecewiseSB | Implementation of the SBML/MathML piecewise operator. |
| interp0SB | Lookup table for zero-order interpolation. |
| interp1SB | Lookup table for linear interpolation. |
| interpcsSB | Lookup table for cubic spline interpolation. |
| delaySB | Function that realizes delays. |
Model/Experiment/Measurement Syntax - Full Description
The syntax of models, experiments, and measurements, as it is used by the SBTOOLBOX2, is best described by well documented examples.
For this purpose there are plenty of examples included in the toolbox. Below you will find to almost each function description an executable
example. Additionally there is an introductory tutorial available that can be found here:
Model Representation - Full Description
The toolbox's model representation uses two different levels of describing a model. On the high-level, an SBmodel is realized as a
MATLAB object with a certain internal data structure, described in the table below. This allows the user and the analysis tools a large freedom in manipluating the
model prior to, and during, analysis. All functions, as far as meaningful, should be able to work with a model given as an SBmodel.
Order of Computation
An SBmodel has states and corresponding ODEs, parameters, variables, reactions, functions, events, and MATLAB functions. Furthermore, it allows to specify algebraic rules and fast reactions. The dependencies between these elements are the following:- Parameters are constant values and do not depend on other elements
- Variables depend only on states (dynamic or algebraic), parameters, and previously defined variables
- Reactions depend on states (dynamic or algebraic), parameters, and variables
- ODEs depend on states (dynamic or algebraic), parameters, variables, and reactions
- Functions can have arguments that have been previously dertermined and be used for the definition of variables, reactions, and ODEs
- Events are used to realize discrete state changes when a given condition is fulfilled. Please read the help text that appears when opening a model using the SBedit function for getting more information about events.
- MATLAB functions can be used similarly to functions. The difference is that you have total freedom of what to put into these functions. For example they can be used to implement a unitstep function to change a certain parameter or variable at a certain time, etc.
| name | Name of the model (string) |
| notes | Notes about the model (string) |
| functions.name | Name of a function in the model (string) |
| functions.arguments | Comma separated list of argument for the function (string) |
| functions.formula | Formula representing the function (string) |
| functions.notes | Notes about the function (string) |
| states.name | Name of a state in the model (string) |
| states.initialCondition | Initial value of a state (numerical) |
| states.ODE | ODE expression determining the time derivative for the state (string) |
| states.type | Additional information about the type of the state, needed for the export to SBML and eventually for the biochemical oriented representation. (string) |
| states.compartment | Additional information for SBML export, etc. Not used if the state does not represent a species or a compartment. (string) |
| states.unittype | Additional information for SBML export, etc. In case the state represents a species the unittype can be "concentration" or "amount". (string) |
| states.notes | Notes about the state (string) |
| algebraic.name | Name of a defined by an algebraic rule in the model (string) |
| algebraic.initialCondition | Initial value of this state (numerical) |
| algebraic.formula | mathematical expression defining the algebraic rule (string) |
| algebraic.type | Additional information about the type of the algebraic state, needed for the export to SBML. (string) |
| algebraic.compartment | Additional information for SBML export, etc. Not used if the algebraic state does not represent a species or a compartment. (string) |
| algebraic.unittype | Additional information for SBML export, etc. In case the algebraic state represents a species the unittype can be "concentration" or "amount". (string) |
| algebraic.notes | Notes about the algebraic state (string) |
| parameters.name | Name of a parameter (string) |
| parameters.value | Value of a parameter (numerical) |
| parameters.type | Additional information about the type of the parameter, needed for the export to SBML and eventually for the biochemical oriented representation. (string) |
| parameters.compartment | Additional information for SBML export, etc. Not used if the state does not represent a species or a compartment. (string) |
| parameters.unittype | Additional information for SBML export, etc. In case the state represents a species the unittype can be "concentration" or "amount". (string) |
| parameters.notes | Notes about a parameter |
| variables.name | Name of a variable (string) |
| variables.formula | Formula defining a variable (string) |
| variables.type | Additional information about the type of the variable, needed for the export to SBML and eventually for the biochemical oriented representation. (string) |
| variables.compartment | Additional information for SBML export, etc. Not used if the state does not represent a species or a compartment. (string) |
| variables.unittype | Additional information for SBML export, etc. In case the state represents a species the unittype can be "concentration" or "amount". (string) |
| variables.notes | Notes about a variable (string) |
| reactions.name | Name of a reaction (string) |
| reactions.formula | Formula defining the rate law of a reaction (string) |
| reactions.notes | Notes about a reaction (string) |
| reactions.reversible | Flag to indicate (ir)reversibility of a reaction (0=irreversible, 1=reversible) |
| reactions.fast | Flag to indicate if this reaction is fast or not (0=not fast (default), 1=fast) |
| events.name | Name of an event (string) |
| events.trigger | Trigger expression for an event (string) |
| events.notes | Notes about an event (string) |
| events.assignment.variable | Name of state variable that is affected (string) |
| events.assignment.formula | Assignment formula for affected state (string) |
| functionsMATLAB | String containing the definition of functions in MATLAB syntax (string) |
The second model representation is that of an ODE function. An SBmodel can be converted to an ODE function by using the function SBcreateODEfile. If possible and reasonable, functions should also be able to work with a model given as an ODE function, however, this will not always be possible. The ODE function description used by this toolbox is compatible with the standard MATLAB ODE function description. However, this is not true in the other direction. Users wanting to use the toolbox with MATLAB models they already have developed as standard MATLAB ODE functions need to do change their models slightly, as described below.
In the case of events being present in the model the SBcreateODEfile can be used to also generate extra files that are needed to handle these events when simulating the model. If this is needed the functions of the toolbox will do this automatically. If these additional files are not needed for some analysis and events are present in the model a warning message will appear that the events are neglected.
Reuse of already available MATLAB models
The standard MATLAB ODE function description has the following syntax: [xdot] = matlabODEfunction(time,x). Here time is the time instant at which the function is evaluated, x is the state vector at time time and xdot is a column vector with the time derivatives of the states, which are calculated by the MATLAB ODE function.The differences between the standard MATLAB ODE function and the ODE function, used in this toolbox, are the following alternative ways of calling the ODE function:
[initialConditions] = ODEfunction();
Calling the ODE function without arguments returns a vector containing initial conditions for the states. IMPORTANT: If the model contains algebraic rules, the initial conditions of the algebraic states are added to the result vector. If you only want to get the initial conditions of the ODEs you need to remove the number of elements from the end of this vector that corresponds to the number of algebraic rules in the model.
[stateNames] = ODEfunction('states');
Calling the ODE function in this way returns a MATLAB cell-array with the names of the states involved in the model. An example for a cell-array is: exampleCellArray = {'state1','state2','state3'}.
[algebraicNames] = ODEfunction('algebraic');
Returns the names of the algebraic states in a cell-array.
[parameterNames] = ODEfunction('parameters');
This returns a MATLAB cell-array with the names of the parameters, contained in the model.
[parameterValues] = ODEfunction('parametervalues');
This returns a column vector with the parameter values used in the model.
[xdot] = ODEfunction(time,x);
Returning the time derivative of the states at time time and state x. IMPORTANT: In the case that algebraic rules are present in the model the last n (where n is the number of algebraic rules in the model) elements in the return vector correspond to the evaluated algebraic rules.
In the following the terms ODE function and ODE file (and maybe some other terms) are describing the same thing.
Experiment Representation - Full Description
The idea behind the experiment description functionality is to be able to separate models from experiments. Previously
the mathematics of in silico experiments had to be added to the models equations, eventually resulting in many different model
instances to keep track off.
Using the experiment description only a nominal model (SBmodel) needs to be present. It can then be merged with different experiment descriptions, resulting in an updated SBmodel that can then be used to simulated the in silico experiment.
The separation of in silico experiment descriptions and in silico models matches very nicely to the wet lab experiments, in which the nominal system (e.g., a wild type yeast cell) is an entity and clearly separated physically from the experiments that are performed with it.
Experiments are represented in this toolbox by an SBexperiment object, that can be created using the SBexperiment function. The format for the experiment description is text based and in the structure similar to the SBmodel textual description.
Features of the experiment description:
- Setting of the state variables initial conditions (not only as numeric values but also as functions of other values within the model).
- Setting of fixed parameter values (not only as numeric values but also as functions of other values within the model).
- Implementation of parameter changes using piecewiseSB expressions or other algebraic expressions for parameters.
- Implementation of state events (so far only at given time points).
The internal data structure of an SBexperiment object has the following fields:
| name | Name of the experiment (string) |
| notes | Notes about the experiment (string) |
| paramicsettings.name | Name of the state (parameter) for which the initial condition (value) is changed (string) |
| paramicsettings.formula | Formula for the determination of the initial condition or parameter value (string) |
| paramicsettings.notes | Notes about this setting (string) |
| paramicsettings.icflag | =0: Parameter setting, =1: Initial condition setting (string) |
| parameterchanges.name | Name of the parameter for which the value is to be determined by an algebraic expression (string) |
| parameterchanges.formula | Formula for the determination of the parameter value (evaluated during the merged models execution) (string) |
| parameterchanges.notes | Notes about this parameter (string) |
| stateevents.name | Name of the state event (string) |
| stateevents.trigger | Trigger for the state event (string) |
| stateevents.assignment | Structure defining the assignments (same structure as in the SBmodel description) |
| stateevents.notes | Notes about the event (string) |
Textual experiment descriptions can be imported to MATLAB using the SBexperiment function. Export of an SBexp object to the textual description is possible using the SBcreateEXPfile function. For an example please have a look in the SBTOOLBOX2/_EXAMPLES/experiment folder.
Measurement Representation - Full Description
Measurement data are represented in this toolbox by an SBmeasurement object, that can be created using the SBmeasurement function.
Measurement data can be in-silico generated data and data obtained through real measurements.
The internal data structure of an SBmeasurement object has the following fields:
| name | Name of the measurement data (string) |
| notes | Notes about the measurement data (string) |
| time | Time vector of sampling instants |
| data.name | Name of the measured component (string) |
| data.notes | Notes about the measured component (string) |
| data.values | Measured values (column vector of the same length as time). If no measurement has been made for the corresponding time instant the value should be set to NaN. |
| data.maxvalues | Upper errorbound of measured values (column vector of the same length as time). If no measurement has been made for the corresponding time instant the value should be set to NaN. If no error bound is available this field contains a vector with only NaN entries. |
| data.minvalues | Lower errorbound of measured values (column vector of the same length as time). If no measurement has been made for the corresponding time instant the value should be set to NaN. If no error bound is available this field contains a vector with only NaN entries. |
The data structure can contain measurements from different components. The time vector is global and contains all time instants at which measurements have been collected. In case that a certain component is not measured at a certain time instant, its value is to be set to NaN (not a number) to indicate this. In this way the number of measurements can be different for different components.
Measurement data can be imported from Excel and CSV (comma separated value) files, using the function SBmeasurement. Export to the same kind of files is possible using the functions SBexportXLSmeasurement, SBexportXLSmeasurements, and SBexportCSVmeasurement. For information on the required format of the Excel and CSV files please look at the example files MeasurementExample.xls, MeasurementExample.csv in the SBTOOLBOX2/_EXAMPLES folder.
Functions - Full Description and Examples
Installation of Toolbox
| installSB | |
|---|---|
| Usage |
Installation function for the SBTOOLBOX2.
Prior to running it you should edit its contents to match your
system. Standard calling syntax:
>> installSB
This function can be called with the optional syntax:
>> installSB('quick')
This adds the SBTOOLBOX2 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 installSB without the
optional argument. Use this the first time when installing a
new version of the toolbox.
|
| Examples |
>> installSB
Installs the toolbox, by compiling all needed libraries and functions and setting paths |
| helpSB | |
|---|---|
| Usage |
helpSB: SBTOOLBOX2 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:
======
helpSB
helpSB 'SBT2 functionname'
EXAMPLES:
=========
helpSB
helpSB SBsimulate
|
Model Creation and Handling
| output = SBmodel(input) | |
|---|---|
| Usage |
This function creates an SBmodel.
input=[] Invoking SBmodel without arguments returns an empty SBmodel. Otherwise SBmodels can be created from a data structure that corresponds to the internal model data structure, described by SBstruct, from a previously defined SBmodel sbm, from an SBML model file SBMLmodelfilename (the extension '.xml' does not need to be specified), and from Textmodelfilename, a text file description of the model. In the latter case the extension '.txt' needs to be specified. The text file description of a model follows the syntax used and defined in SBedit. The output consists of an SBmodel sbm. |
| Examples |
Two example SBML models are provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type: >> sbm = SBmodel('SBMLexampleLevel1'); This creates an SBmodel from an SBML model file. Note that to be able to import SBML models you need to have installed the SBMLToolbox (see the Installation Guide).
|
| SBcreateTEXTmodel(input) | |
|---|---|
| Usage |
SBcreateTEXTmodel: Creates a new TEXT model, saves the corresponding
file in the current directory and opens it in the editor, if opening
is desired.
USAGE:
======
SBcreateTEXTmodel(name)
SBcreateTEXTmodel(name,openFlag)
name: filename of the model and model name
openFlag: decides if the created model is automatically opened
in the editor or not. (=0: do not open, =1: do open)
DEFAULT VALUES:
===============
openFlag: 1 (do open)
|
| Examples |
To create a new TEXT SBmodel with the name newmodel, please enter the following command: >> SBcreateTEXTmodel('newmodel') The model is created, saved to the file newmodel.txt, which is subsequently opened in the editor. |
| SBcreateTEXTBCmodel(input) | |
|---|---|
| Usage |
SBcreateTEXTBCmodel: Creates a new TEXTBC model, saves the
corresponding file in the current directory and opens it in
the editor, if opening is desired.
USAGE:
======
SBcreateTEXTBCmodel(name)
SBcreateTEXTBCmodel(name,openFlag)
name: filename of the model and model name
openFlag: decides if the created model is automatically
opened in the editor or not. (=0: do not open,
=1: do open)
DEFAULT VALUES:
===============
openFlag: 1 (do open)
|
| Examples |
To create a new TEXTBC SBmodel with the name newmodel, please enter the following command: >> SBcreateTEXTmodel('newmodel') The model is created, saved to the file newmodel.txtbc, which is subsequently opened in the editor. |
| output = SBstruct(input) | |
|---|---|
| Usage |
This function returns the internal data structure of an SBmodel. input=[sbm] sbm is the SBmodel for which to return the data structure. output=[SBstructure] The output consists of the internal data structure of sbm, defined above. Note that instead of SBstruct also the MATLAB struct command can be used, resulting in exactly the same output. |
| Examples |
First run the example from SBmodel above. Then type: >> SBstructure = SBstruct(sbm) This returns the internal data structure of the SBmodel. |
| output = SBedit(input) | |
|---|---|
| Usage |
This function realizes a graphical user interface that mainly allows to edit an SBmodel using a representation
in terms of ODEs, variables, and parameters. The model
can directly be simulated, the steady-state can be computed, and the model can be exported to an
SBML model and a text file description of the model. The use of SBedit is hopefully
self-explanatory due to the help text in each view. For additional information on optional information
please type >> help SBedit in MATLAB.
input=[sbm] sbm: An SBmodel
output = [] If no output argument is given, nothing is returned. If an output argument is given, SBedit returns the edited SBmodel.
|
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder and type: >> sbm = SBmodel('SBMLexampleLevel1.xml') This converts the SBML model to an SBmodel. Type the following: >> SBedit(sbm) You should just click you around and read the appearing help texts in the top of the window. The window can be resized to desired size. |
| output = SBeditBC(input) | |
|---|---|
| Usage |
This function realizes a graphical user interface that mainly allows to edit an SBmodel in terms of
a biochemical representation of the reaction equations. The use of parameters, variables, and all other
features of the SBmodel is possible. The model can directly be simulated, the steady-state can be
computed, and the model can be exported to an SBML model and a text file description of the model.
The use of SBeditBC is hopefully self-explanatory due to the help text in each view.
For additional information on optional information please type >> help SBeditBC in MATLAB.
input=[sbm] sbm: An SBmodel
output = [] If no output argument is given, nothing is returned. If an output argument is given, SBeditBC returns the edited SBmodel.
|
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder and type: >> sbm = SBmodel('bcmodel.txtbc') This converts the biochemically oriented text description of a model into an SBmodel. Type the following: >> SBeditBC(sbm) You should just click you around and read the appearing help texts in the top of the window. The window can be resized to desired size. Now type: >> SBedit(sbm) The biochemically oriented representation and the ODE representation are to 100% interchangeable. Please type >> help SBeditBC and >> help SBedit to find out more. |
| output = isSBmodel(input) | |
|---|---|
| Usage | This function has a single input argument and simply checks if the input argument is an SBmodel. If it is an SBmodel 1 is returned. Otherwise 0. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = cleanmodelSB(input) | |
|---|---|
| Usage |
This function removes unused reactions, variables and parameters from the given SBmodel and returns a "cleaned" SBmodel.
input=[sbm] sbm: An SBmodel to be cleaned
output = [sbmcleaned] |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = SBstates(input) | |
|---|---|
| Usage |
This function returns information about the states in the model. input=[model] model: SBmodel or name of ODE file model output=[names,ODEs,initialConditions]
names: cell-arry containing the names of the states |
| Examples |
First run the example from SBmodel above. Then type: >> [names,ODEs,initialConditions] = SBstates(sbm) and >> names = SBstates(sbm)
|
| output = SBinitialconditions(input) | |
|---|---|
| Usage |
This function returns a column vector with the values of the
states in the SBmodel as elements. (The values are the initial conditions
stored in the model). The function can also be used to set initial
conditions of the model (only if applied to an SBmodel).
[sbm] = SBinitialconditions(sbm,values) This function call returns an SBmodel sbm which corresponds to the SBmodel sbm with initial conditions for the states as given by values. [values] = SBinitialconditions(model) This function call returns the initial conditions for the states set within the model, which is either an SBmodel or a string with the name of an ODE file model.
|
| Examples |
First run the example from SBmodel above. Then type: >> SBinitialconditions(sbm) This returns the initial conditions of the model as stored in sbm. >> sbm_new = SBinitialconditions(sbm,[1 1 1]) This creates a new SBmodel sbm_new which is the same as sbm, except that it has the specified initial conditions.
|
| output = SBalgebraic(input) | |
|---|---|
| Usage |
SBalgebraic: Returns information about the algebraic equations
in a model.
USAGE:
======
[names,formulas] = SBalgebraic(model)
model: SBmodel or m-file ODE description of model
Output Arguments:
=================
names: Cell-array with names of the variables that are
determined using algebraic equations.
formulas: Cell-array with right hand side formula for
the algebraic rules.
|
| Examples |
An example model containing algebraic rules is present in the folder:
SBTOOLBOX2/_EXAMPLES/special. Please change into this folder and have a look at
the runExamples.m function that will display and simulate the models.
To run the SBalgebraic function you just type:
>> model = SBmodel('example_algebraic_rule.txt') |
| output = SBparameters(input) | |
|---|---|
| Usage |
This function returns information about the parameters in the model.
input=[model]
model: SBmodel or name of ODE file model (changing parameters is only possible for an SBmodel)
output=[names,values] (in case of a single input argument)
names: cell-arry containing the names of the parameters |
| Examples |
Load the Novak-Tyson cell cycle model by typing: >> novak_tyson Then get information about the parameters in the model by typing: >> [names,values] = SBparameters(sbm) and >> names = SBparameters(sbm) Change parameter k1 by typing >> sbm = SBparameters(sbm,'k1',1) |
| output = SBvariables(input) | |
|---|---|
| Usage |
Returns information about the variables in an SBmodel.
If a state vector is passed additionally, the corresponding values of the
variables are returned also.
input=[sbm]
sbm: SBmodel (function not applicable to an ODE file model)
output=[names,formulas] (if no statevector is given
names: Cell-array containing the names of the variables |
| Examples |
First type the following to define a model containing variables (available in the SBTOOLBOX2/_EXAMPLES folder): >> novak_tyson this defines an SBmodel with the name sbm. Then type: >> [names,formulas] = SBvariables(sbm) and >> names = SBvariables(sbm) If you want to determine the values of the models variables at the steady-state, you can type: >> [names,formulas,variablevalues] = SBvariables(sbm,SBsteadystate(sbm)) Note that for a time-invariant system the specification of the time instant of the given statevector is not needed. |
| output = SBreactions(input) | |
|---|---|
| Usage |
SBreactions: Returns information about the reactions in an SBmodel.
If a state vector is passed additionally, the corresponding
reaction rates are returned also.
USAGE:
======
[names,formulas,reversibleFlag,fastFlag] = SBreactions(model)
[names,formulas,reversibleFlag,fastFlag,reactionrates] = ...
SBreactions(model,statevector)
[names,formulas,reversibleFlag,fastFlag,reactionrates] = ...
SBreactions(model,time,statevector)
model: SBmodel (function can not be used on M-file model)
statevector: vector with corresponding statevalues
time: time instant of the statevector (only needed for time
variant systems)
DEFAULT VALUES:
===============
statevector: not needed
time: 0 (makes no difference for time invariant systems)
Output Arguments:
=================
names: cell-array with models reaction names
formulas: cell-array with formuas for the kinetic laws of the
reactions
reversibleFlag: vector with same number of entries as reactions.
An entry of 0 indicates an irreversible reaction, an
entry of 1 indicates a reversible reaction. The ordering
is the same as the reaction names.
fastFlag: vector with same number of entries as reactions. An
entry of 1 indicates a fast reaction, an entry of 0
indicates a reaction that is determined by its kinetic
rate law.
reactionrates: the reaction rates at the given state and time
|
| Examples |
First type the following to define a model containing variables (available in the SBTOOLBOX2/_EXAMPLES folder): >> novak_tyson this defines an SBmodel with the name sbm. Then type: >> [names,formulas,reversibleFlag] = SBreactions(sbm) and >> names = SBreactions(sbm) If you want to determine the values of the reaction rates at the steady-state, you can type: >> [names,formulas,reversibleFlag,fastFlag,reactionrates] = SBreactions(sbm,SBsteadystate(sbm)) Note that for a time-invariant system the specification of the time instant of the given statevector is not needed. |
| output = SBfunctions(input) | |
|---|---|
| Usage |
This function returns information about the functions in an SBmodel. input=[sbm] sbm: SBmodel (function not applicable to an ODE file model) output=[names,formulas,arguments]
names: cell-arry containing the names of the functions |
| Examples |
First change to the SBTOOLBOX2/_EXAMPLES folder, then type: >> sbm = SBmodel('functionsExample.txt') this defines an SBmodel with the name sbm. Then type: >> [names,formulas,arguments] = SBfunctions(sbm) and >> names = SBfunctions(sbm)
|
| output = SBevents(input) | |
|---|---|
| Usage |
This function returns information about the events in an SBmodel. input=[sbm] sbm: SBmodel (function not applicable to an ODE file model) output=[names,triggers,variables,formulas]
names: cell-arry containing the names of the events The ordering of the elements in the cell-arrays is important. The i-th elements in the output variables belongs to the i-th event. |
| Examples |
First change to the SBTOOLBOX2/_EXAMPLES folder, then type: >> sbm = SBmodel('eventExample.txt') this defines an SBmodel with the name sbm. Then type: >> [names,triggers,variables,formulas] = SBevents(sbm) and >> names = SBevents(sbm)
|
| output = SBfunctionsMATLAB(input) | |
|---|---|
| Usage |
This function returns information about the functionsMATLAB functions in an SBmodel. input=[sbm] sbm: SBmodel (function not applicable to an ODE file model) output=functionsMATLAB functionsMATLAB: string containing function definitions written in standard MATLAB code. |
| Examples |
First change to the SBTOOLBOX2/_EXAMPLES folder, then type: >> sbm = SBmodel('functionsMATLABexample.txt') this defines an SBmodel with the name sbm. Then type: >> functionsMATLAB = SBfunctionsMATLAB(sbm) Look at the model using the SBedit function to see what this MATLAB function does and how it is used. |
| output = isparameterSB(input) | |
|---|---|
| Usage |
This function checks if a given "name" is a parameter in given model. input=[sbm, name]
sbm: SBmodel or ODE file model output=flag flag: 0 = no parameter with given name present. 1 = parameter with given name is present in the model. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = isstateSB(input) | |
|---|---|
| Usage |
This function checks if a given "name" is a state in given model. input=[sbm, name]
sbm: SBmodel or ODE file model output=flag flag: 0 = no state with given name present. 1 = state with given name is present in the model. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = isvariableSB(input) | |
|---|---|
| Usage |
This function checks if a given "name" is a variable in given model. input=[sbm, name]
sbm: SBmodel or ODE file model output=flag flag: 0 = no variable with given name present. 1 = variable with given name is present in the model. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = isreactionSB(input) | |
|---|---|
| Usage |
This function checks if a given "name" is a reaction in given model. input=[sbm, name]
sbm: SBmodel or ODE file model output=flag flag: 0 = no reaction with given name present. 1 = reaction with given name is present in the model. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = stateindexSB(input) | |
|---|---|
| Usage |
This function returns the index of a specified state in the given model. input=[sbm, name]
sbm: SBmodel or ODE file model output=index index: =[]: specified name is not a state in the given model. Otherwise it contains the index of the state in the model. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = variableindexSB(input) | |
|---|---|
| Usage |
This function returns the index of a specified variable in the given model. input=[sbm, name]
sbm: SBmodel or ODE file model output=index index: =[]: specified name is not a variable in the given model. Otherwise it contains the index of the variable in the model. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = reactionindexSB(input) | |
|---|---|
| Usage |
This function returns the index of a specified reaction in the given model. input=[sbm, name]
sbm: SBmodel or ODE file model output=index index: =[]: specified name is not a reaction in the given model. Otherwise it contains the index of the reaction in the model. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
| output = usedelaySB(input) | |
|---|---|
| Usage |
usedelaySB: checks if an SBmodel contains the delaySB function. output = usedelaySB(model) model: SBmodel Output Arguments: ================= output: =1 if "delaySB" function is present in the model, =0 if not |
| Examples |
An example model containing delays is present in the folder:
SBTOOLBOX2/_EXAMPLES/special. Please change into this folder and have a look at
the runExamples.m function that will display and simulate the models.
To run the usedelaySB function you just type:
>> model = SBmodel('example_delay.txt') |
| output = useeventSB(input) | |
|---|---|
| Usage |
useeventSB: checks if an SBmodel contains events. output = useeventSB(model) model: SBmodel Output Arguments: ================= output: =1 if events are present in the model, =0 if not |
| Examples | An example model containing delayed events is present in the folder: SBTOOLBOX2/_EXAMPLES/special. Please change into this folder and have a look at the runExamples.m function that will display and simulate the models. |
| output = usealgebraicSB(input) | |
|---|---|
| Usage |
usealgebraicSB: checks if an SBmodel contains algebraic rules. output = usealgebraicSB(model) model: SBmodel Output Arguments: ================= output: =1 if algebraic rules present in the model, =0 if not |
| Examples |
An example model containing algebraic rules is present in the folder:
SBTOOLBOX2/_EXAMPLES/special. Please change into this folder and have a look at
the runExamples.m function that will display and simulate the models.
To run the usealgebraicSB function you just type:
>> model = SBmodel('example_algebraic_rule.txt') |
| output = usefastSB(input) | |
|---|---|
| Usage |
usefastSB: Checks if an SBmodel contains "fast" reactions.
output = usefastSB(model)
model: SBmodel
Output Arguments:
=================
output: =1 if reactions with the "fast" flag set are present,
=0 if not
|
| Examples |
An example model containing fast reactions is present in the folder:
SBTOOLBOX2/_EXAMPLES/special. Please change into this folder and have a look at
the runExamples.m function that will display and simulate the models.
To run the usefastSB function you just type:
>> model = SBmodel('example_fast_reaction.txtbc') |
| output = hasmoietyconservationsSB(input) | |
|---|---|
| Usage |
hasmoietyconservationsSB: Checks if an SBmodel contains moiety conservations. output = hasmoietyconservationsSB(model) model: SBmodel Output Arguments: ================= output: =1 if moiety conservations are present, =0 if not |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
Experiment Creation and Handling
| output = SBexperiment(input) | |
|---|---|
| Usage |
This function creates an SBexperiment object, defining experiment settings.
input=[] Invoking SBexperiment without arguments returns an empty SBexperiment object. Otherwise SBexperiment objects can be created from a data structure that corresponds to the internal experiment data structure, from a previously defined SBexperiment object expin, and from an experiment description file "filename".exp (the extension '.exp' is mandatory). The output consists of an SBexperiment object exp. |
| Examples | Please have a look at the contents of the SBTOOLBOX2/_EXAMPLES/experiment folder, which contains an example model, experiment and a short script combining model and experiment. The defined experiment uses all features and contains the documentation of the syntax. |
| output = SBstruct(input) | |
|---|---|
| Usage |
This function returns the internal data structure of an SBexperiment object. input=[exp] exp is the SBexperiment object for which to return the data structure. output=[SBstructure] The output consists of the internal data structure of exp, defined above. Note that instead of SBstruct also the MATLAB struct command can be used, resulting in exactly the same output. |
| Examples | Should be self-explaining. |
| SBcreateEXPfile(input) | |
|---|---|
| Usage |
This function converts an SBexperiment object to a text file description that is written in the
current directory.
input=[exp] The only required input is an SBexperiment object exp that is to be converted to an experiment text file description. The second input argument is optional and determines the filename of the EXP file. If the filename is not given the content of the experiments name field is used as filename.
|
| Examples | Should be self-explaining. |
| output = SBmergemodexp(input) | |
|---|---|
| Usage |
This function merges an SBmodel with an SBexperiment object. The result is a merged SBmodel that can be simulated and will reflect the
nominal models behavior under the experimental conditions that are defined in the experiment description.
input=[sbm,exp]
sbm: An SBmodel output=[expmodel]
expmodel: An SBmodel in which the model (sbm) and the experiment (exp) have been merged. |
| Examples | Please have a look at the contents of the SBTOOLBOX2/_EXAMPLES/experiment folder, which contains an example model, experiment and a short script combining model and experiment. The defined experiment uses all features and contains the documentation of the syntax. |
| output = isSBexperiment(input) | |
|---|---|
| Usage | This function has a single input argument and simply checks if the input argument is an SBexperiment. If it is an SBexperiment 1 is returned. Otherwise 0. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
Measurement Creation and Handling
| output = SBmeasurement(input) | |
|---|---|
| Usage |
This function creates an object that contains
measurement data from real experiments or insilico computations.
input = []
SBmeasurementstructure: Internal measurement data structure, used for representation of an SBmeasurement object. output: The output can be a new SBmeasurement object. In the case that several measurements are represented in the same Excel file (on separate sheets), the output is a cell-array where each element is an SBmeasurement object.
|
| Examples |
Example Excel and CSV data files are provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> measurements = SBmeasurement('MeasurementExample.xls'); This creates SBmeasurement objects from an Excel file. In the above Excel file 2 measurements are stored. Each on a separate sheet. The output measurements is thus a cell-array with 2 elements. Each element is an SBmeasurement object. Have also a look at the Excel file to get an idea of how it is formatted. A corresponding CSV example is the following: >> measurement = SBmeasurement('MeasurementExample.csv'); In CSV files only single measurements can be present and the output is thus always an SBmeasurement object. |
| output = SBstruct(input) | |
|---|---|
| Usage |
This function returns the internal data structure of an SBmeasurement object. input=[SBmeasurement] SBmeasurement is the SBmeasurement object for which to return the data structure. output=[SBmeasurementstructure] The output consists of the internal data structure of the SBmeasurement object, defined above. Note that instead of SBstruct also the MATLAB struct command can be used, resulting in exactly the same output. |
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder. Then type:
>> measurements = SBmeasurement('MeasurementExample.xls') |
| output = SBmeasurementdata(input) | |
|---|---|
| Usage |
This functions allows to extract information from an SBmeasurement structure USAGE: ====== [time, componentNames] = SBmeasurementdata(measurement) [time, componentNames, values] = SBmeasurementdata(measurement) [time, componentNames, values,minvalues,maxvalues] = SBmeasurementdata(measurement) measurement: SBmeasurement object Output Arguments: ================= time: time vector of all measurement instants componentNames: cell-array containing the names of the measured components values: matrix containing all the measurements of the components. One row per time instant and one column per measured component. The ordering of the columns corresponds to the ordering of the names in the "componentNames" output variable. Non measured elements are set to NaN (not a number). minvalues: matrix containing all the min values for the measured components. One row per time instant and one column per measured component. The ordering of the columns corresponds to the ordering of the names in the "componentNames" output variable. Non measured elements are set to NaN (not a number). maxvalues: matrix containing all the max values for the measured components. One row per time instant and one column per measured component. The ordering of the columns corresponds to the ordering of the names in the "componentNames" output variable. Non measured elements are set to NaN (not a number). |
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder. Then type:
>> measurement = SBmeasurement('MeasurementExample.csv'); Information about the components present in the SBmeasurement object can be obtained by writting: >> [time, names, values] = SBmeasurementdata(measurement) |
| SBexportCSVmeasurement(input) | |
|---|---|
| Usage |
Exports an SBmeasurement object to a CSV (comma separated value) file.
The format of the written CSV file is explained above.
input = [SBmeasurement]
SBmeasurement: SBmeasurement object containing the data. If no filename is specified, the filename is constructed from the name of the data object. |
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder. Then type:
>> measurement = SBmeasurement('MeasurementExample.csv'); The SBmeasurement object can be exported to a CSV file by typing >> SBexportCSVmeasurement(measurement,'ExportData'); |
| SBexportXLSmeasurement(input) | |
|---|---|
| Usage |
Exports an SBmeasurement object to an Excel file.
The format of the written XLS file is explained above.
input = [SBmeasurement]
SBmeasurement: SBmeasurement object containing the data. |
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder. Then type:
>> measurement = SBmeasurement('MeasurementExample.csv'); The SBmeasurement object can be exported to an XLS file by typing >> SBexportXLSmeasurement(measurement,'ExportData2'); |
| SBexportXLSmeasurements(input) | |
|---|---|
| Usage |
Exports several SBmeasurement objects to an Excel file. Each measurement to a separate Excel sheet.
The format of the written XLS file is explained above.
input = [measurements,filename]
measurements: Cell-array containing SBmeasurement objects. |
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder. Then type:
>> measurements = SBmeasurement('MeasurementExample.xls'); The cell array with the SBmeasurement objects can be exported to an XLS file by typing >> SBexportXLSmeasurements(measurements,'ExportData2'); |
| output = SBvisualizemeasurement(input) | |
|---|---|
| Usage |
This function can be used to graphically visualize data stored in an SBmeasurement object. The function used for plotting is
SBplot.
input = [measurement] measurement: SBmeasurement object containing the data. If an output argument is specified, the data are not plotted, but a structure is returned that can be used as input argument for SBplot to show the data. |
| Examples |
Change into the SBTOOLBOX2/_EXAMPLES folder. Then type:
>> measurement = SBmeasurement('MeasurementExample.csv'); The contents of the SBmeasurement object can be visualized by typing >> SBvisualizemeasurement(measurement) The circles mark the instants at which measurements are present in the data. In the legend the name/formula of the measurements and (if present) the component notes are shown. If an output argument is specified the function does not plot the results but returns a structure, that can be used for plotting by SBplot.
>> output = SBvisualizemeasurement(measurement) |
| output = isSBmeasurement(input) | |
|---|---|
| Usage | This function has a single input argument and simply checks if the input argument is an SBmeasurement object. If it is an SBmeasurement object 1 is returned. Otherwise 0. |
| Examples | Not really needed? Otherwise mail me so I can make an example. |
Export of SBmodel
| SBcreateODEfile(input) | |
|---|---|
| Usage |
This function converts an SBmodel to a MATLAB ODE file that is written in the
current directory.
input=[sbm] The only required input is an SBmodel sbm that is to be converted to an ODE file. The second input argument is optional and determines the filename of the ODE file. If the filename is not given the content of the models name field is used as filename. The optional argument eventFlag indicates (if set to one) that the SBcreateODEfile function should also create an event handling function and an event assignment function. These functions are required for the simulation of models that contain discrete state events. If not specified otherwise this flag is zero per default. The optional argument dataFileFlag has the following meaning: dataFileFlag=1: an additional file is created allowing to determine variable and reaction rate values for given state values and time vector. If set to 0, no such file is created (default). |
| Examples |
Load the Novak-Tyson cell cycle model by typing: >> novak_tyson Create the ODE file and the datafile from the SBmodel. >> SBcreateODEfile(sbm,'example', 1); To simulate the ODE file and visualize the results type:
>> initialConditions = example(); This only determined the trajectories for the states of the model. To determine also the trajectories of the reaction rates and the variables type:
>> help datafile_example The variable output is a MATLAB structure with the result of the simulation. Please inspect this structure to see what it contains. Compare it also to the result from: >> output = SBsimulate(sbm,400) |
| output = SBcreateTempODEfile(input) | |
|---|---|
| Usage |
This function creates a temporary ODE file, same as
SBcreateODEfile, but the file is written in the systems temporary
directory. It creates also a datafile and eventhandling files if wanted.
No filename is passed, but temporary filenames/functionnames are chosen automatically
and returned back as output argument. Since the function also includes the path to
the systems temporary directory in the MATLAB path the returned functionnames can be
used directly. For example, for simulation using the MATLAB integrators.
input=[sbm]
sbm: SBmodel to convert to an ODE file description output = [ODEfctname, ODEfilefullpath, DATAfctname, EVENTfctname, EVENTASSGNfctname]
ODEfctname: Name of the function (filename without .m extension) The names of the data and event functions are returned as empty string in the case that the corresponding flags are set to 0. |
| deleteTempODEfileSB(input) | |
|---|---|
| Usage |
This function should be used to delete the created temporary files, created using the function SBcreateTempODEfile,
after having been used. It not only deletes the ODE file, but also the data and event handling files, if present.
input=[ODEfilefullpath]
ODEfilefullpath: The variable of the same name, returned by SBcreateTempODEfile. |
| SBcreateTEXTfile(input) | |
|---|---|
| Usage |
This function converts an SBmodel to a file containing a textual description of the model in terms of ODEs.
This textfile can then be loaded as SBmodel using SBmodel.
Please note that the extension of such a file is .txt.
input=[sbm] The only required input is an SBmodel sbm that is to be converted to a textfile. The second input argument is optional and determines the filename of the textfile. If the filename is not given the content of the models name field is used as filename.
|
| Examples |
First run the example from SBmodel above. Then type: >> SBcreateTEXTfile(sbm,'example'); This command takes the SBmodel sbm as input an exports it into a textfile example.txt. You can load the textfile again into an SBmodel by typing: >> model = SBmodel('example.txt') |
| SBcreateTEXTBCfile(input) | |
|---|---|
| Usage |
This function converts an SBmodel to a file containing a textual description of the model
in terms of reaction equations. This textfile can then be loaded as SBmodel using
SBmodel. Please note that the extension of such a file is .txtbc.
input=[sbm] The only required input is an SBmodel sbm that is to be converted to a textfile. The second input argument is optional and determines the filename of the textfile. If the filename is not given the content of the models name field is used as filename.
|
| Examples |
Change into the SBTOOLBOX2/example folder. Then type >> edit bcmodel.txtbc This is a model in the TEXTBC format. You easily see the difference to the TEXT format, which is based on ODEs. To load the model type: >> model = SBmodel('bcmodel.txtbc'); To export the model again as a TEXTBC file type: >> SBcreateTEXTBCfile(model,'test'); |
| SBexportSBML(input) | |
|---|---|
| Usage |
This functions exports an SBmodel to an SBML model file.
input=[sbm]
The only required input is an SBmodel sbm that is to be exported to an SBML model. In order to be able to correctly export an SBmodel to SBML
additional information in the the type, compartment, and unittype fields in the SBmodel's internal datastructure are needed.
The SBexportSBML function determines this information automatically if not already present.
|
| Examples |
Change into the SBTOOLBOX2/example folder and type: >> sbm = SBmodel('SBMLexampleLevel1.xml') This converts the SBML model to an SBmodel. The sbmlnotes fields are already set correctly. >> SBexportSBML(sbm) This exports the SBmodel to an SBML model of level 2. In order to get an idea about the needed contents of the sbmlnotes fields in the internal data structure, type the following: >> SBedit(sbm) and click once on the Export SBML button. An example for a model, for which the additional information is not yet present, can be run by the following commands: >> novak_tyson This is a script that defines a simple example model. Typing SBedit(sbm) it can be visualized. To convert it to SBML please type: >> SBexportSBML(sbm)
|
| output = SBconvert2MA(input) | |
|---|---|
| Usage |
This function takes an SBmodel and if possible returns the stoichiometric
matrix, the numeric kinetic parameters, and the initial conditions. The SBmodel is not allowed
to contain variables, functions, events, or functionsMATLAB. All right hand sides of the ODEs have to be
defined in terms of reaction names (see also SBstoichiometry). All reactions need to be irreversible.
Please note that the function is NOT parsing the reaction kinetics to check if they are correct mass action kinetic rate laws. The user needs to make sure that this is the case. Examples of correct expressions are:
Reaction = k * species1 * species2 The kinetic rate constant is then simply determined by setting all species concentrations to 1 and evaluating the rate expressions. input = [model] model: SBmodel output = [MAstructure]
The MAstructure output argument has the following structure: |
| Examples |
Change into the SBTOOLBOX2/example folder and type:
>> model = SBmodel('bcmodel.txtbc') |
Simulation Functions
| output = SBsimulate(input) | |
|---|---|
| Usage |
This function simulates an SBmodel or an ODE file created by
SBcreateODEfile. In case the model is given as an SBmodel, not only the
trajectories for the models states are determined, but also the time
trajectories for all variables and reaction rates in the model.
input=[model]
model: SBmodel or string with name of ODE file to be simulated If no output arguments are given, the result of the simulation is plotted 1) online during the simulation for monitoring purposes - the simulation can here be stopped at every instant by just clicking on the "Stop" button. 2) after the simulation is finished the simulation data is plotted using the SBplot function, allowing to browse the simulation data. In case an output argument is specified (e.g., output), the following structure is returned:
output.time: Vector with time instants for the results The following fields are only present in case the model as been given as an SBmodel:
output.variables: Cell-array with variable names |
| Examples |
First run the example from SBmodel above. Then type: >> SBsimulate(sbm) This simulates the SBmodel sbm from 0 to 20 time units using the initial conditions in sbm and the MATLAB ode23s integrator. The result is plotted using SBplot. >> output = SBsimulate(sbm,'ode45',[0 100],[1 1 1]) This simulates the SBmodel sbm from 0 to 100 time units from the given initial conditions and the MATLAB ode45 integrator. The result is returned as a structure in output. |
| output = SBstochsim(input) | |
|---|---|
| Usage |
Stochastic simulation of SBmodels that only contain mass
action kinetics. The simulator is based on the paper:
Ullah, M., Schmidt, H., Cho, K.-H., Wolkenhauer, O. (2006)
Deterministic Modelling and Stochastic Simulation of Pathways
using MATLAB, IEE Proceedings - Systems Biology, 153(2), 53-60
The SBmodel needs to have a certain format, explained below.
USAGE:
======
[output] = SBstochsim(model,time,V)
[output] = SBstochsim(model,time,V,units)
[output] = SBstochsim(model,time,V,units,runs)
[output] = SBstochsim(model,time,V,units,runs,Nsample)
model: SBmodel
There are certain limitations on an SBmodel used for
stochastic simulation. Please read further below.
V: Volume/NumbersFlag: If a number is given then this number
is in interpreted as the volume of the reaction space
(given in Liter). This is necessary in order to do
stochastic simulations if the species in the model are in
concentration units. If the species in the model are given
in molecule numbers, the volume is not important and this
is indicated by setting V to [].
units: This value is only used in the case that the species
are defined in concentration units. Per default nM
(units=1e-9) are assumed for all species. If the model uses
uM the units argument needs to be set to 1e-6, etc.
(default: 1e-9 used only if V has a numeric value)
time: End time for simulation
runs: number of realizations(simulation runs) (default: 1)
Nsample: Each Nsample-th point will be used for output
(to save memory) (default: 100)
Output Arguments:
=================
If no output arguments are given, the result of the simulation is
plotted (if runs>1 only the mean is plotted). Otherwise the output
argument has the following structure:
output.time: cell-array with time vectors for the single
runs
output.speciesdata: cell-array with simulation data for the
single runs
output.runs: number of runs
output.timemean: ensemble of all time instants in the
single runs
output.speciesdatamean: matrix containing the means of the
simulation data
output.species: cell-array containing the names of the
species
FORMAT OF THE SBmodel:
======================
SBmodels that can be used for stochastic simulation need to
follow some rules:
1) All reaction kinetics need to be of mass action type and be
defined in the following syntax:
'ReactionName' = 'kineticParameter' * ...
2) All reactions have to be irreversible. You can use the
function SBmakeirreversible to convert your model
3) The reactions can at maximum have 2 substrates and 2 products.
4) The right hand side of the ODEs needs only to consist of
reaction rate terms and eventually stoichiometric coefficients.
This is necessary in order to be able to determine the
stoichiometric matrix. More information about the required
syntax can be found in the help text of the function
SBstoichiometry
5) No variables, functions, events, functionsMATLAB are allowed to
be present.
6) Initial conditions of species are assumed to be given in numbers
of molecules
|
| Examples |
Please change into the SBTOOLBOX2/_EXAMPLES folder. >> model = SBmodel('stochexample.txtbc'); This loads a model that is based on the model published in: Unified phototransduction model from Hamer et al., Visual Neuroscience 22, 417-436. The model has been modified considerably to test the rhodopsin shut-off kinetics.
>> time = 20 |
Plotting Functions
| SBplot(input) | |
|---|---|
| Usage |
This function has a graphical user interface. It allows to plot simulation data returned from a MATLAB integrator
or from SBsimulate. It has no output arguments. The use of it is self-explanatory. Several datasets can be handled and selected.
Apart from only plotting the data on different axes settings (lin,linlog,log, etc.) the SBplot GUI also allows to display the
fourier transform and the autocorrelation of selected signals.
Per default the mean value is substracted before the computation of the FFT and the autocorrelation. For the FFT this can be overridden by setting the global variable doRemoveZeroComponentFlag to 0 before calling SBplot.
input = [time,data]
input = [datastruct1] The datastructures are created most easily using the function createdatastructSBplotSB.
time: Column vector with time information datastruct: datastructure with all the plotting data (allows for displaying several datastructs at a time in the same GUI).
|
| Examples |
First run the example from SBmodel above. Then type:
>> SBsimulate(sbm)
>> output = SBsimulate(sbm)
|
| SBplot2(input) | |
|---|---|
| Usage |
This function has a graphical user interface. It allows to plot data that is best visualized using bar graphs.
The user can customize axis titles, and visualize several different data sets at a time. A simple export functionality
allows to construct figures containing subplots.
input = [datastruct1] datastruct1-10: Structure with information about the datasets that are to be displayed. SBplot2 can accept up to 10 different datastructures which can be displayed. The structure of the input arguments is defined as follows:
datastruct.name: Descriptive name for the datastructure All fields of the structure need to be correctly initialized. |
| Examples | For examples please execute the examples given for the parameter sensitivity analysis functions. |
| output = createdatastructSBplotSB(input) | |
|---|---|
| Usage |
This function allows to pack the standard input argument of the SBplot function into a datastructure that also
can be used as input argument for the SBplot function. The advantage is that the SBplot function then can take several
of these structures as input arguments and allows to browse all the different plots.
input = [time,data]
time: Column vector with time information The output is a datastructure that can be passed to SBplot. |
| Examples |
>> novak_tyson % this generates the Novak Tyson model in the workspace. >> output = SBsimulate(sbm) >> data1 = createdatastructSBplotSB(output.time,output.statevalues, ... output.states,'All the states'); >> data2 = createdatastructSBplotSB(output.time,output.reactionvalues, ... output.reactions,'All the reactions'); >> data3 = createdatastructSBplotSB(output.time,output.variablevalues, ... output.variables,'All the variables'); >> SBplot(data1,data2,data3) Note that you can change between the datasets in the upper left corner of the SBplot window. |
| output = createdatastruct2SBplotSB(input) | |
|---|---|
| Usage |
createdatastruct2SBplotSB: Converts simulation data,
returned from SBsimulate or SBPDsimulate to a datastruct that
can be passed to SBplot for plotting.
USAGE:
======
[datastruct] = createdatastruct2SBplotSB(simdata)
[datastruct] = createdatastruct2SBplotSB(simdata,name)
simdata: simulation data returned by SBsimulate and SBPDsimulate
name: name for the datastruct
DEFAULT SETTINGS:
=================
name: 'unnamed'
Output Arguments:
=================
datastruct: structure that can be displayed by SBplot
(>> SBplot(datastruct))
|
| Examples |
>> novak_tyson % get Novak Tyson model in the workspace. >> simdata = SBsimulate(sbm) >> datastructure = createdatastruct2SBplotSB(simdata); >> SBplot(datastructure) |
Simple Analysis Functions
| output = SBsteadystate(input) | |
|---|---|
| Usage |
This function determines the steady-state of a model given as SBmodel or as ODE file, created by SBcreateODEfile.
The function is limited to time-invariant models. Otherwise an error will occur. The function is able to deal
with models having a singular Jacobian, e.g., due to moiety conservations.
input=[model]
model: SBmodel or string with name of ODE file
output=[steadystate]
steadystate: Vector with the steady-state values. If steady-state could not be found steadystate=[]. |
| Examples |
First define a model by typing: >> novak_tyson Then determine a steady-state by typing: >> [steadystate, residual] = SBsteadystate(sbm) This determines the steady-state and the residual for the SBmodel sbm, starting the search at the initial conditions given in sbm, using default options for the solver and nominal values for the parameters. |
| output = SBjacobian(input) | |
|---|---|
| Usage |
Determines the Jacobian of a given SBmodel or an ODE file description. The Jacobian is obtained by numerical differentiation
around a given state. This function should only be used for time-invariant systems. If used for time-variant systems an error will occur.
input=[model,state]
model: SBmodel or string with name of ODE file for which to determine the Jacobian.
output=[jacobian]
jacobian: Jacobian of the model at the given state. |
| Examples |
First define a model by typing: >> novak_tyson Then determine the Jacobian at the state corresponding to the initial conditions stored in the model by typing: >> Jacobian = SBjacobian(sbm,SBinitialconditions(sbm)) |
| [output] = SBmoietyconservations(input) | |
|---|---|
| Usage | This function determines algebraic relationships, present in a given model. These algebraic relations can be
due to moitey conservations and other conservation laws. The model can be specified as SBmodel or as ODE file.
input = [model]
model: SBmodel or ODE file model description. When no output arguments are specified the function will simply display the found algebraic relations in the MATLAB window. output = [depVarIndex, depVarConstant, depVarFactor, message]
depVarIndex: Index of dependent states |
| Examples |
An example SBML model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> sbm = SBmodel('testsingular'); |
| SBreducemodel(input) | |
|---|---|
| Usage |
Reduces an SBmodel by identifying algebraic relations in its ODEs and deleting the corresponding time dependent variables.
The function first checks if the SBmodel contains algebraic relations between the time dependent variables.
If there are, it lets the user decide which variables to delete and replaces these by static variables.
Due to moiety conservations algebraic relations are often present in biological systems. However,
many analysis methods require non-singular systems. This function helps to avoid this problem. input = [sbm] sbm: SBmodel to reduce (not applicable to ODE file model descriptions) output = [sbmreduced] sbmreduced: Reduced SBmodel. If sbm is non-singular, sbmreduced = sbm
|
| Examples |
An example SBML model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> sbm = SBmodel('testsingular');
>> SBsimulate(sbm)
|
| [output] = SBstoichiometry(input) | |
|---|---|
| Usage |
Determines the stoichiometric matrix for the given model. In order to be
able to do that the differential equations for the components have to be
expressed in terms of reaction rates. The stoichiometric constants need
to be numeric and multiplied to the reaction terms. Example:
d/dt(A) = -1*Re1+2*Re3-Re5+3.141*Re8 Especially when importing models from SBML the right hand side of the ODEs might show a correction term that is needed for transport between two different compartments in the case that the species is defined in concentration units. In this case the ODE can look as follows: d/dt(B): (-1*Re1+2*Re3-Re5+3.141*Re8)/compartmentsize This syntax is also accepted. In this case the stoichiometric elements in the parenthesis will be divided by compartmentsize. The compartmentsize is only allowed to be a parameter! It can not be a numeric value, a state, a variable, or a function! Except the above shown pair of parentheses, no additional parentheses are allowed to appear in the ODE definitions. Otherwise, and in case that not only reaction rates are present in the ODE expression, the corresponding component is not taken into account for the stoichiometric matrix. input = [model] model: SBmodel to determine the stoichiometric matrix for. output = [N,componentNames,reactionNames,reversibleFlag]
N: Stoichiometric matrix |
| Examples |
An example SBML model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> novak_tyson |
| [output] = SBreactantstoichiometry(input) | |
|---|---|
| Usage |
Determines the reactant stoichiometric matrix for the given model. Non-elementary reactions are taken into account ... otherwise this
function would not really make sense. The same limitations regarding the model syntax apply as for the SBstoichiometry function.
input = [model] model: SBmodel to determine the stoichiometric matrix for. output = [L] N: Reactant stoichiometric matrix |
| Examples | |
| [output] = SBmakeirreversible(input) | |
|---|---|
| Usage |
For certain analysis methods it is useful that all reaction rate
expressions in a model are irreversible. This function takes an SBmodel
as input and replaces all reversible reactions by irreversible ones. This
is done by splitting up reversible reaction rates into one forward and one
backward rate. For this to be possible it is IMPORTANT that the reaction
rate expressions that are marked as reversible in the model are defined
in the following format:
ReactionRate = RateForward - RateReverse where ReactionRate can be any reaction rate name, and the terms RateForward and RateReverse can be any mathematical expressions, involving parameters, states, functions, and/or variables. However, it is IMPORTANT that there is only one minus sign in the top level of the formula. Minus signs in eventual parentheses are not taken into account for the parsing and are therefor, of course, allowed to be present. Examples:
R1 = Rf1 - Rr1 Additionally it is important that all ODE right hand sides are defined in terms of reaction rate terms, as discussed under the function SBstoichiometry. input = [model] model: SBmodel for which to convert reversible reactions to irreversible ones. output = [modelout] modelout: Converted model, where all reversible reactions have been exchanged against irreversible ones. |
| Examples |
An example SBML model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> novak_tyson In the SBedit window you can see that 4 reversible reactions have been converted to 8 irreversible ones. The ODE expressions are updated accordingly. |
Local Parameter Sensitivity Analysis Functions
| output = SBsensdataosc(input) | |
|---|---|
| Usage |
This function allows to generate data that subsequently can be
used for different kinds of parametric sensitivity analyses. Used only
for oscillating systems! This function should only be used in the case that no events are present in the model.
The data is obtained by simulation of the nominal and perturbed systems. In each simulation of a perturbed system only a single parameter is perturbed. The used integrator for this is 'ode23s'. As initial state for the simulation the initial conditions stored in the model are used. As nominal parameter values the parameter values stored in the model are used.
input = [sbm,timeData]
sbm: SBmodel (not useable with ODE model file)
timeData = [timeHorizont]
timeHorizont: determines the time over which data is collected for
later analysis.
parameters: a cell-array with parameter names, determining the parameters
that are to be considered in the analysis (default: all parameters in model) The only required input arguments are sbm and timeData=[timeHorizont]. If no specified otherwise, default values are used. The output argument output is a MATLAB struct element with the following structure:
output.model: Model as obtained as input argument |
| Examples |
An example model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> novak_tyson
|
| output = SBsensdataoscevents(input) | |
|---|---|
| Usage | This function has exactly the same syntax as the function SBsensdataosc. The only difference is that it is used for the sensitivity analysis of models in which events are present. |
| Examples |
An example model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> sbm = SBmodel('eventexample2.txt')
|
| output = SBsensamplitude(input) | |
|---|---|
| Usage |
This function determines the local first order amplitude sensitivities (both normalized and non-normalize)
with respect to small changes in single parameters. Before invoking this function a dataset needs to be
determined using the SBsensdataosc function. To learn more about the implementation of this analysis please read the help text to this function in MATLAB. input = [datastructure] datastructure: This is the structure that is returned from the SBsensdataosc function. If no output argument is given, the determined data are plotted using the function SBplot2. The output argument output contains the information about the amplitude sensitivities and has the following structure:
output.S: Matrix, with elements S_ij (please read the help text in MATLAB to learn more) The reason for having different fields for parameters and names for the non-normalized and normalized sensitivities is due to the fact that zero nominal parameter values lead to zero normalized sensitivities for these parameters, and that zero nominal steady-state values of states lead to infinite normalized sensitivities. In these cases the normalized sensitivities for these parameters and states are not determined. The output.plotDataS and output.plotDataSn fields contain datastructures that can directly be used as input arguments for SBplot2 for visualization of the sensitivity analysis results. For information about how this data structure is defined please refer to the help text provided for the SBplot2 function. |
| Examples |
Please first execute the example given for the SBsensdataosc function. Then type: >> SBsensamplitude(output) Browse around in the appearing graphical user interface (SBplot2) to get an idea what it is doing. Note that the title of the figure is changing according to the chosen plot settings. |
| output = SBsensperiod(input) | |
|---|---|
| Usage |
This function determines the local first order period sensitivities (both normalized and non-normalize)
with respect to small changes in single parameters. Before invoking this function a dataset needs to be
determined using the SBsensdataosc function. To learn more about the implementation of this analysis please read the help text to this function in MATLAB. input = [datastructure] datastructure: This is the structure that is returned from the SBsensdataosc function. If no output argument is given, the determined data are plotted using the function SBplot2. The output argument output contains the information about the period sensitivities and has the following structure:
output.S: Matrix, with elements S_ij (please read the help text in MATLAB to learn more) The reason for having different fields for parameters and names for the non-normalized and normalized sensitivities is due to the fact that zero nominal parameter values lead to zero normalized sensitivities for these parameters, and that zero nominal steady-state values of states lead to infinite normalized sensitivities. In these cases the normalized sensitivities for these parameters and states are not determined. The output.plotDataS and output.plotDataSn fields contain datastructures that can directly be used as input arguments for SBplot2 for visualization of the sensitivity analysis results. For information about how this data structure is defined please refer to the help text provided for the SBplot2 function. |
| Examples |
Please first execute the example given for the SBsensdataosc function. Then type: >> SBsensperiod(output) Browse around in the appearing graphical user interface (SBplot2) to get an idea what it is doing. Note that the title of the figure is changing according to the chosen plot settings. |
| output = SBsensdatastat(input) | |
|---|---|
| Usage |
This function allows to to generate steady-state data that
subsequently can be used for different kinds of parametric sensitivity
analyses.
The data is obtained by determining the steady-states of the nominal and perturbed systems. In each calculation of a perturbed system only a single parameter is perturbed. As initial guess for the steady-state the initial conditions stored in the model are used. As nominal parameter values the parameter values stored in the model are used. In case the considered steady-state is unstable at least a good guess of the steady-state needs to be given in the model.
input = [sbm]
sbm: SBmodel (not useable with ODE model file) The output argument output is a MATLAB struct element with the following structure:
output.model: Model as obtained as input argument |
| Examples |
An example model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> novak_tyson
|
| output = SBsensstat(input) | |
|---|---|
| Usage |
This function determines the local first order steady-state sensitivities (both normalized and non-normalize)
with respect to small changes in single parameters. Before invoking this function a dataset needs to be
determined using the SBsensdatastat function. To learn more about the implementation of this analysis please read the help text to this function in MATLAB. input = [datastructure] datastructure: This is the structure that is returned from the SBsensdatastat function. If no output argument is given, the determined data are plotted using the function SBplot2. The output argument output contains the information about the steady-state sensitivities and has the following structure:
output.S: Matrix, with elements S_ij (please read the help text in MATLAB to learn more) The reason for having different fields for parameters and names for the non-normalized and normalized sensitivities is due to the fact that zero nominal parameter values lead to zero normalized sensitivities for these parameters, and that zero nominal steady-state values of states lead to infinite normalized sensitivities. In these cases the normalized sensitivities for these parameters and states are not determined. The output.plotDataS and output.plotDataSn fields contain datastructures that can directly be used as input arguments for SBplot2 for visualization of the sensitivity analysis results. For information about how this data structure is defined please refer to the help text provided for the SBplot2 function. |
| Examples |
Please first execute the example given for the SBsensdatastat function. Then type: >> SBsensstat(output) Browse around in the appearing graphical user interface (SBplot2) to get an idea what it is doing. Note that the title of the figure is changing according to the chosen plot settings. |
| output = SBmca(input) | |
|---|---|
| Usage |
This function uses the steady state sensitivity analysis functions of the
SBtoolbox2 to determine flux control coefficients and concentration
control coefficients. Additionally it computes elasticity coefficients.
It is important to note that all states in the analyzed SBmodel are
assumed to represent concentrations of substrates and all reactions
enzymatic reactions. If this is not the case for certain states and/or
reactions the user needs to postprocess the results by deleting the
corresponding columns and rows in the matrices FCC, CCC, EC. Furthermore,
the model should only contain irreversible reactions (consider the use of
SBmakeirreversible).
input = [model]
model: SBmodel If no output argument is given, the determined MCA data (FCC, CCC, EC) are plotted using the function SBplot2.
Otherwise, the output argument 'output' is a MATLAB struct element with the
following structure: |
| Examples | Should be self explaining. |
Global Parameter Sensitivity Analysis Functions
| output = SBsensglobalfast(input) | |
|---|---|
| Usage |
Global sensitivity analysis method: Extended FAST method
For more information see:
Y. Zheng and A. Rundell (2006) Comparative study of parameter
sensitivity analyses of the TCR-activated Erk-MAPK signalling
pathway, IEE Proc.-Syst. Biol., Vol. 153, No. 4, 201-211
Saltelli, A., Tarantola, S., and Chan, K.P.S. (1999) A quantitative
model-independent method for global sensitivity analysis of model
output, Technometrics, 41, 39–56
USAGE:
======
SBsensglobalfast(model,timevector)
SBsensglobalfast(model,timevector,paramNames)
SBsensglobalfast(model,timevector,paramNames,OPTIONS)
[output] = SBsensglobalfast(model,timevector)
[output] = SBsensglobalfast(model,timevector,paramNames)
[output] = SBsensglobalfast(model,timevector,paramNames,OPTIONS)
model: SBmodel to perform the global sensitivity analysis for
timevector: vector of timeinstants to consider
paramNames: cell-array with names of the parameters to consider
OPTIONS: structure with optional settings:
OPTIONS.statenames: cell-array with state names which to consider
as model outputs
OPTIONS.variablenames: cell-array with variable names which to
consider as model outputs
OPTIONS.reactionnames: cell-array with reaction names which to
consider as model outputs
OPTIONS.Nsim: Number of simulation to carry out (approximate
value)
OPTIONS.range: Order of magnitude of parameter perturbations
OPTIONS.firstorder: =0: use total effect, =1: use firstorder appr.
OPTIONS.objectivefunction: ='relative': the differences between
nominal and perturbed model are normalized to represent
relative changes in each considered variable. ='absolute':
no normalization is done. Alternatively, the user can provide
the name for an own objective function to use. As template
you can have a look at the two objectivefunctions in the
folder:
SBTOOLBOX2/analysis/globalparametersensitivity/auxiliary
OPTIONS.integrator: Structure with optional settings for the
integrator
DEFAULT VALUES:
===============
paramNames: Consider all parameters in the model
OPTIONS.statenames: Consider all states in the model
OPTIONS.variablenames: {} (no variables)
OPTIONS.reactionnames: {} (no reactions)
OPTIONS.Nsim: 1000
OPTIONS.range: 1
OPTIONS.firstorder: 0 (use total effect)
OPTIONS.objectivefunction: 'relative'
OPTIONS.integrator: [] (default integrator settings)
Output Arguments:
=================
If no output argument is specified, the result is plotted.
Otherwise, the output is a structure with the following fields:
output.Nsim: Number of performed simulations
output.method: Name of the global sensitivity method
output.parameters: Considered parameters
output.overallmeasure: Sensitivity indices for overall model output
output.overallparamranking: Parameter ranking regarding overall
model output
output.singlecomponents: Names of the components, considered outputs
output.singlemeasure: Single sensitivity indices for all considered
model outputs
output.singleparamranking: Parameter ranking for each considered
model output
|
| Examples | |
| output = SBsensglobalprcc(input) | |
|---|---|
| Usage |
Global sensitivity analysis method: PRCC method
For more information see:
Y. Zheng and A. Rundell (2006) Comparative study of parameter
sensitivity analyses of the TCR-activated Erk-MAPK signalling
pathway, IEE Proc.-Syst. Biol., Vol. 153, No. 4, 201-211
Draper, N., and Smith, H. (1981) Applied regression analysis,
Wiley, New York, 2nd edn.
USAGE:
======
SBsensglobalprcc(model,timevector)
SBsensglobalprcc(model,timevector,paramNames)
SBsensglobalprcc(model,timevector,paramNames,OPTIONS)
[output] = SBsensglobalprcc(model,timevector)
[output] = SBsensglobalprcc(model,timevector,paramNames)
[output] = SBsensglobalprcc(model,timevector,paramNames,OPTIONS)
model: SBmodel to perform the global sensitivity analysis for
timevector: vector of timeinstants to consider
paramNames: cell-array with names of the parameters to consider
OPTIONS: structure with optional settings:
OPTIONS.statenames: cell-array with state names which to consider
as model outputs
OPTIONS.variablenames: cell-array with variable names which to
consider as model outputs
OPTIONS.reactionnames: cell-array with reaction names which to
consider as model outputs
OPTIONS.Nsim: Number of simulation to carry out (approximate
value)
OPTIONS.range: Order of magnitude of parameter perturbations
OPTIONS.objectivefunction: ='relative': the differences between
nominal and perturbed model are normalized to represent
relative changes in each considered variable. ='absolute':
no normalization is done. Alternatively, the user can provide
the name for an own objective function to use. As template
you can have a look at the two objectivefunctions in the
folder:
SBTOOLBOX2/analysis/globalparametersensitivity/auxiliary
OPTIONS.integrator: Structure with optional settings for the
integrator
DEFAULT VALUES:
===============
paramNames: Consider all parameters in the model
OPTIONS.statenames: Consider all states in the model
OPTIONS.variablenames: {} (no variables)
OPTIONS.reactionnames: {} (no reactions)
OPTIONS.Nsim: 1000
OPTIONS.range: 1
OPTIONS.objectivefunction: 'relative'
OPTIONS.integrator: [] (default integrator settings)
Output Arguments:
=================
If no output argument is specified, the result is plotted.
Otherwise, the output is a structure with the following fields:
output.Nsim: Number of performed simulations
output.method: Name of the global sensitivity method
output.parameters: Considered parameters
output.overallmeasure: Sensitivity indices for overall model output
output.overallparamranking: Parameter ranking regarding overall
model output
output.singlecomponents: Names of the components, considered outputs
output.singlemeasure: Single sensitivity indices for all considered
model outputs
output.singleparamranking: Parameter ranking for each considered
model output
|
| Examples | |
| output = SBsensglobalsobol(input) | |
|---|---|
| Usage |
Global sensitivity analysis method: SOBOL's method
For more information see:
Y. Zheng and A. Rundell (2006) Comparative study of parameter
sensitivity analyses of the TCR-activated Erk-MAPK signalling
pathway, IEE Proc.-Syst. Biol., Vol. 153, No. 4, 201-211
Sobol, I.M. (2001) Global sensitivity indices for nonlinear
mathematical models and their Monte Carlo estimates,
Math. Comp. Simul., 55, 271–280
USAGE:
======
SBsensglobalsobol(model,timevector)
SBsensglobalsobol(model,timevector,paramNames)
SBsensglobalsobol(model,timevector,paramNames,OPTIONS)
[output] = SBsensglobalsobol(model,timevector)
[output] = SBsensglobalsobol(model,timevector,paramNames)
[output] = SBsensglobalsobol(model,timevector,paramNames,OPTIONS)
model: SBmodel to perform the global sensitivity analysis for
timevector: vector of timeinstants to consider
paramNames: cell-array with names of the parameters to consider
OPTIONS: structure with optional settings:
OPTIONS.statenames: cell-array with state names which to consider
as model outputs
OPTIONS.variablenames: cell-array with variable names which to
consider as model outputs
OPTIONS.reactionnames: cell-array with reaction names which to
consider as model outputs
OPTIONS.Nsim: Number of simulation to carry out (approximate
value)
OPTIONS.range: Order of magnitude of parameter perturbations
OPTIONS.firstorder: =0: use total effect, =1: use firstorder appr.
OPTIONS.objectivefunction: ='relative': the differences between
nominal and perturbed model are normalized to represent
relative changes in each considered variable. ='absolute':
no normalization is done. Alternatively, the user can provide
the name for an own objective function to use. As template
you can have a look at the two objectivefunctions in the
folder:
SBTOOLBOX2/analysis/globalparametersensitivity/auxiliary
OPTIONS.integrator: Structure with optional settings for the
integrator
DEFAULT VALUES:
===============
paramNames: Consider all parameters in the model
OPTIONS.statenames: Consider all states in the model
OPTIONS.variablenames: {} (no variables)
OPTIONS.reactionnames: {} (no reactions)
OPTIONS.Nsim: 1000
OPTIONS.range: 1
OPTIONS.firstorder: 0 (use total effect)
OPTIONS.objectivefunction: 'relative'
OPTIONS.integrator: [] (default integrator settings)
Output Arguments:
=================
If no output argument is specified, the result is plotted.
Otherwise, the output is a structure with the following fields:
output.Nsim: Number of performed simulations
output.method: Name of the global sensitivity method
output.parameters: Considered parameters
output.overallmeasure: Sensitivity indices for overall model output
output.overallparamranking: Parameter ranking regarding overall
model output
output.singlecomponents: Names of the components, considered outputs
output.singlemeasure: Single sensitivity indices for all considered
model outputs
output.singleparamranking: Parameter ranking for each considered
model output
|
| Examples | |
| output = SBsensglobalwals(input) | |
|---|---|
| Usage |
Global sensitivity analysis method: WALS (weighted average of local
sensitivities)
For more information see:
Y. Zheng and A. Rundell (2006) Comparative study of parameter
sensitivity analyses of the TCR-activated Erk-MAPK signalling
pathway, IEE Proc.-Syst. Biol., Vol. 153, No. 4, 201-211
Bentele, M., Lavrik, I., Ulrich, M., Stößer, S., Heermann, D.W.,
Kalthoff, H., Krammer, P.H., and Eils, R. (2004) Mathematical
modeling reveals threshold mechanism in CD95-induced apoptosis,
J. Cell Biol., 166, (6), pp. 839–851
USAGE:
======
SBsensglobalwals(model,timevector)
SBsensglobalwals(model,timevector,paramNames)
SBsensglobalwals(model,timevector,paramNames,OPTIONS)
[output] = SBsensglobalwals(model,timevector)
[output] = SBsensglobalwals(model,timevector,paramNames)
[output] = SBsensglobalwals(model,timevector,paramNames,OPTIONS)
model: SBmodel to perform the global sensitivity analysis for
timevector: vector of timeinstants to consider
paramNames: cell-array with names of the parameters to consider
OPTIONS: structure with optional settings:
OPTIONS.statenames: cell-array with state names which to consider
as model outputs
OPTIONS.variablenames: cell-array with variable names which to
consider as model outputs
OPTIONS.reactionnames: cell-array with reaction names which to
consider as model outputs
OPTIONS.Nsim: Number of simulation to carry out (approximate
value)
OPTIONS.range: Order of magnitude of parameter perturbations
OPTIONS.deltaPert: relative perturbation for determining local
sensitivities. If a parameters nominal value is zero a
warning will appear.
OPTIONS.objectivefunction: ='relative': the differences between
nominal and perturbed model are normalized to represent
relative changes in each considered variable. ='absolute':
no normalization is done. Alternatively, the user can provide
the name for an own objective function to use. As template
you can have a look at the two objectivefunctions in the
folder:
SBTOOLBOX2/analysis/globalparametersensitivity/auxiliary
OPTIONS.integrator: Structure with optional settings for the
integrator
DEFAULT VALUES:
===============
paramNames: Consider all parameters in the model
OPTIONS.statenames: Consider all states in the model
OPTIONS.variablenames: {} (no variables)
OPTIONS.reactionnames: {} (no reactions)
OPTIONS.Nsim: 1000
OPTIONS.range: 1
OPTIONS.deltaPert: 0.02 (2 percent)
OPTIONS.objectivefunction: 'relative'
OPTIONS.integrator: [] (default integrator settings)
Output Arguments:
=================
If no output argument is specified, the result is plotted.
Otherwise, the output is a structure with the following fields:
output.Nsim: Number of performed simulations
output.method: Name of the global sensitivity method
output.parameters: Considered parameters
output.overallmeasure: Sensitivity indices for overall model output
output.overallparamranking: Parameter ranking regarding overall
model output
output.singlecomponents: Names of the components, considered outputs
output.singlemeasure: Single sensitivity indices for all considered
model outputs
output.singleparamranking: Parameter ranking for each considered
model output
|
| Examples | |
Localization of Mechanisms leading to Complex Behaviors
| [output] = SBlocbehavcomp(input) | |
|---|---|
| Usage |
Determines the importance of components in the
given biochemical system in the creation of an observed complex behavior,
such as multiple steady-states and sustained oscillations.
Central functions in the cell are often linked to complex dynamic behaviors, such as sustained oscillations and multistability, in a biochemical reaction network. Determination of the specific mechanisms underlying such behaviors is important, e.g., to determine sensitivity, robustness, and modelling requirements of given cell functions. The aim of the "SBlocbehavcomp" function is to identify the components in a biochemical reaction network, described by a set of ordinary differential equations, that are mainly involved in creating an observed complex dynamic behavior, such as sustained oscillations or multiple steady-states. Rather than analyzing the biochemical system in a state corresponding to the complex nonlinear behavior, the system is considered at its underlying unstable steady-state. This is motivated by the fact that all complex behaviors in unforced systems can be traced to destabilization (bifurcation) of some steady-state, and hence enables the use of tools from Linear System Theory to qualitatively analyze the sources of given network behaviors. A full description of this method can be found in "Linear systems approach to analysis of complex dynamic behaviours in biochemical networks", IEE Systems Biology, 1, 149-158 (2004) and "Identifying feedback mechanisms behind complex cell behavior", IEEE Control Systems Magazine, 24 (4), 91-102 (2004)
input = [model, steadystate]
model: SBmodel or ODE file to perform the analysis on. If no output arguments are given, the result of the analysis is plotted. The importances are color-coded. Blue color is used for positive importances, red color for negative importances that are smaller than -1, and black color for negative importances that are between 0 and -1. Since the determined epsilon perturbations are relative perturbations and therefor values for epsilon < -1 (0 > importances > -1) lead to a change of sign in the corresponding feedback loop, the two different colors for negative importances are used to distinguish these two cases. output = [importance, stateNames] importance and stateNames: To the i-th component (state) name corresponds the i-th importance value, defined by importance_i = 1/epsilon_i, where epsilon_i is the relative change in the feedback interconnection in the i-th state (stateNames{i}) that stabilizes the considered unstable steady-state. The smaller the absolute value of the required perturbation, this means, the larger importance_i, the more important role plays state i in the creation of the observed complex behavior. In case the stabilizing value of epsilon_i has a magnitude larger than maxEpsilonValue, zero is returned for the corresponding importance. |
| Examples |
An example model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> novak_tyson
|
| [output] = SBlocbehavinteract(input) | |
|---|---|
| Usage |
Determines the importance of direct interactions
(e.g., reactions) between components in the given biochemical system in
the creation of an observed complex behavior, such as multiple
steady-states and sustained oscillations. Read below to get more insight
into the method.
Central functions in the cell are often linked to complex dynamic behaviors, such as sustained oscillations and multistability, in a biochemical reaction network. Determination of the specific mechanisms underlying such behaviors is important, e.g., to determine sensitivity, robustness, and modelling requirements of given cell functions. The aim of the "SBlocbehavinteract" function is to identify the mechanism in a biochemical reaction network, described by a set of ordinary differential equations, that are mainly involved in creating an observed complex dynamic behavior, such as sustained oscillations or multiple steady-states. Rather than analyzing the biochemical system in a state corresponding to the complex nonlinear behavior, the system is considered at its underlying unstable steady-state. This is motivated by the fact that all complex behaviors in unforced systems can be traced to destabilization (bifurcation) of some steady-state, and hence enables the use of tools from Linear System Theory to qualitatively analyze the sources of given network behaviors. A full description of this method can be found in "Linear systems approach to analysis of complex dynamic behaviours in biochemical networks", IEE Systems Biology, 1, 149-158 (2004) and "Identifying feedback mechanisms behind complex cell behavior", IEEE Control Systems Magazine, 24 (4), 91-102 (2004)
input = [model, steadystate]
model: SBmodel or ODE file to perform the analysis on.
OPTIONS.plotTypeFlag: =0: linear y-axis, =1: logarithmic y-axis (default: 0). If no output arguments are given, the results of the analysis are plotted. The result is color coded. Blue color corresponds to positive elements of the corresponding nominal Jacobian, red color corresponds to negative elements. output = [importance, stateNames]
importance: each row corresponds to a direct interaction between states
in the considered system. The first element in a row determines the
index of the affected and the second the index of the affecting
state. The third element in a row determines the inverse of the
magnitude of the corresponding delta_ij value. delta_ij is the
value for the relative perturbation in the direct interaction from
state j to state i that stabilizes the considered steady-state.
The larger this inverse is, the more important is the direct effect
from state j on state i for the creation of the analyzed behavior. |
| Examples |
An example model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> novak_tyson
|
| [output] = SBlocbehavinteract2(input) | |
|---|---|
| Usage |
This function does basically the same as the SBlocbehavinteract function, except that it can be used in the case where
the open loop system is unstable. This function does not check if the determined perturbations actually stabilize the system at the considered
steady-state, but still gives a good insight into the importance of interactions in creating an observed complex behavior.
For more information please read the information about the SBlocbehavinteract function, and the help text for this function by typing >> help SBlocbehavinteract2 |
| Examples |
An example model is provided in the SBTOOLBOX2/_EXAMPLES folder. Change into this folder and type:
>> novak_tyson
Compare the result to the result obtained when using the SBlocbehavinteract function. Using the SBlocbehavinteract less interactions are plotted/returned as result, since only these are stabilizing the system. Furthermore the numerical values of the determined perturbations are slightly different. This is because using SBlocbehavinteract the analysis is done at the frequency where the critical eigenlocus crosses the real axis, while using SBlocbehavinteract2 the analysis is done at the frequency given by the imaginary part of the unstable eigenvalue. |
Model Reduction Functions (Require the Symbolic Toolbox)
| output = SBredallreac(input) | |
|---|---|
| Usage |
Wrapper for the SBredreac function allowing to easily go through a whole model and reduce the kinetic rate expressions of
all reactions that are possible to reduce. This function also compares the reduced with the original model after each accepted
reduction step. The user can freely modify the way how the models are compared, by customising the comparison routine in this function.
input = [sbm,time,experiments]
sbm: SBmodel to reduce output = [sbmreduced] sbmreduced: Reduced SBmodel.
|
| Examples | This function requires the presence of the SBPD package. An example script reduceExample.m can be found in the SBPD/_EXAMPLES/ModredExample folder. |
| output = SBprepredreac(input) | |
|---|---|
| Usage |
Prepares a model for subsequent reduction of reaction rate
expressions. Eventual "power(x,y)" expressions are exchanged against
"x^y". Reaction rates are expanded by substituting in variables. Ununsed
elements (reactions, variables, and parameters) are deleted from the
model. Furthermore reference simulations are performed based on which the
models reactions can be reduced in following steps.
input = [sbm, time, experiments]
sbm: SBmodel to reduce output = [output] output: Structure with necessary information that is used as input for the SBredreac function. |
| Examples | This function requires the presence of the SBPD package. An example script reduceExample.m can be found in the SBPD/_EXAMPLES/ModredExample folder. |
| output = SBredreac(input) | |
|---|---|
| Usage |
Reduction of single reaction expressions with the goal of reducing
complexity and number of parameters. This function requires the prior
execution of the SBprepredreac.
input = [prepoutput, reaction]
prepoutput: Result returned from SBprepredreac. output = [sbmreduced] sbmreduced: Reduced SBmodel.
|
| Examples | This function requires the presence of the SBPD package. An example script reduceExample.m can be found in the SBPD/_EXAMPLES/ModredExample folder. |
Optimization
| output = simplexSB(input) | |
|---|---|
| Usage |
Downhill Simplex Method in Multidimensions. Algorithm based on
section 10.4 in "Numerical Recipes in C", ISBN 0-521-43108-5.
The algorithm has been modified in order to be able to take into account
simple box constraints on parameter values.
input=[FUN,X]
FUN: Function to minimize output = [X,FVAL,EXITFLAG]
X: Found solution |
| Examples | |
| output = simannealingSB(input) | |
|---|---|
| Usage |
Minimization by simulated annealing. Algorithm partly
based on section 10.4 in "Numerical Recipes in C", ISBN 0-521-43108-5.
The implementation of this simmulated annealing method uses a nonlinear
simplex search as basis. The algorithm has been modified in order to be
able to take into account simple box constraints on parameter values.
input=[FUN,X]
FUN: Function to minimize output = [X,FVAL,EXITFLAG]
X: Found solution |
| Examples | |
| output = isresSB(input) | |
|---|---|
| Usage |
Stochastic Ranking for Constrained Evolutionary Minimization.
The algorithm is described in:
The code of this function is based on the original code written by
input=[FUN,X]
FUN: Function to minimize output = [X,FVAL,EXITFLAG]
X: Best feasible individual ([] if EXITFLAG = 0) |
| Examples | |
| output = SSmSB(input) | |
|---|---|
| Usage |
Interface function to a Global optimization algorithm for
MINLP's based on Scatter Search.
Note that the optimization method itself is not included
in the toolbox but that it can be downloaded. For further information,
please click on the "Download" link on the SBTOOLBOX2.org webpage.
SSm attempts to solve problems of the form:
min F(x) s. t.: ceq(x) = 0 (equality constraints)
x
c_L <= c(x) <= c_U (inequality constraints)
x_L <= x <= x_U (bounds on the decision variables)
If you use SSm and publish the results, please cite the following
papers:
Egea, J.A., M. Rodriguez-Fernandez, J. R. Banga and R. Martí (2007)
Scatter Search for chemical and bioprocess optimization. Journal of
Global Optimization 37(3):481-503.
Rodriguez-Fernandez, M., J. A. Egea and J. R. Banga (2006) Novel
Metaheuristic for Parameter Estimation in Nonlinear Dynamic
Biological Systems. BMC Bioinformatics 7:483.
USAGE:
======
[info] = SSmSB()
[X,FVAL,result] = SSmSB(FUN,X,OPTIONS)
FUN: Function to optimize
X: Starting Guess (Not strictly required but kept for the sake of
compatible optimization function calls)
OPTIONS: structure containing options for the algorithm:
OPTIONS.vtr: cost function value to reach
OPTIONS.highbounds: vector containing upper bounds for
parameters. Instead of a vector highbounds can also be
a scalar > 1. In the latter case the highbounds are
determined by multiplying this scalar to the initial
parameter guess X. This latter case works only for
positive X(i) ... if negative present then the user needs
to specify a whole highbounds vector.
OPTIONS.lowbounds: vector containing lower bounds for
parameters. Instead of a vector lowbounds can also be a
scalar < 1. In the latter case the lowbounds are
determined by multiplying this scalar to the initial
parameter guess X. This latter case works only for
positive X(i) ... if negative present then the user
needs to specify a whole lowbounds vector.
User options
OPTIONS.maxfunevals: Maximum number of function evaluations
OPTIONS.maxtime: Maximum time (in minutes) for optimization
OPTIONS.silent: =0: output of info, =1: no output
OPTIONS.plot. Plots convergence curves:
0-Deactivated,
1-Plot curves on line,
2-Plot final results
OPTIONS.weight: Weight that multiplies the penalty term added
to the objective function in constrained problems
OPTIONS.log_var: Indexes of the variables which will be used
to generate diverse solutions in different orders of
magnitude
Global options
OPTIONS.dim_refset: Number of elements in Refset
OPTIONS.ndiverse: Number of solutions generated by the
diversificator
OPTIONS.initiate: Type of Refset initialization
0: Take bounds, middle point and fill by euclidean
distance
1: Evaluate all the diverse solutions,take the
dim_refset/2 best solutions and fill by
euclidean distance
OPTIONS.combination: Type of combination of Refset elements
1: hyper-rectangles
2: linear combinations
OPTIONS.regenerate: Type of Refset regeneration
1: Regeneration by distance diversity
2: Regeneration by direction diversity
3: Randomly alternates 1 and 2
OPTIONS.delete: Maximum number of Refset elements
deleted when regenerating Refset
'standard': Maximum deleted elements=dim_refset/2
(half of the elements)
'aggressive': Delete dim_refset-1 (all of them
except the best solution found)
OPTIONS.intens: Iteration interval between intensifications
OPTIONS.tolfun: Function tolerance for joining the Refset
OPTIONS.diverse_criteria: Criterion for diversification in
the Refset
1: euclidean distance
2: tolerances
OPTIONS.tolx: Variable tolerance for joining the Refset when
the euclidean distance is deactivated
Local options
OPTIONS.local.solver: Choose local solver:
0: local search off, 'constrnew','fminsearch',
'nomad','solnp','n2fb','dn2fb','dhc','fsqp','ipopt',
'misqp','lsqnonlin'
OPTIONS.local.n1: Number of function evaluations before
applying local search for the 1st time
OPTIONS.local.n2: Minimum number of function evaluations
in the global phase between 2 local calls
Output Arguments:
=================
info: calling the function w/o input argument returns
information about the options and a flag indicating if
the algorithm can handle constraints or not
X: Found solution
FVAL: Value of the function FUN at X
result: Structure containing results
result.fbest = Best objective function value
found after the optimization
result.xbest = Vector providing the best
function value
result.cpu_time = Time in seconds consumed in the
optimization
result.f = Vector containing the best
objective function value after
each iteration
result.x = Matrix containing the best vector
after each iteration
result.time = Vector containing the cpu time
consumed after each iteration
result.neval = Vector containing the number of
function evaluations after each
iteration
result.numeval = Number of function evaluations
result.local_solutions = Local solutions found by the
local solver (in rows)
result.local_solutions_values = Function values of the local
solutions
result.end_crit = Criterion to finish the
optimization
1: Maximal number of function
evaluations achieved
2: Maximum allowed CPU Time
achieved
3: Value to reach achieved
DEFAULT VALUES:
===============
OPTIONS.lowbounds: 0.1 => lowbounds = 0.1*X
OPTIONS.highbounds: 10 => highbounds = 10*X
OPTIONS.maxfunevals: 400*ndim
OPTIONS.maxtime: 120 (minutes)
OPTIONS.silent: 0
OPTIONS.plot 0
OPTIONS.weight: 1000
OPTIONS.log_var: [1:ndim] (all variables)
OPTIONS.dim_refset: 'auto'
OPTIONS.ndiverse: 10*ndim
OPTIONS.initiate: 1
OPTIONS.combination: 1
OPTIONS.regenerate: 3
OPTIONS.delete: 'standard'
OPTIONS.intens: 10
OPTIONS.tolfun: 1e-4
OPTIONS.diverse_criteria: 1
OPTIONS.tolx: 1e-3
OPTIONS.local.solver: 'dn2fb'
OPTIONS.local.n1: 100*ndim
OPTIONS.local.n2: 200*ndim
|
| Examples | |
| output = fSSmSB(input) | |
|---|---|
| Usage |
Interface function to a Global optimization algorithm for
MINLP's based on Scatter Search ("fast" version).
Please have a look at SSmSB. The calling syntax and the
options are the same.
Note that the optimization method itself is not included
in the toolbox but that it can be downloaded. For further information,
please click on the "Download" link on the SBTOOLBOX2.org webpage.
|
| Examples | |
| output = pswarmSB(input) | |
|---|---|
| Usage |
Particle swarm pattern search algorithm for global optimization.
Algorithm developed by A. Ismael F. Vaz and L. N. Vicente. aivaz@dps.uminho.pt 04/04/2007 More information: http://www.norg.uminho.pt/aivaz/pswarm/ In case of a publication that was prepared using pswarm, users are asked to cite the following publication: A. I. F. Vaz and L. N. Vicente, A particle swarm pattern search method for bound constrained global optimization, Journal of Global Optimization, 39 (2007) 197-219. The PSwarm algorithm takes advantage of the particle swarm algorithm in looking for a global optimum in the search phase of the pattern search algorithm. The pattern search enforces convergence for a local optimum. If the global variable stopOptimization is set to 1, the optimization is stopped. This allows for stopping parameter estimation functions on user request.
input=[FUN,X]
FUN: Function to minimize output = [X,FVAL,EXITFLAG]
X: Best feasible individual ([] if EXITFLAG = 0) |
| Examples | |
Solvers
| [output] = fsolveSB(input) | |
|---|---|
| Usage |
This functions attempts to solve equations of the form FUN(X)=0
where FUN and X may be vectors. Newton iteration.
input = [FUN,X,OPTIONS]
FUN: Name of the function to solve (string). output = [X,FVAL,EXITFLAG]
X: Fond solution. |
| Examples | |
Statistics
| [output] = princompSB(input) | |
|---|---|
| Usage |
Compute principal components of X USAGE: ====== [pc,z,w,Tsq] = princomp(X) pc: the principal components z: the transformed data w: the eigenvalues of the covariance matrix Tsq: Hotelling's T^2 statistic for the transformed data |
| Examples | |
| [output] = clusteringSB(input) | |
|---|---|
| Usage |
Performs UPGMA on distance matrix and produces a denddrogram plot. Initially, each object is in its own cluster. At each step, the nearest 2 clusters are combined into a higher-level cluster. The distance between any 2 clusters A and B is taken to be the average of all distances between pairs of objects "a" in A and "b" in B. USAGE: ====== [] = clusteringSB(dist,labels,fontsize) [topology] = clusteringSB(dist,labels,fontsize) dist: [n x n] symmetric distance matrix labels: optional [n x q] matrix of group labels for dendrogram fontsize: optional font size for labels [default = 10] If no output argument is specified, the dendrogram is plotted. Otherwise the topology is returned to the workspace. |
| Examples | |
| [output] = pdistSB(input) | |
|---|---|
| Usage |
Determines the distance matrix for a set of points whose
coordinates are given as row-vectors in the data matrix.
USAGE:
======
D = pdistSB(datamatrix)
D = pdistSB(datamatrix, method)
datamatrix: datamatrix is an NxP matrix of coordinates for N points
in P dimensions
method: is an integer between 1 and 3 representing the chosen
method for computing the distance matrix (see note below)
DEFAULT VALUES:
===============
method: method chosen problem size dependend if not specified
Output Arguments:
=================
D: An NxN matrix, where the value of DMAT(i,j) corresponds to
the distance from datamatrix(i,:) to datamatrix(j,:)
Note:
=====
method=1: Usually fastest for small inputs. Takes advantage of the
symmetric property of distance matrices to perform
half as many calculations
method=2: Usually fastest for medium inputs. Uses a fully
vectorized method
method=3: Usually fastest for large inputs. Uses a partially
vectorized method with relatively small memory
requirement
|
| Examples | |
| [output] = prctileSB(input) | |
|---|---|
| Usage |
This function determines the percentiles of a sample, based on
interpolation.
USAGE:
======
[output] = prctileSB(data,p)
data: column vector of matrix where each sample corresponds
to one column
p: vector of percentage values to calculate the percentiles for
Output Arguments:
=================
output: column vector with same length as p, containing the
percentiles for the given percentages in p.
|
| Examples | |
| boxplotSB(input) | |
|---|---|
| Usage |
Plots a box-and-whisker diagram for the given data. The two sides
(green color) of the box define the lower and upper quartile. The
red line corresponds to the median. The whiskers are the blue
lines. Outliers are depicted as black dots.
USAGE:
======
boxplotSB(data)
boxplotSB(OPTIONS)
data: column vector of matrix where each sample corresponds to
one column
OPTIONS: structure containing options for the function
OPTIONS.samplenames: Cell-array with names or other
information of the samples
OPTIONS.boxWidth: Width of the boxes to be drawn
OPTIONS.whiskerLength: Whisker length relative to the length
of the box
OPTIONS.verticalFlag: Flag determining if the boxes are
oriented vertically (=1) or horizontally (=0)
DEFAULT VALUES:
===============
OPTIONS.samplenames: {'Sample 1','Sample 2', ...}
OPTIONS.boxWidth: 0.5
OPTIONS.whiskerLength: 1.5 (standard)
OPTIONS.verticalFlag: 0 (plot horizontally)
|
| Examples | |
| output = chi2cdfSB(input) | |
|---|---|
| Usage |
Cumulative density function of the chi-square distribution USAGE: ====== cdf = chi2cdfSB(x, n) For each element of 'x', compute the cumulative distribution function (CDF) at 'x' of the chisquare distribution with 'n' degrees of freedom. |
| Examples | |
| output = chi2invSB(input) | |
|---|---|
| Usage |
Quantile function of the chi-square distribution USAGE: ====== inv = chi2invSB(x, n) For each element of 'x', compute the quantile (the inverse of the CDF) at 'x' of the chisquare distribution with 'n' degrees of freedom. |
| Examples | |
| output = chi2pdfSB(input) | |
|---|---|
| Usage |
Probability density function of the chi-square distribution USAGE: ====== pdf = chi2pdfSB(x, n) For each element of 'x', compute the probability density function (PDF) at 'x' of the chisquare distribution with 'n' degrees of freedom. |
| Examples | |
| output = tcdfSB(input) | |
|---|---|
| Usage |
Cumulative density function of the t distribution USAGE: ====== cdf = tcdfSB(x, n) For each element of 'x', compute the CDF at 'x' of the t (Student) distribution with 'n' degrees of freedom, i.e., PROB (t(n) <= x). |
| Examples | |
| output = tinvSB(input) | |
|---|---|
| Usage |
Quantile function of the t distribution USAGE: ====== inv = tinvSB(x, n) For each component of 'x', compute the quantile (the inverse of the CDF) at 'x' of the t (Student) distribution with parameter 'n'. |
| Examples | |
| output = tpdfSB(input) | |
|---|---|
| Usage |
Probability density function of the t distribution USAGE: ====== pdf = tpdfSB(x, n) For each element of 'x', compute the probability density function (PDF) at 'x' of the t (Student) distribution with 'n' degrees of freedom. |
| Examples | |
| output = gamcdfSB(input) | |
|---|---|
| Usage |
Cumulative density function of the Gamma distribution USAGE: ====== cdf = gamcdfSB(x, a, b) For each element of 'x', compute the cumulative distribution function (CDF) at 'x' of the Gamma distribution with parameters 'a' and 'b'. |
| Examples | |
| output = gaminvSB(input) | |
|---|---|
| Usage |
Quantile function of the Gamma distribution USAGE: ====== inv = gaminvSB(x, a, b) For each component of 'x', compute the quantile (the inverse of the CDF) at 'x' of the Gamma distribution with parameters 'a' and 'b'. |
| Examples | |
| output = gampdfSB(input) | |
|---|---|
| Usage |
Probability density function of the Gamma distribution USAGE: ====== pdf = gampdfSB(x, a, b) For each element of 'x', return the probability density function (PDF) at 'x' of the Gamma distribution with parameters 'a' and 'b'. |
| Examples | |
| output = normcdfSB(input) | |
|---|---|
| Usage |
Cumulative densitiy function of the normal distribution USAGE: ====== cdf = normcdfSB(x, m, s) For each element of 'x', compute the cumulative distribution function (CDF) at 'x' of the normal distribution with mean 'm' and standard deviation 's'. Default values are 'm' = 0, 's' = 1. |
| Examples | |
| output = norminvSB(input) | |
|---|---|
| Usage |
Quantile function of the normal distribution USAGE: ====== pdf = norminvSB(x, m, s) For each element of 'x', compute the quantile (the inverse of the CDF) at 'x' of the normal distribution with mean 'm' and standard deviation 's'. Default values are 'm' = 0, 's' = 1. |
| Examples | |
| output = normpdfSB(input) | |
|---|---|
| Usage |
Probability density function of the normal distribution USAGE: ====== pdf = normpdfSB(x, m, s) For each element of 'x', compute the probability density function (PDF) at 'x' of the normal distribution with mean 'm' and standard deviation 's'. Default values are 'm' = 0, 's' = 1. |
| Examples | |
| output = swtestSB(input) | |
|---|---|
| Usage |
Shapiro-Wilk parametric hypothesis test of composite normality.
USAGE:
======
[H, pValue, SWstatistic] = swtestSB(x)
[H, pValue, SWstatistic] = swtestSB(x, alpha)
[H, pValue, SWstatistic] = swtestSB(x, alpha, tail)
This function performs the Shapiro-Wilk test to determine if the
null hypothesis of composite normality is a reasonable assumption
regarding the population distribution of a random sample x. The
desired significance level, alpha, is an optional scalar input
(default = 0.05). tail indicates the type of test (default = 1).
The Shapiro-Wilk hypotheses are:
Null Hypothesis: x is normal with unspecified mean and variance.
For tail = 0 (2-sided test), alternative: x is not normal.
For tail = 1 (1-sided test), alternative: x is upper the normal.
For tail = -1 (1-sided test), alternative: x is lower the normal.
This is an omnibus test, and is generally considered relatively
powerful against a variety of alternatives.
Shapiro-Wilk test is better than the Shapiro-Francia test for
Platykurtic sample. Conversely, Shapiro-Francia test is better than
the Shapiro-Wilk test for Leptokurtic samples.
When the series 'x' is Leptokurtic, swtestSB performs the
Shapiro-Francia test, else (series 'x' is Platykurtic) swtestSB
performs the Shapiro-Wilk test.
Inputs:
x - a vector of deviates from an unknown distribution. The
observation number must exceed 3 and be less than 5000.
Optional inputs:
alpha - The significance level for the test (default = 0.05).
tail - The type of the test (default = 1).
Outputs:
SWstatistic - The test statistic (non normalized).
pValue - is the p-value, or the probability of observing the
given result by chance given that the null hypothesis is true.
Small values of pValue cast doubt on the validity of the null
hypothesis.
H = 0 => Do not reject the null hypothesis at significance level
alpha.
H = 1 => Reject the null hypothesis at significance level
alpha.
References: Royston P. "Algorithm AS R94", Applied Statistics (1995)
Vol. 44, No. 4. AS R94 -- calculates Shapiro-Wilk normality test
and P-value for sample sizes 3 <= n <= 5000. Handles censored or
uncensored data. Corrects AS 181, which was found to be inaccurate
for n > 50.
|
| Examples | |
Signal
| output = xcorrSB(input) | |
|---|---|
| Usage |
Compute correlation R_xy of X and Y for various lags k:
R_xy(k) = sum_{i=1}^{N-k}{x_i y_{i-k}}/(N-k), for k >= 0
R_xy(k) = R_yx(-k), for k <= 0
usage: [R, lag] = xcorrSB(X)
usage: [R, lag] = xcorrSB(X, Y)
usage: [R, lag] = xcorrSB(X, Y, maxlag)
usage: [R, lag] = xcorrSB(X, Y, maxlag, scale)
Returns R(k+maxlag+1)=Rxy(k) for lag k=[-maxlag:maxlag].
Scale is one of:
'biased' for correlation=raw/N,
'unbiased' for correlation=raw/(N-|lag|),
'coeff' for correlation=raw/(correlation at lag 0),
'none' for correlation=raw
If Y is omitted, compute autocorrelation.
If maxlag is omitted, use N-1 where N=max(length(X),length(Y)).
If scale is omitted, use 'none'.
If X is a matrix, computes the cross correlation of each column
against every other column for every lag. The resulting matrix has
2*maxlag+1 rows and P^2 columns where P is columns(X). That is,
R(k+maxlag+1,P*(i-1)+j) == Rij(k) for lag k=[-maxlag:maxlag],
so
R(:,P*(i-1)+j) == xcorr(X(:,i),X(:,j))
and
reshape(R(k,:),P,P) is the cross-correlation matrix for X(k,:).
xcorr computes the cross correlation using an FFT, so the cost is
dependent on the length N of the vectors and independent of the
number of lags k that you need. If you only need lags 0:k-1 for
vectors x and y, then the direct sum may be faster:
unbiased:
( hankel(x(1:k),[x(k:N); zeros(k-1,1)]) * y ) ./ [N:-1:N-k+1](:)
biased:
( hankel(x(1:k),[x(k:N); zeros(k-1,1)]) * y ) ./ N
If length(x) == length(y) + k, then you can use the simpler
( hankel(x(1:k),x(k:N-k)) * y ) ./ N
Ref: Stearns, SD and David, RA (1988). Signal Processing Algorithms.
New Jersey: Prentice-Hall.
|
| Examples | |
| output = resampleSB(input) | |
|---|---|
| Usage |
resampleSB: resamples time series x1, which is sampled at the time
instances t1 to time series x2 using a sampling defined by t2.
t2: scalar representing sampling interval or vector of sampling
instances
method: 'zoh', 'linear', 'cubic'. The use of 'method' is optional.
(default: 'linear')
The output t2 is the vector that has been used for the resampling.
|
| Examples | |
| output = postpadSB(input) | |
|---|---|
| Usage |
postpadSB: Appends value c (default: 0) until to extend vector x to a length of l. Same with matrices x, where the dimension to extend is given by dim (default: 1). y = postpadSB(x, l) y = postpadSB(x, l, c) y = postpadSB(x, l, c, dim) |
| Examples | |
| output = prepadSB(input) | |
|---|---|
| Usage |
prepadSB: prepends value c (default: 0) until to extend vector x to a length of l. Same with matrices x, where the dimension to extend is given by dim (default: 1). y = prepadSB(x, l) y = prepadSB(x, l, c) y = prepadSB(x, l, c, dim) |
| Examples | |
| output = centeredfftSB(input) | |
|---|---|
| Usage |
centeredfftSB: Uses the fft function of MATLAB to determine a two sided spectrum of x, where te data in x have been sampled with the frequency Fs. [X,freq] = centeredfftSB(x,Fs) |
| Examples | |
| output = positivefftSB(input) | |
|---|---|
| Usage |
positivefftSB: Uses the fft function of MATLAB to determine a one sided spectrum of x, where te data in x have been sampled with the frequency Fs. [X,freq] = positivefftSB(x,Fs) |
| Examples | |
Auxiliary functions
| Auxiliary functions | |
|---|---|
| Usage |
The following functions are not documented in detail in this manual.
To obtain more information please type in MATLAB:
>> help "functionname" "functionname":
explodePCSB
andSB
piecewiseSB
delaySB |
