Home > Objects > @iFunc > iFunc.m



model = iFunc(...): create a fit model function


function a = iFunc(varargin)


 model = iFunc(...): create a fit model function

 Any Fit Model function can be created from a mathematical expression, a
 structure, a function handle or an other object.

 The model can store the following information members:
   Expression:       The expression for the function (string) or function handle
                       signal=Expression(p, x,y, ...)
                         The parameter names surrounded by "" are replaced
                         by the corresponing p(n)
                       the iFunc object itself is named 'this' in the Expression
   Guess:            Vector, expression or function to evaluate in order to obtain
                       guessed parameters from axes x,y,z, ... and signal
                       p=Guess(x,y,z, ..., signal) should return a vector. NaN values 
                       are not set.
   Name:             A short name for the function
   ParameterValues:  Some parameter values to be used e.g. as starting parameters
                       for a fit procedure or a plot
   Description:      A string describing the model
   Parameters:       The Parameter names (cellstr)
   Constraint:       An expression or a function handle with syntax 
                       p=Constraint(p, x,y,...). NaN values are not changed.
                     The Constraint may also be defined as a structure with
                       min: a vector of minimal values per parameter
                       max: a vector of maximal values per parameter
                       fixed: a vector of 0(free) and 1(fixed) per parameter
                       set: a cell of expressions per parameter
                       Expression: an Expression to be evaluated
                         The parameter names surrounded by "" are replaced
                         by the corresponing p(n)

 Creating the object:
   From a character string
     the Expression should make use of x,y,z,t,u,v,w to denote axes of rank 1-7,
     and the model Parameters are specified using 'p(n)' vector elements.

   From a structure, with iFunc object fields (see above) and alias fields:
     x0          -> Guess
     objective   -> Expression
     pars        -> Parameters
     function    -> Name

   From a function handle
     The function should have syntax model(p, x,y,...) and return the model value.
       iFunc(@(p,x) p(1)*x+p(2))

   From a script/function 
     The file should use 'p' as adjustable parameters, and optionally axes 'x', 'y', ...

   From a SpinW object

   From a file in MAT, M, YAML, JSON, XML format holding a model (iFunc/save)
       iFunc('filename_model'). See iFunc/save

   From a data set (iData) or data file
       iFunc(iData('filename')); parameters allow to scale and shift.

 Using the object:
   Once the object has been created, you can evaluate it with: object(p, x, y, ...)
   The usual mathematical operators can be used to manipulate iFunc objects.
   You can use guessed Model parameters with syntax: object('guess', x,y, ...)

   The syntax iFunc(iData object) evaluates the iFunc model using the iData
     object axes, and returns the model value as a numerical array. To get the
     result as an iData, use syntax iData(iFunc object) [the opposite syntax].

   The Model expression is               object.Expression
   The Model parameter names are         object.Parameters
   The Model parameter values (when set) object.ParameterValues or object.p
   A single parameter can be accessed    object.<ParameterName> or object.p(index)

 Scan model parameters:
 It is possible to scan model parameters when using vectors as value for the
 parameters. To achieve that, the parameter values must be given as a named 
 For instance, to scan the Intensity parameter in a gaussian, use:
   model = gauss1;
   p.Intensity= [ .5:.25:2 ];      % from 0.5 to 2 by steps of .25
   v=iData(model, p);              % evaluate as iData sets.
   plot(cat(2,v));                 % plot the scan as a surface

 Optimise model parameters:
 To optimise model parameters, you should first fix the non-varying
 parameters, and possibly bound the others. Then the optimisation is launched with
 any optimiser. To maximise the model, use '-model' as argument, as in the example:
   model = gauss1;
   fix(model, 'all'); model.Intensity='free';
   model.Intensity=[0 1 2];    % bounds and starting value
   model.HalfWidth = 0.5;
   p = fmin(-model, [])        % return the optimal parameters to maximise the model

 Type <a href="matlab:doc(iFunc)">doc(iFunc)</a> to access the iFit/iFunc Documentation.
 iFunc is part of iFit http://ifit.mccode.org 
 input:  s: iFunc, string, structure, function handle, spinw
 output: b: model object (iFunc)
 ex:     b=iFunc(@(p,x) p(1)*x+p(2)); 
         plot(x, b(p, x))
         b.p=p; plot(b)

 Version: Aug. 22, 2017
 See also iFunc, iFunc/feval, iFunc/plot, iFunc/fits, iFunc/save, methods
 (c) E.Farhi, ILL. License: EUPL.


This function calls: This function is called by:
Generated on Tue 22-Aug-2017 11:03:30 by m2html © 2005. iFit (c) E.Farhi/ILL EUPL 1.1