Home > Objects > @iData > fits.m



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


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


 [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.
     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
  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'   % 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:  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).
             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 '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
             Minimization criteria. Default is 'least_square' (char/function handle)
             the syntax for evaluating the criteria is criteria(Signal, Error, Model)
             Function called at each iteration as outfun(pars, optimValues, state)
             The 'fminplot' function 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=...' to define the structure

         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


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