SimBiology^®

sbioparamestim - Perform parameter estimation

Syntax

[k, result]= sbioparamestim(modelObj, tspan, xtarget, species_array, parameter_array) [...]= sbioparamestim(..., species_array, parameter_array, k0) [...]= sbioparamestim(..., species_array, parameter_array, k0, method)

Arguments

`k`	Vector of estimated parameter values.
`result`	`struct` with fields that provide information about the progress of optimization.
`tspan`	An `n-by-1` vector representing the time span of the target data `xtarget`.
`xtarget`	An `n-by-m` matrix, where `n` is the number of time samples and `m` is the number of states you would like to match during the simulation. States can only be species varying with time. You cannot use time varying (nonconstant) parameters. The number of rows of `xtarget` must be the same as the number of rows of `tspan`.
`species_array`	Either an array of species objects or a cell array of names of species in `modelObj` whose amounts should be matched during the estimation process. The length of the `species_array` must be the same as the number of columns in `xtarget`. If there are species with duplicate names in different compartments, either use qualified names to identify the species correctly or use an array of species objects to identify the species correctly. `sbioparamestim` assumes that the order of the species in `species_array` is the same as the order used to specify columns of `xtarget`. For example, a qualified name for a species named `sp1` that is in a compartment named `comp2` is `comp2.sp1`.
`parameter_array`	Either an array of parameter objects or a cell array of names of parameters in `modelObj` whose values should be estimated. If you do not specify `parameter_array`, `sbioparamestim` estimates all the parameters in the model. When a vector of parameter initial values (`k0`) is not specified, `sbioparamestim` takes the initial values from `modelObj`. When there are parameters with duplicate names, use either parameter objects or qualified parameter names to identify the right parameter object. For example, for a parameter named `param1` used in a reaction named `reaction1` and at the kinetic law level, the qualified name is `reaction1.param1`.
`k0`	Array of doubles that holds initial values of parameters to be estimated. The length of `k0` is same as that of `parameter_array`. When you specify `k0`, `sbioparamestim` ignores any initial values specified in active variants attached to the model. If left unspecified, `sbioparamestim` takes initial values for parameters from the model (`modelObj`) or, if there are active variants, `sbioparamestim` uses any initial values specified in the active variants. See `Variant object` for more information about variants.
`method`	Either a `string` or a cell array. If it is a `string`, it must be the name of the optimization algorithm to be used during the estimation process. Valid values are `'fminsearch'`, `'lsqcurvefit'`, `'lsqnonlin'`, `'fmincon'`, `'patternsearch'`, `'patternsearch_hybrid'`, `'ga'`, or `'ga_hybrid'`. If it is a cell array, it must have two elements: the first one is the name of the optimization method as described before and the second element is a MATLAB `struct` as returned by `optimset`, `gaoptimset`, or `psoptimset`. `sbioparamestim` uses the cell array option to specify user-defined optimization options. If you do not specify this argument, then it defaults to `'lsqcurvefit'` if the Optimization Toolbox™ is available; otherwise it defaults to `'fminsearch'`. `'fminsearch'` is a part of basic MATLAB and does not require the Optimization Toolbox. Note that `'fminsearch'` is an unconstrained optimization method and this could result in negative values for parameters. In that case, use another optimization method.

Description

[k, result]= sbioparamestim(modelObj, tspan, xtarget, species_array, parameter_array) estimates parameters of the SimBiology model object (modelObj), specified in parameter_array, so as to match species given by species_array with the target state (xtarget), whose time variation is given by the time span tspan. modelObj must be a top-level SimBiology model. A top-level SimBiology model object has its Parent property set to the SimBiology root object.

[...]= sbioparamestim(..., species_array, parameter_array, k0) lets you specify the initial values of parameters.

[...]= sbioparamestim(..., species_array, parameter_array, k0, method) lets you specify the optimization method to use.

Examples

Example 1

Given a model and some target data, estimate all of its parameters without having to specify any initial values. This is the simplest case. Estimate all of its parameters using the default method.

Load a model from the project, gprotein_norules.sbproj. The project contains two models, one for the wild-type strain (stored in variable m1), and one for the mutant strain (stored in variable m2). Load the G protein model for the wild-type strain.
```
sbioloadproject gprotein_norules m1;
```

Store the target data in a variable.

Gt = 10000;
tspan  = [0 10 30 60 110 210 300 450 600]';
Ga_frac = [0 0.35 0.4 0.36 0.39 0.33 0.24 0.17 0.2]';
xtarget = Ga_frac * Gt;

Store all model parameters in an array.

p_array = sbioselect(m1,'Type','parameter');

Store the species that should match target.

Ga = sbioselect(m1,'Type','species','Name','Ga');
% In this example only one species is selected.
% To match more than one targeted species data
% replace with selected species array.

Estimate the parameters.

[k, result] = sbioparamestim(m1, tspan, xtarget, Ga, p_array)

k =

    0.1988
    0.0000
    0.0045
    6.2859
    0.0040
    0.9726
    0.0000
    0.1164

result = 

          fval: 8.7248e+005
      residual: [9x1 double]
      exitflag: 2
    iterations: 2
     funccount: 27
     algorithm: 'large-scale: trust-region reflective Newton'
       message: [1x77 char]

Example 2

Estimate parameters specified in p_array and species specified in sp_array using different algorithms. This example uses the data from Example 1.

[k2,r2] = sbioparamestim(m1, tspan, xtarget, Ga, p_array, {}, 'patternsearch');
[k3,r3] = sbioparamestim(m1, tspan, xtarget, Ga, p_array, {}, 'ga');

[k1,r1] = sbioparamestim(m1, tspan, xtarget, Ga, p_array, ...
          {}, 'fmincon');
[k2,r2] = sbioparamestim(m1, tspan, xtarget, Ga, p_array, ...
          {}, 'patternsearch');
[k3,r3] = sbioparamestim(m1, tspan, xtarget, Ga, p_array, ...
          {}, 'ga')

Example 3

Estimate parameters specified in p_array, species specified in sp_array, and change default optimization options to use user-specified options. This example uses the data from Example 1.

myopt1 = optimset('Display','iter');
[k1,r1] = sbioparamestim(m1, tspan, xtarget, ...
          sp_array, p_array, {},{'fmincon', myopt1});

myopt2.Tolmesh = 1.0e-4;
[k2,r2] = sbioparamestim(m1, tspan, xtarget, ...
          sp_array, p_array, {},{'patternsearch', myopt2});

myopt3.PopulationSize = 50; 
myopt3.Generations = 20; 
[k3,r3] = sbioparamestim(m1, tspan, xtarget, ...
          sp_array, p_array, {},{'ga', myopt3});

Reference

Tau-Mu Yi, Hiroaki Kitano, and Melvin I. Simon. PNAS (2003) vol. 100, 10764–10769.