Site navigation:

Contents

PyDSTool provides a thin wrapper around the SciPy versions of the Levenberg-Marquardt least squares optimizer and the one-parameter BoundMin bounded minimizer, under a unifying class type ParamEst, which is implemented in `PyDSTool/Toolbox/ParamEst.py`. This class provides basic features such as a default residual function that is compatible with PyDSTool Model objects, easing the changing of model parameter values, computation of trajectories, and setting of additional parameters for each call to the function.

The user begins by creating and initializing a Param`Est class instance with a ``Model` system, the number of free parameters in the model to be fitted, the dependent variables names to use, and the residual function to use. *Either integration initial conditions or model parameters can be used as the free parameters.*

Residual functions must have a signature of the form `(s, p, tmesh [, <optional additional argument sequence>])`. The first argument `s` refers to the Param`Est class instance initialized by the user, which provides the function access to the model and other user-specified settings. The ``p` argument will be an array of new parameter values, *given in the same order as* `s.freeParNames`.

An explicit Jacobian defined in a model system (such as that calculated using the Symbolic toolbox differentiation functions) will automatically be used by the class.

Once the Param`Est object has been created, its ``run` method can be called in order to execute the actual optimization algorithm. Arguments to this call allow additional arguments to be sent to the residual function, and algorithmic tolerances to be set. By default, the Param`Est class calls the optimizers with their 'full output' options set, and stores the results in the dictionary ``s.pestResult`, as well as returning a *copy* of that dictionary. Note that this dictionary will be overwritten on the next call to `run`.

One benefit of organizing a parameter estimation problem inside a class such as Param`Est is that it gives the residual function greater power to store state inside its associated class instance. `

For further information see examples in `PyDSTool/tests` such as `pest_test1.py` for initialization of ParamEst class instances, overriding of default residual functions, and running of the optimizers.

This works in an N-dimensional parameter space on an n-dimensional model trajectory. This sub-class wraps the `leastsq` function from `scipy.minpack`. This algorithm is inherently unconstrained, but can be adapted to incorporate *soft* constraints in the residual function (see the provided example scripts).

The class attribute `_memory`, which is pre-declared and provided as a memory for the residual functions between calls. It is declared to be the array `zeros(self._tmesh_len*self._depvar_len, dtype=float64)`, to provide temporary storage while building the return array of residuals (see `residual_fn_LMpest_default_Ndim` for an example).

This works only in a one-dimensional parameter space for a one-dimensional model trajectory. This sub-class wraps `fminbound` from `scipy.optimize`. It minimizes subject to bound constraints.

You can fit user-defined qualitative "features" of a trajectory to those of experimental data or to predefined ideals using conventional optimization algorithms, such as least squares. This approach is under development but appears to work well in instances where standard approaches for which the fitting problem is ill-conditioned by virtue of having a "fitness landscape" that is too flat or too irregular near typical initial conditions.

A robust way to fit trajectory extrema in a given coordinate is to define events in the test model to find them accurately. The tools provided here assume that you have added appropriate events to your model to do this. This is described further in the following docstring for the example residual function `residual_fn_LMpest_extrema(s, p, tmesh)` exported from `ParamEst.py`:

- Example residual function for the qualitative fitting of local
- extrema locations in model trajectory to those of data, using least squares. This assumes that dictionaries containing the extrema data have been pre-computed and placed in alg_params, as under keys 'data_mins_t', 'data_mins_v', 'data_maxs_t', 'data_maxs_v', for the time and variable value locations of the maxima and minima. Each dictionary of extrema data is expected to be an array of values keyed by coordinate name. The generator specified by gen_name should exist in the model
s.testModel given to the ParamEst object at creation. This generator should contain separate events for detecting maxima and minima in each coordinate being fitted (e.g. zero crossing of first derivative of a coordinate, in appropriate direction). For a coordinate named 'x' these events are expected to have the names 'min_ev_x' and 'max_ev_x'. num_expected_mins and num_expected_maxs is per variable.

- extrema locations in model trajectory to those of data, using least squares. This assumes that dictionaries containing the extrema data have been pre-computed and placed in alg_params, as under keys 'data_mins_t', 'data_mins_v', 'data_maxs_t', 'data_maxs_v', for the time and variable value locations of the maxima and minima. Each dictionary of extrema data is expected to be an array of values keyed by coordinate name. The generator specified by gen_name should exist in the model

In addition to parameter estimation, one may use an algorithm to systematically alter a model in order to achieve a fit of its performance to given criteria. This may be called model estimation, a.k.a. model inference. To support this, a number of tools are provided for manipulating model descriptions (using ModelSpec), via a class of model Transforms. One may also take advantage of a library (class ModelLibrary) of model description primitives, from which to base a systematic search of a "model space" suitable to the model estimation problem.

A ModelManager instance is a repository for all models related by a class of transformations. In order to build model instantiations that are ready to simulate, the GDescriptor and MDescriptor classes are used to hold all the specific details of how to instantiate a model once it is mathematically specified. Upon demand, these are then fed by the model manager into a ModelConstructor object to build a new model. The model manager is also the access point for creating transformations of a model into another.