iFit: iFuncs fit models


  1. How to use models
  2. List of default fit models
  3. The list of all available fit functions can be obtained from the command:
  4. Model builder: making a model easy
    1. Creating complex functions from simple functions
    2. Using signal convolution/correlation in new functions
  5. How to write manually a model function


Commands we use in this page: fits, ifitmakefunc, fits(iData)

How to use models

Models are numerical functions, that take input axes and a parameter set, and return a function evaluation.

Such models are used in iFit when there is a need to e.g. compute and plot a function evaluation corresponding with the axes of an iData obect by means of the ieval function. Similarly, this function evluation can be used iteratively in an optimization process in order to find a parameter set that matches best the iData object Signal, using the fits method. All these are explained in the Fit page.

Each function/model can be used in the following ways (for instance model may be 'gauss'):
>> model		% display model informations
>> model('identify') % idem
>> model('plot') % plot the model with its default settings
>> model(p, x, y ...) % evaluate the model with parameters p, and axes x,y,...
>>
model([], x, y ...) % evaluate the model with axes x,y,... and automatic parameter guess
>> model('guess', x, y ...) % idem
>> ieval(a, @model, p) % evaluate the model onto the iData object axes with parameters p
>>
fits(a, @model, p) % fit the model onto the iData object

List of default fit models


Function
Description
Dimensionality
Parameters
allometric
Allometric (power/asymptotic law)
1D
Amplitude Offset Exponent BackGround
bigauss
Asymmetric Gaussian
1D Amplitude Centre HalfWidth1 HalfWidth2 Background
bilorz
Asymmetric Lorentzian
1D Amplitude Centre HalfWidth1 HalfWidth2 Background
bose Bose factor
1D Tau [h/2pi/kT] in "x" units
dho
Damped harmonic oscillator
1D Amplitude Centre HalfWidth Background Temperature (in "x" unit)
dirac
Dirac peak
1D
Amplitude Centre
doseresp
Dose-response curve with variable Hill slope
1D
Amplitude Center Slope BackGround
expon
Exponential decay
1D
Amplitude Tau Background
expstretched
Exponential - Stretched
1D
Amplitude Tau Exponent Background
gauss Gaussian
1D Amplitude Centre HalfWidth Background
green
Green function
1D
Amplitude Centre HalfWidth Background
heaviside
Heaviside (gap)
1D
Amplitude Centre FulfWidth Background
langevin
Langevin function for magnetic polarization
1D
Amplitude Center Width BackGround
laplace
Laplace distribution function
1D
Amplitude Center Width BackGround
lognormal
Log-Normal distribution
1D
Amplitude Center Width BackGround
lorz
Lorentzian
1D Amplitude Centre HalfWidth Background
pareto
Pareto distribution function
1D
Amplitude Exponent Width BackGround
poisson
Poisson distribution
WARNING: The 'x' axis is assumed to be an integer array (counts)
1D
Amplitude Center BackGround
quadline
Quadratic line
1D
Quadratic Linear Constant
sine
Sine function
1D
Amplitude Phase_Shift Period BackGround
sinedamp
Damped Sine function (exponential decay)
1D
Amplitude Phase_Shift Period BackGround Decay
strline
Straight line
1D
Gradient Background
triangl
Triangular
1D Amplitude Centre HalfWidth Background
voigt
Voigt function
1D
Amplitude Centre HalfWidth_Gauss HalfWidth_Lorz Background

iFit: default functions (in iFuncs)
The list of all available fit functions can be obtained from the command:
>> fits(iData);
which also prodices the plot above.

Model builder: making a model easy

The ifitmakefunc tool enables to define a new fit function/model from a simple dialog, by entering its ifitmakefuncexpression as a function of the parameter vector p and the axes x,y,z,...
>> h=ifitmakefunc;
The only required argument is the expression, but you may as well  enter a function name and description, parameter names and default values, as well as a constraint to be evaluated before computing the function value. When started without any parameters, the Gaussian function settings are used.

The function both creates a function file, and returns its function handle, that may be used with ieval anf fits.
>> [p,criteria,message,output]= fits(a, h);
A quick definition, without using the dialog, can be performed with the syntax:
>> h=ifitmakefunc('p(1)*exp( (x-p(2))/p(3) )');
>> fits(a, h);
where  p is the vector that holds parameters. Axes are x (rows),y (columns),z (pages),t (time).
The full syntax for the model builder is:
>> h=ifitmakefunc('expression');
>> h=ifitmakefunc('expression', 'constraints');
>> h=ifitmakefunc('function_name', 'description', 'Parameter1 Parameter2 ...', ...
'expression', [default parameter values], 'constraint');
which is equivalent to:
>> fun.function='function_name';			% function name
>> fun.Description='function description'; % function long description
>> fun.Parameters='Parameter1 Parameter2 ...'; % parameter names. When empty, names are given according to the Expression analysis (when appropriate)
>> fun.Guess=[0 1 2 ...] or 'automatic'; % parameter default values (vector), or automatic mode
>> fun.Expression='expression using p and x,y,z,t...'; % value of the model (required). p is the vector that holds parameters. Axes are x,y,z,t.
>> fun.Constraint='evaluated before Expression'; % constraint evaluated prior to the model Expression
>> h=ifitmakefunc(fun);
>>
fits(a, h);
The gerenated code will basically be:
function y=[fun.function](p, axes, ...)
% [fun.Description]
% Parameters: [fun.Parameters]
[fun.Constraint];
y=[fun.Expression];
The resulting function has the ability to identify itself ('identify', provide detailed informations), compute automatic starting parameters ('guess'), display itself ('plot'), and evaluate its value of course. The resulting function embeds the automatic guess functionality (iFuncs_private_guess), and thus can be stored anywhere in the Matlab search path, but should better be in the iFit/iFuncs directory so that it appears in the fits(iData) function list.

