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

The 1D functions are signal=f(parameters, x), and the 2D functions are signal=f(parameters, x, y).

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. This is a sigmoid or S-shaped.
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)
The GapSide indicates raising (+) or falling (-) gap.
1D
Amplitude Centre GapSide 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
pseudovoigt
Pseudo Voigt
1D
Amplitude Center Width BackGround LorentzianRatio
quadline
Quadratic line (parabola)
1D
Quadratic Linear Constant
sigmoid
Sigmoidal S-shaped curve (similar to Dose Response)
1D Amplitude Center Width BackGround
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
tophat
Top-Hat rectangular function
1D Amplitude Centre HalfWidth Background
twoexp
Two exponential decay functions
1D Amplitude1 Tau1 Amplitude2 Tau2 Background
voigt
Voigt function
1D
Amplitude Centre HalfWidth_Gauss HalfWidth_Lorz Background
gauss2d
Gaussian function with tilt angle
2D
Amplitude Centre_X Center_Y HalfWidth_X HalfWidth_Y Angle Background
lorz2d
Lorentzian function with tilt angle 2D Amplitude Centre_X Center_Y HalfWidth_X HalfWidth_Y Angle Background
plane2d
Planar function
2D Slope_X Slope_Y Background
pseudovoigt2d
Pseudo Voigt with tilt angle 2D Amplitude Centre_X Center_Y HalfWidth_X HalfWidth_Y Angle Background LorentzianRatio
quad2d
Quadratic (parabola) with tilt angle 2D Amplitude Centre_X Center_Y Curvature_X Curvature_Y Angle 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 and 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 letter parameters a,b,c ... o can be used in place of p(1), p(2), ... Beware to use a model expression with element-wise division and multiplication operators (./ and .*). The function builder is known to work well for 1D and 2D functions.

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 generated 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.

A large set of 1D (vector) and 2D (surface) models can be obtained from ZunZun.com.

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.

Warning: The fconv and fxcorr functions require the x axis not to be coarsely sampled. In case the initial data contains peaks described with few points underneath (e.g. less than 5), the fit model above will fail convolving. One solution is to artificially create a finer sampled axis, evaluate the function, and reduce back to the initial number of points. The constraints are used to define the new finer axis xx, and the final result is re-sampled with 1 point out of 5 :
>> h = ifitmakefunc('fconvn(lorz(p(1:4),xx)+dho(p(5:9),xx), gauss(p(10:13),xx)); signal=signal(1:5:end);', ...
'xx=linspace(min(x),max(x), 5*length(x));'
);

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: 2012-02-13 20:13:12 $ $Revision: 1.22 $ - back to Main iFit Page ILL, Grenoble, France <www.ill.eu>