Fit a model for S(Q,w) to an sqw object, with an optional background function.
If passed an array of sqw objects, then each object is fitted independently.
Differs from multifit_sqw, which fits all objects in the array simultaneously
but with independent backgrounds.
Fit several objects in succession to a given function:
>> [wout, fitdata] = fit_sqw (w, func, pin) % all parameters free
>> [wout, fitdata] = fit_sqw (w, func, pin, pfree) % selected parameters free to fit
>> [wout, fitdata] = fit_sqw (w, func, pin, pfree, pbind) % binding of various parameters in fixed ratios
With optional 'background' function added to the function
>> [wout, fitdata] = fit_sqw (..., bkdfunc, bpin)
>> [wout, fitdata] = fit_sqw (..., bkdfunc, bpin, bpfree)
>> [wout, fitdata] = fit_sqw (..., bkdfunc, bpin, bpfree, bpbind)
If unable to fit, then the program will halt and display an error message.
To return if unable to fit, call with additional arguments that return status and error message:
>> [wout, fitdata, ok, mess] = fit_sqw (...)
Additional keywords controlling which ranges to keep, remove from objects, control fitting algorithm etc.
>> [wout, fitdata] = fit_sqw (..., keyword, value, ...)
Keywords are:
'keep' range of x values to keep
'remove' range of x values to remove
'mask' logical mask array (true for those points to keep)
'select' if present, calculate output function only at the points retained for fitting
'list' indicates verbosity of output during fitting
'fit' alter convergence critera for the fit etc.
'evaluate' evaluate function at initial parameter values only, with argument check as well
'chisqr' evaluate chi-squared at the initial parameter values (ignored if 'evaluate' not set)
'average' compute the function at the average h,k,l,e of the pixels in a bin
Example:
>> [wout, fitdata] = fit_sqw (..., 'keep', xkeep, 'list', 0)
Input:
======
win sqw object or array of sqw objects to be fitted
sqwfunc Handle to function that calculates S(Q,w)
Most commonly used form is:
weight = sqwfunc (qh,qk,ql,en,p)
where
qh,qk,ql,en Arrays containing the coordinates of a set of points
p Vector of parameters needed by dispersion function
e.g. [A,js,gam] as intensity, exchange, lifetime
weight Array containing calculated energies; if more than
one dispersion relation, then a cell array of arrays
More general form is:
weight = sqwfunc (qh,qk,ql,en,p,c1,c2,..)
where
p Typically a vector of parameters that we might want
to fit in a least-squares algorithm
c1,c2,... Other constant parameters e.g. file name for look-up
table
pin Initial function parameter values
- If the function my_function takes just a numeric array of parameters, p, then this
contains the initial values [pin(1), pin(2)...]
- If further parameters are needed by the function, then wrap as a cell array
{[pin(1), pin(2)...], c1, c2, ...}
pfree [Optional] Indicates which are the free parameters in the fit
e.g. [1,0,1,0,0] indicates first and third are free
Default: all are free
pbind [Optional] Cell array that indicates which of the free parameters are bound to other parameters
in a fixed ratio determined by the initial parameter values contained in pin:
pbind={1,3} parameter 1 is bound to parameter 3.
pbind={{1,3},{4,3},{5,6}} parameter 1 bound to 3, 4 bound to 3, and 5 bound to 6
In this case, parmaeters 1,3,4,5,6 must all be free in pfree.
To explicity give the ratio, ignoring that determined from pin:
pbind=(1,3,0,7.4) parameter 1 is bound to parameter 3, ratio 7.4 (the extra '0' is required)
pbind={{1,3,0,7.4},{4,3,0,0.023},{5,6}}
To bind to background parameters (see below), use the function index unity:
pbind={1,3,1} Parameter 1 bound to background parameter 3
pbind={1,3,1,3.14} Give explicit binding ratio.
Optional background function:
--------------------------------
bkdfunc Handle to background function
The background function is assumed to be defined by the axes x1,x2,...xn (n=number of dimensions).
Must have form:
y = my_function (x1,x2,... ,xn,p)
or, more generally:
y = my_function (x1,x2,... ,xn,p,c1,c2,...)
- x1,x2,.xn Arrays of x coordinates along each of the n dimensions
- p a vector of numeric parameters that can be fitted
- c1,c2,... any further arguments needed by the function e.g.
they could be the filenames of lookup tables for
resolution effects)
e.g. Two dimensional Gaussian:
function y = gauss2d(x1,x2,p)
y = p(1).*exp(-0.5*(((x1 - p(2))/p(4)).^2+((x2 - p(3))/p(5)).^2);
bpin Initial function parameter values
- If the function my_function takes just a numeric array of parameters, bp, then this
contains the initial values [bpin(1), bpin(2)...]
- If further parameters are needed by the function, then wrap as a cell array
{[bpin(1), bpin(2)...], c1, c2, ...}
bpfree [Optional] Indicates which are the free parameters in the fit
e.g. [1,0,1,0,0] indicates first and third are free
Default: all are free
bpbind [Optional] Cell array that indicates which of the free parameters are bound to other parameters
Examples of a single binding description:
{1,4} Background parameter (bp) 1 is bound to bp 3, with the fixed
ratio determined by the initial values
{5,11,0} Bp 5 bound to parameter 11 of the foreground fitting function, func
{5,11,1} Bp 5 bound to parameter 11 of the background function
{5,11,0,0.013} Explicit ratio for binding bp 5 to parameter 11 of the foreground fitting function
{1,4,1,14.15} Explicit ratio for binding bp 1 to bp 4 of background function
Several binding descriptions:
{{1,3},{2,4,0,1.2},{5,11,1}}
Optional keywords:
------------------
'list' Numeric code to control output to Matlab command window to monitor
status of fit
=0 for no printing to command window
=1 prints iteration summary to command window
=2 additionally prints parameter values at each iteration
'fit' Array of fit control parameters
fcp(1) relative step length for calculation of partial derivatives
fcp(2) maximum number of iterations
fcp(3) Stopping criterion: relative change in chi-squared
i.e. stops if chisqr_new-chisqr_old < fcp(3)*chisqr_old
'keep' Ranges of data to retain for fitting. A range is specified by two
pairs of numbers which define a rectangle:
[xlo, xhi, ylo, yhi]
Several ranges can be defined by making an (m x 4) array:
[xlo(1), xhi(1), ylo(1), yhi(1); xlo(2), xhi(2), ylo(2), yhi(2); ...]
'remove' Ranges to remove from fitting. Follows the same format as 'keep'.
'mask' Array of ones and zeros, with the same number of elements as the data
array, that indicates which of the data points are to be retained for
fitting
'select' Calculates the returned function values, yout, only at the points
that were selected for fitting by 'keep' and 'remove'; all other
points are set to NaN. This is useful for plotting the output, as
only those points that contributed to the fit will be plotted.
A final useful set of keyword is:
'evaluate' Evaluate the fitting function at the initial parameter values only. Useful for
checking the validity of starting parameters.
'chisqr' If 'evaulate' is set, then if this option keyword is present the reduced
chi-squared is evaluated. Otherewise, chi-squared is set to zero.
'average' if sqw object, then compute the function at the average h,k,l,e of the
pixels contributing to each bin, rather than for each pixel. This can
save a lot of computation
Output:
=======
wout Array or cell array of the objects evaluated at the fitted parameter values
If there was a problem for ith data set i.e. ok(i)==false, then wout(i)==w(i) (or wout{i}
=[] if cell array input).
If there was a fundamental problem e.g. incorrect input argument
syntax, then fitdata=[].
fitdata Result of fit for each dataset
fitdata.p - parameter values
fitdata.sig - estimated errors of foreground parameters (=0 for fixed parameters)
fitdata.bp - background parameter values
fitdata.bsig - estimated errors of background (=0 for fixed parameters)
fitdata.corr - correlation matrix for free parameters
fitdata.chisq - reduced Chi^2 of fit (i.e. divided by
(no. of data points) - (no. free parameters))
fitdata.pnames - parameter names
fitdata.bpnames- background parameter names
If there was a problem for ith data set i.e. ok(i)==false, then fitdata(i)
will be dummy.
If there was a fundamental problem e.g. incorrect input argumnet syntax, then
fitdata=[].
ok True if all ok, false if problem fitting.
If an array of input datasets was given, then ok is an array with the size of the
input data array.
If the error was fundamental e.g. wrong argument syntax, then ok will be a scalar.
mess Character string contaoning error message if ~ok; '' if ok
If an array of datasets was given, then mess is a cell array of strings with the
same size as the input data array.
If the error was fundamental e.g. wrong argument syntax, then
mess will be a simple character string.
EXAMPLES:
Fit a spin waves to a collection of sqw objects, allowing only intensity and coupling constant to vary:
>> weight=100; SJ; gamma=3;
>> [wfit, fdata] = fit_sqw (w, @bcc_damped_spinwaves, [ht,SJ,gamma], [1,1,0])
If an array of 1D cuts: allow all parameters to vary, only keep data in restricted range, and allow
independent linear background for each cut in the units of the x axis:
>> weight=100; SJ; gamma=3;
>> const=0; slope=0;
>> [wfit, fdata] = fit_sqw (w, @bcc_damped_spinwaves, [ht,SJ,gamma], @linear, [const,slope]...
'keep',[-1.5,0.5])
% Overloaded methods:
sqw/fit_sqw
sqw/fit_sqw
d4d/fit_sqw
d3d/fit_sqw
d2d/fit_sqw
d1d/fit_sqw
d0d/fit_sqw