Home > Objects > @iData > fits.m

iFit/fits

PURPOSE ^

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

SYNOPSIS ^

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

DESCRIPTION ^

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

   @iData/fits find best parameters 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 fxing 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.
     The fit can be applied sequentially and independently onto iData object arrays.
  [pars,...] = fits(a, model, pars, options, lb, ub)
     uses lower and upper bounds as parameter constraints (double arrays)
  [pars,...] = fits(a, model, pars, options, fixed)
     indicates which parameters are fixed (non zero elements of array).
  [pars,...] = fits(a, model, pars, 'optimizer', ...)
     uses a specific optimizer and its default options=feval(optimizer,'defaults')
     See below for suggested best optimizers.
  [pars,...] = fits(a, model, pars, options, constraints, args...)
     send additional arguments to the fit model(pars, axes, args...)
  [optimizers,functions] = fits(iData)
     returns the list of all available optimizers and fit functions.
  fits(iData)
     displays the list of all available optimizers and fit functions.
  You may create new fit models with the 'ifitmakefunc' tool.

  When the iData object contains 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'   % 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:  a: object or array (iData)
           when given as an empty iData, the list of optimizers and fit models
             is shown.
         model: model function (char/iFunc/function handle)
           the model is converted into an iFunc object, with 'p' as parameters
           and 'x,y,...' as axes (1st axis 'x' refers to rows, 'y' to columns)
             from a string:       'signal = expression(p, x,y,...);'
                                  'expression(p, x,y,...)' 
             from function handle: @(p,x,..)expression or @function(p,x,...)
           when set to empty, the 'gauss' 1D function is used (and possibly extended to multidimensional).
         pars: initial model parameters (double array). 
           when set to empty 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 'fminsearch' (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
             Function called at each iteration as outfun(pars, optimValues, state)
             The 'fminplot' function 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=...' to define the structure

 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:        Last model evaluation (iData)
           parsHistoryUncertainty: Uncertainty on the parameters obtained from 
                              the optimization trajectory (double)

 ex:     a=iData('sv1850.scn'); p=fits(a,'','','fminpowell');
         o=fminpowell('defaults'); o.OutputFcn='fminplot'; 
         [p,c,m,o]=fits(a,'gauss',p,o); b=o.modelValue; figure; plot(a,b)

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

CROSS-REFERENCE INFORMATION ^

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