Home > Objects > @iFunc > fits.m



[pars,criteria,message,output] = fits(model, data, pars, options, constraints, ...) : fit a model on a data set


function [pars_out,criteria,message,output] = fits(model, a, pars, options, constraints, varargin)


 [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.
     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 

   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

  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).
             The termination tolerance for x. Its default value is 1.e-4.
             The termination tolerance for the function value. The default value is 1.e-4. 
             This parameter is used by fminsearch, but not fminbnd.
             Maximum number of iterations allowed.
             The maximum number of function evaluations allowed. 
             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
             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.
             Display additional information during fit: 'iter','off','final'. Default is 'iter'.
             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=...'

         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,c,m,o]=fits(gauss,data,[],'optimizer=fminpowell; OutputFcn=fminplot'); 
         figure; plot(a); hold on; plot(o.modelAxes, o.modelValue,'r');

 Version: Nov. 26, 2018
 See also fminsearch, optimset, optimget, iFunc, iData/fits, iData, ifitmakefunc


This function calls: This function is called by:
Generated on Mon 26-Nov-2018 15:08:42 by m2html © 2005. iFit (c) E.Farhi/ILL EUPL 1.1