[pars,criteria,message,output] = fits(model, data, pars, options, constraints, ...) : fit a model on a data set
@iFunc/fits find best parameter estimates in order to minimize the
fitting criteria using model 'fun', by mean of an optimization method
described with the 'options' structure argument.
Additional constraints may be set by fixing some parameters, or define
more advanced constraints (min, max, steps). The last arguments controls the
fitting options with the optimset mechanism, and the constraints to apply
during optimization.
[pars,...] = fits(model, data, pars, options, lb, ub)
uses lower and upper bounds as parameter constraints (double arrays)
[pars,...] = fits(model, data, pars, options, fixed)
indicates which parameters are fixed (non zero elements of array).
[pars,...] = fits(model, data, pars, 'optimizer', ...)
uses a specific optimizer and its default options=feval(optimizer,'defaults')
See below for suggested best optimizers.
[pars,...] = fits(model, data, pars, options, constraints, args...)
send additional arguments to the fit model(pars, axes, args...).
[optimizers,functions] = fits(iFunc)
returns the list of all available optimizers and fit functions/models.
[pars,...] = fits(iData_object)
searches for a Model in the data set, and then performs the fit.
[pars,...] = fits(iFunc_array, iData_array, ...)
vectorise the fit. When the two arrays have the same number of elements,
the fit is done per pair (model,data) in arrays.
fits(iFunc)
displays the list of all available optimizers and fit functions.
You may create new fit models with the 'edit(iFunc)' tool, or by arithmetic
operators combining iFunc and string objects.
When the data is entered as a structure or iData object with a Monitor value,
the fit is performed on Signal/Monitor.
When parameters, options, and constraints are entered as a string with
name=value pairs, the string is interpreted as a structure description, so
that options='TolX=1e-4; optimizer=fminpso' is a compact form for
options=struct('TolX','1e-4','optimizer','fminpso').
To set a constraint on a model parameter, define the 'constraint' input argument
or set the constraint directly on the model parameters with:
model.parameter='fix' % to lock its value during a fit process
model.parameter='clear' % or 'free' to unlock value during a fit process
model.parameter=[min max] % to bound value
model.parameter=[nan nan] % to remove bound constraint
model.parameter='' % to remove all constraints on 'parameter'
model.Constraint='' % to remove all constraints
The default fit options.criteria is 'least_square', but others are available:
least_square (|Signal-Model|/Error).^2 non-robust
least_absolute |Signal-Model|/Error robust
least_median median(|Signal-Model|/Error) robust, scalar
least_max max(|Signal-Model|/Error) non-robust, scalar
least_rfactor (|Signal-Model|/Error).^2/(Signal/Error).^2 non-robust
max_corrcoef 1-corrcoeff(Signal, Model) scalar
max_likelihood
Type <a href="matlab:doc(iData,'Fit')">doc(iData,'Fit')</a> to access the iFit/Fit Documentation.
Type <a href="matlab:doc(iData,'Optimizers')">doc(iData,'Optimizers')</a> to access the Optimizers Documentation.
input: model: model function (iFunc). When entered as an empty object, the
list of optimizers and fit models is shown.
data: array or structure/object (numeric or structure or cell)
Can be entered as a single numeric array (the Signal), or as a
structure/object with possible members
Signal, Error, Monitor, Axes={x,y,...}
or as a cell { x,y, ... , Signal }
or as an iData object
or as a file name
The 1st axis 'x' is row wise, the 2nd 'y' is column wise.
pars: initial model parameters (double array, string or structure).
when set to empty or 'guess', the starting parameters are guessed.
when set to 'current', the current model parameter values are used.
Named parameters can be given as a structure or string 'Amplitude=...; Width=...'
options: structure as defined by optimset/optimget (char/struct)
if given as a char, it defines the algorithm to use and its default % options (single optimizer name or string describing a structure).
when set to empty, it sets the default algorithm options (fmin).
options.TolX
The termination tolerance for x. Its default value is 1.e-4.
options.TolFun
The termination tolerance for the function value. The default value is 1.e-4.
This parameter is used by fminsearch, but not fminbnd.
options.MaxIter
Maximum number of iterations allowed.
options.MaxFunEvals
The maximum number of function evaluations allowed.
options.optimizer
Optimization method. Default is 'fminpowell' (char/function handle)
the syntax for calling the optimizer is e.g. optimizer(criteria,pars,options,constraints)
Best optimizers are:
fminpso: Particle Swarm Optimization
fminpowell: Powell with Coggins line search
fminhooke: Hooke-Jeeves direct search
fminralg: Shor R-algorithm
fminsimpsa: Simplex/simulated annealing
fminimfil: Unconstrained Implicit filtering
options.criteria
Minimization criteria. Default is 'least_square' (char/function handle)
the syntax for evaluating the criteria is criteria(Signal, Error, Model)
options.OutputFcn and options.PlotFcns
Function called at each iteration as outfun(pars, optimValues, state)
The 'fminplot' or 'fminstop' functions may be used.
options.Display
Display additional information during fit: 'iter','off','final'. Default is 'iter'.
options.Diagnostics
When set to 'on' or 1, returns the correlation coefficient and Hessian matrix
constraints: fixed parameter array. Use 1 for fixed parameters, 0 otherwise (double array)
OR use empty to not set constraints
OR use a structure with some of the following fields:
constraints.min: minimum parameter values (double array)
constraints.max: maximum parameter values (double array)
constraints.step: maximum parameter step/change allowed.
constraints.fixed: fixed parameter flag. Use 1 for fixed parameters, 0 otherwise (double array)
constraints.eval: expression making use of 'p', 'constraints', and 'options'
and returning modified 'p'
or function handle p=@constraints.eval(p)
OR use a string 'min=...; max=...'
output:
pars: best parameter estimates (double array)
criteria: minimal criteria value achieved (double)
message: return message/exitcode from the optimizer (char/integer)
output: additional information about the optimization (structure)
algorithm: Algorithm used (char)
funcCount: Number of function evaluations (double)
iterations: Number of iterations (double)
parsHistory: Parameter set history during optimization (double array)
criteriaHistory: Criteria history during optimization (double array)
modelValue: Final best model evaluation
parsHistoryUncertainty: Uncertainty on the parameters obtained from
the optimization trajectory (double)
The 'output' 4th return argument can be sent to 'fminplot' to plot the
criteria convergence and the parameter distributions (see example below).
ex: data=load(iData, [ ifitpath 'Data/sv1850.scn' ])
p=fits(data);
[p,c,m,o]=fits(gauss,data,[],'optimizer=fminpowell; OutputFcn=fminplot');
figure; plot(a); hold on; plot(o.modelAxes, o.modelValue,'r');
fminplot(o);
Version: Nov. 26, 2018
See also fminsearch, optimset, optimget, iFunc, iData/fits, iData, ifitmakefunc