The iFunc class is a
structure which holds a multi-parameter model,to be used for e.g.
plot or fit onto a data set. Models can be assembled using standard
Matlab operators. There exist a set of pre-defined Models, which you can assemble to define
more complex ones. You can also Fit an iFunc
model onto an iData object (containing
e.g. some experimental data).

Creating and inquiring iFunc models
(iFunc, get, plot, subplot)

A model object holds an
Expression (to compute the model value), a list of parameter names,
a Guess expression to compute parameter value estimates, as well as
other MetaData just as for iData objects.

To create a model (i.e. instantiate a class into an object), specify
its Expression, using

Any expression can be entered, and an analysis of the parameters
results in default parameter names.

It is also possible to create a model out of an iData (data set) object. Then, the model
parameters are the total intensity scaling, as well as an offset and
a scaling factor per axis. In order to create a model from a data
file, use:

>> iFunc(iData('filename'))

will create a data set object and derive a model out of it.

You can then display the full content of the object with the disp or get methods :

A graphical representation of the model is obtained using the plot method.

Properties of the model can be obtained with the get method, or with
direct indexing :

>> get(a, 'Expression')>> a.Expressionans =

signal = p(1)*x+p(2);

The Expression can be a
character string returning the
'signal' as a function of the parameters 'p' and axes x,y,z,t,u,v,w
It can also be given as a function handle signal=@Expression(p, x,y, ...), which usually
makes the model evaluation much faster.

>> a=iFunc(@(p,x)p(1)*x+p(2))

Additional arguments (above the model dimensionality) are usable in
the Expression as 'varargin' cell.
The name of the parameters can be changed by accessing the Parameters property (this is a
cell of strings) :

>> a.Parameters = {'Slope','Constant'}

The ParameterValues
property holds the last parameter values (e.g. when returned from a
fit or a function evaluation).
The Guess property should
return a vector of parameter values
'p' as a function of the axes x,y,z... and a signal.
This is a character string, vector or a function handle p=@Guess(x,y,z, ..., signal).
Values of the parameters left as NaN
indicate that the automatic guess procedure should be used (which is
based upon a signal peak search, and baseline analysis). The Guess
is used when starting a fit procedure for starting parameters.
Last, the Constraint
property holds any script to change the parameter values (character
string modifying 'p') from
axes x,y,z,... or a
function handle p=@Constraint(p,
x,y,...). See below on how
to define Constraints.

To print out the equivalent functionf(p, x, ...)
from an object, convert it to a char or cellstr:

>> a=iFunc('p(1)*x+p(2)')>> char(a)>> cellstr(a)

Last, it is possible to define an empty iFunc object, and fill it
with Parameters and any Expression, even without actually any
mathematical model:

This way, it is possible to define any Matlab function inside an
iFunc object. The cell 'varargin' then contains the arguments 2-end,
while 'p' contains the first argument.

>> a(1,2,3)ans = 2 3

Accessing or
modifying parameter values

Parameters from a model can be accessed in many equivalent ways.
If 'a' is an iFunc model
:

>> a.Parameters % lists all parameter names>> get(a) % display the model description, with the list of parameter names and last evaluated values>> a.p % returns a vector of parameter values>> a.ParameterValues % same as above, last evaluated parameter values

If, for instance, the model has an 'Slope' parameter, you can get specifically
its value with :

>> a.Slope % display the value of the 'Slope' parameter

Alternatively, it is possible to modify parameter values :

>> a.p(1) = 2;>> a.Slope = 2;

Defining a new model

To define a new model with a
dialogue window, use:

>> edit(iFunc)

Refer to the dedicated help on this topic in
the Models page, which also lists
pre-defined models (Gaussian, Lorentzian, exponential, lines,
quadratic, ...). Edit their code to see how to define new models:

where parameters can be a numerical vector, or a structure with
named parameters matching the model ones, x,y,z,t,u,v,w are
axes values for ranks 1,2,3... Additional arguments (above the model
dimensionality) are usable in the Expression as 'varargin' cell.

When the parameters are specified as empty ( [] ), current parameter
values are used, or guessed. These parameters can also be given as a
vector corresponding to the model parameter order, a string such as
'Intensity=1; Width=.5', a structure
with named fields and values such as:

p.Intensity=1;

p.Width=0.5;

model(p)

The evaluation of a model with a set of parameters is obtained by
calling the feval
function with the parameter values, or sending these values directly
to the object :

In this case, tentative axes are computed from the model definition.
Axes can also be passed as additional arguments for x,y,z,... either as separate
arguments, as a cell array {x,y,...}, as a structure, or as an iData object which axes are used.

It is also possible to evaluate the model while scanning
parameters. To achieve that, the parameter values must be
given as a named structure, or as a string such as 'Intensity=[ .5 1 1.5 2 ];'

