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.
iFunc('p(1)*x+p(2)');
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
iFunc(sw_model('squareAF',2,0))
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
structure.
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));
b=iFunc('p(1)*x+p(2)');
b=iFunc('signal=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.