Creating complex functions from simple functions

To assemble existing functions into new ones, you may use e.g.:
>> h=ifitmakefunc('gausslorz', ...
'Gaussian+Lorentzian function'
, ...
'Amplitude1 Centre1 HalfWidth1 Background1
Amplitude2 Centre2 HalfWidth2 Background2', ...
'gauss(p(1:4),x)+lorz(p(5:8),x)', ...
'automatic', 'p(8)=0');

ifitmakefunc: Wrote function signal=gausslorz(p, x)
% Gaussian+Lorentzian function
% 8 parameter(s): 'Amplitude1' 'Centre1' 'HalfWidth1' 'Background1' 'Amplitude2' 'Centre2' 'HalfWidth2' 'Background2'
p(8)=0;
signal=gauss(p(1:4),x)+lorz(p(5:8),x);

Stored in: /home/farhi/gausslorz.m
which creates a new function which is the sum of a Gaussian and a Lorentzian. The second redundant Lorentzian Background p(8) parameter is forced to 0 so that it does not correlate with the Gaussian Background p(4). The function has all the features listed above (plot/identify/guess).

A simpler equivalent syntax is
>> h=ifitmakefunc('gauss(p(1:4),x)+lorz(p(5:8),x)', 'p(8)=0');
where unspecified arguments are guessed/automatically set.

Using signal convolution/correlation in new functions

It is possible to include a convolution (FFT based, multidimensional) in the core of the new function. The two function fconv and fconvn should then be used with the following syntax, where a and b are vectors/matrices:
>> c = fconv(a,b);		% returned convoluted object with size which is size(a)+size(b)+1
>> c = fconv(a,b, 'same'); % returned convoluted object with size which is size(a)
>> c = fconv(a,b, 'valid'); % returned convoluted object with size which is size(a)-size(b)+1
>> c = fconv(a,b, 'pad'); % pads 'a' with starting/ending values to minimize border effects
>> c = fconv(a,b, 'center'); % centers 'b' so that convolution does not shift 'a'
>> c = fconv(a,b, 'norm'); % normalizes 'b' so that convolution does not change 'a' integral
>> c = fconv(a,b, 'background');% subtracts minimal value in 'b' so that convolution does not change 'a' integral
>> c = fconv(a,b, 'deconv'); % deconvolution, but very sensitive to noise (use with caution)
When some data has to be convoluted with a response function (e.g. instrument resolution function), the usual options to use should be:
>> c = fconv(a,b, 'same pad background center norm');
>> c = fconvn(a,b); % same as above in a shorter call
Using fconvn, we may assemble a new function as:
>> global b;	% holds the convolution function as a single vector/matrix or iData object
>> h = ifitmakefunc('fconvn(gauss(p(1:4),x), double(b))','global b'); % creates a fit function with convolution
where the vector/matrix 'b' holds the response function (filter) with the same axis binning as the object 'a'.
In case the response function can be modeled as a function, you may use e.g. :
>> h = ifitmakefunc('fconvn(lorz(p(1:4),x)+dho(p(5:9),x), gauss(p(10:13),x))');
which in this example as a Lorentizian plus a DHO convolved with a Gaussian. In order for iFit to be able to guess starting parameters, you may need to specify manually the parameter names for that function, such as in:
>> h = ifitmakefunc('conv_lorzdho_gauss', ...						% name of the function
'conv(Lorz+DHO, Gauss)
', ... % description
[ 'Lorz_Amplitude Lorz_Centre Lorz_HalfWidth Lorz_Background ' ... % Parameter names
'DHO_Amplitude DHO_Centre DHO_HalfWidth DHO_Background DHO_Temperature ' ...
'Gauss_Amplitude Gauss_Centre Gauss_HalfWidth Gauss_Background' ], ...
'fconvn(lorz(p(1:4),x)+dho(p(5:9),x), gauss(p(10:13),x))'); % expression
Instead of the convolution, the correlation can also be computed using the function fxcorr similarly as fconv.

How to write manually a model function

We suggest that you start from the 'gauss' function in iFit/iFuncs, and customize at will. Please retain the function core structure to ensure proper execution. Store the new function in iFit/iFuncs so that it can access the automatic guess functionality (iFuncs_private_guess). A template function also exists in iFit/iFuncs/private/template.txt.


E. Farhi - iFit/fit models - $Date: 2011-09-22 14:31:19 $ $Revision: 1.16 $ - back to Main iFit Page ILL, Grenoble, France <www.ill.eu>