MF_linfit MD_linfit ME_linfit
MF_linfitwW MD_linfitwW ME_linfitwW
FunctionData-fitting to models z=f(x, y) linear in the parameters
Syntax C/C++#include <MFstd.h>
int MF_linfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, ui htZ, ui lenZ,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int MF_linfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, fMatrix InvVar, ui htZ, ui lenZ,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int MF_linfitwEdit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, ui htZ, ui lenZ, float thresh,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int MF_linfitwWwEdit( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, fMatrix InvVar, ui htZ, ui lenZ, float thresh,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
C++ MatObj#include <OptiVec.h>
int vector<T>::linfit( const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int vector<T>::linfitwW( matrix<T> Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int vector<T>::linfitwW( matrix<T>* Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int vector<T>::linfitwEdit( const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const T thresh,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int vector<T>::linfitwWwEdit( matrix<T> Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar, const T thresh,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
 
int vector<T>::linfitwWwEdit( matrix<T>* Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar, const T thresh,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
Pascal/Delphiuses MFstd;
function MF_linfit( A:fVector; AStatus:iVector; npars:UInt; X, Y:fVector; MZ:fMatrix; htZ, lenZ:UIntSize; funcs:Pointer ): IntBool;
 
function MF_linfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; npars:UInt; X, Y:fVector; MZ, MInvVar:fMatrix; htZ, lenZ:UIntSize; funcs:Pointer ): IntBool;
 
function MF_linfitwEdit( A:fVector; AStatus:iVector; npars:UInt; X, Y:fVector; MZ:fMatrix; htZ, lenZ:UIntSize; thresh:Single; funcs:Pointer ): IntBool;
 
function MF_linfitwWwEdit( A:fVector; Covar:fMatrix; AStatus:iVector; npars:UInt; X, Y:fVector; MZ, MInvVar:fMatrix; htZ, lenZ:UIntSize; thresh:Single; funcs:Pointer ): IntBool;
DescriptionThe input data X, Y, MZ (and MInvVar) are used to evaluate the parameters ai of a general linear function,
z = a0f0(x, y) + a1f1(x, y) + a2f2(x, y)...
The parameters ai are returned in the vector A.

Arguments:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients.
If the covariances are not needed, one may call the function with Covar=NULL / nil.
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
X, Yvectors of size lenZ and htZ, respectively, spanning the x-y coordinate system of the matrix MZ
MZ, MInvVarmatrices of dimensions [htZ, lenZ], holding the input data and, in the weighted variant, the inverse of their variances
funcsuser-defined model function
 
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide the vector AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling MF_linfit. npars denotes the total number of parameters in A (not only the free parameters!).

You must provide a model function "funcs" which, for any pair of arguments x, y, must calculate the individual fi(x, y) and store them in a vector BasFuncs of size npars. In C/C++, it has to be defined as
void MyFunc( fVector BasFuncs, float x, float y, unsigned nfuncs);
{
  BasFuncs[0] = f0( x, y );
  BasFuncs[1] = f1( x, y);
  . . .
}

and shall be passed to MF_linfit by calling
MF_linfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, MyFunc );
In Pascal/Delphi, the model function has to be defined as
procedure MyFunc( BasFuncs:fVector; x, y:Single; nfuncs:UInt );
begin
  VF_Pelement( BasFuncs, 0 )^ := f0( x, y );
  VF_Pelement( BasFuncs, 1 )^ := f1( x, y );
  . . .
end;

and shall be passed to MF_linfit by calling
MF_linfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, @MyFunc );
Note the address-of operator in front of "MyFunc.". In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}.

The functions f0( x, y ) etc. must not contain the parameters ai.
In the weighted variant, MF_linfitwW, the matirx MInvVar has to contain the inverse of the variances of the individual X-Y-Z data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).

Internally, MF_linfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. The default threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect. As VF_setLinfitNeglect is not thread-safe, this function should not be used to set different thresholds for different calls to VF / MF_linfit etc. Rather than repeatedly changing the default value, use the "wEdit" variants of VF / MF_linfit, namely MF_linfitwEdit, MF_linfitwWwEdit etc.

In the rare case of failure, this function returns 1 (TRUE) and sets all A[i] = 0.

Return valueFALSE (0), if no error occurred, otherwise TRUE (non-zero).
See alsoVF_linfit,   MF_nonlinfit,   chapter 13,  FITDEMO*.*

MatrixLib Table of Contents  OptiVec home