For instance, to scan the Intensity parameter in a Gaussian,
and get the model value as an array of data sets, 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. To only get the values, use feval(model,p)

plot(cat(2,v)); % plot the scan as a surface

Scans with multiple parameters vectors can be performed the same
way.

Setting
and removing constraints on models

Models are often used for fitting purposes (refer to the Fit help page).

To set a constraint on a model parameter, define the 'constraint'
input argument when calling fits (see Fit)
or set the constraint directly on the model parameters with:

>> model.parameter='fix'% to lock its value during a fit process. Same as mlock>> model.parameter='clear'% or 'free' to unlock value during a fit process. Same as munlock
>> model.parameter=[min max] % to bound value>> model.parameter=[min value max] % to bound the parameter and set its value>> model.parameter=[nan nan] % to remove bound constraint>> model.parameter=''% to remove all constraints on 'parameter'>> model.parameter='expression'% to set the parameter from an expression which can use 'p(n)' for other parameters>> model.Constraint=''% to remove all constraints>> model.Constraint = 0; % to unlock/free all Parameters during a fit process>> model.Constraint = 1; % to lock/fix all Parameters during a fit process

Any parameter name surrounded by double quotes, e.g. "Amplitude", is replaced by the
corresponding p(n) value
in an expression used for setting a parameter value
(cross-constraints). For instance

which return the number of parameters in each category. This is also
displayed when using:

>> disp(f)

Under the hood, the constraints are stored as a structure with
fields min, max, fixed, set
(with one expression per parameter), and eval (to be evaluated before the object
Expression).

Saving objects for further re-use: save,
saveas

Once you have created an manipulated a model, it is possible to
export it into a file so that you can re-use it latter. To do so,
use saveas(object, ...)
similarly as when saving iData objects. 'save' is equivalent to saveas.

>> a=iFunc('p(1)*x+p(2)') + gauss ;>> saveas(a); % save as a Matlab m-file function, file name is automatically set to the model iD>> saveas(a, '', 'mat') % same, with a 'mat' file>> save(a, 'model.mat') % same, with a 'mat' file, specifying the file name

The supported export formats are [ as listed with saveas(iFunc,'formats') ]:

The element-wise times(.*), divide(./) and power(.^) operators apply
the operation along the model dimensions, with parallel axes.
The matrix-operators mtimes(*), mrdivide(/) and
mpower(^) operator perform orthogonal axes multiplication,
with extension of the model dimensionality.

In binary operations, passing one of the arguments as a string will simply insert the
corresponding code into the model Expression as the argument to the
operator. For instance the following statement appends a zero value
vector to the gauss model
value (axes are x,y,z,...
and parameters values are in p):

>> c = gauss + 'zeros(size(x))'

The addition operator plus (+)
used with a string argument which contains an equal sign'=' or';'character
concatenates the string before/after the Expression of the model. For
instance the following example does the same as above, explicitly
setting the new signal value, and the next one displays a text
before evaluating the model :

Methods generally mimic the Matlab default ones in functionality,
and are also similar to those of the iData
objects (see the Methods page).

Optimising
the iFunc model parameters

It is possible to optimize the model parameter values in order to
minimize or maximize the model value, with the 'fmin' method.
For this, any optimizer can be used, e.g.

>> p = fmin(model)

will use some guessed axes and automatic optimizer choice for the
optimisation. To start the optimization for a given initial
parameter set, use:

>> p = fmin(model, starting_pars)

The starting parameters can be given as a vector, structure or
string such as 'Intensity=1' as
explained above.
When given as a structure or a string, the resulting optimised
parameters are returned as a structure.

You may also set manually the optimizer configuration and axes to
use with:

>> p = fmin(model, starting_pars, options, x,y, ...)

Just as detailed in the Optimizers
documentation, you may specify the 'options' as the name of the
optimizer (then using its default configuration), a string, or a
structure, such as in the following examples:

Similarly to the iData objects, the 'x'
1st rank axis corresponds to rows, 'y' to columns. When the data has
a higher dimensionality as the model, this latter is extended by
orthogonal multiplication to match the data dimensionality. It is
thus possible for instance to fit a 4D data set with the default
'gauss' model, which then results in the creation of the
'gauss*gauss*gauss*gauss' model.

The fit begins from the given starting values, or from guessed
values if entered as empty. Other options
and constraints, as well as
returned arguments, are the same as described in the Fit page. Empty input argument values request
the fit to use default values.

which is an iData object when data is given as an iData. In
this case, fits(iFunc, iData,
...) is equivalent to fits(iData,
iFunc, ...), and you can directly plot the result on top of
the initial data with:

>> plot(data, output.modelValue)

When the data to be fitted is not an iData object, you can plot the
fit result from e.g.