gwynlfit

gwynlfit — Marquardt-Levenberg nonlinear least square fitter

Synopsis




gdouble     (*GwyNLFitFunc)                 (gdouble x,
                                             gint n_param,
                                             const gdouble *param,
                                             gpointer user_data,
                                             gboolean *fres);
void        (*GwyNLFitDerFunc)              (gint i,
                                             const gdouble *x,
                                             gint n_param,
                                             gdouble *param,
                                             GwyNLFitFunc fmarq,
                                             gpointer user_data,
                                             gdouble *deriv,
                                             gboolean *dres);
void        (*GwyNLFitGuessFunc)            (gdouble *x,
                                             gdouble *y,
                                             gint n_dat,
                                             gdouble *param,
                                             gpointer user_data,
                                             gboolean *fres);
void        (*GwyNLFitParamScaleFunc)       (gdouble *param,
                                             gdouble xscale,
                                             gdouble yscale,
                                             gint dir);
void        (*GwyNLFitWeightFunc)           (gdouble *x,
                                             gdouble *y,
                                             gint n_dat,
                                             gdouble *weight,
                                             gpointer user_data);
struct      GwyNLFitter;
struct      GwyNLFitPreset;
struct      GwyNLFitParam;
GwyNLFitter* gwy_math_nlfit_new             (GwyNLFitFunc ff,
                                             GwyNLFitDerFunc df);
void        gwy_math_nlfit_free             (GwyNLFitter *nlfit);
gdouble     gwy_math_nlfit_fit              (GwyNLFitter *nlfit,
                                             gint n_dat,
                                             const gdouble *x,
                                             const gdouble *y,
                                             gint n_param,
                                             gdouble *param,
                                             gpointer user_data);
gdouble     gwy_math_nlfit_fit_full         (GwyNLFitter *nlfit,
                                             gint n_dat,
                                             const gdouble *x,
                                             const gdouble *y,
                                             const gdouble *weight,
                                             gint n_param,
                                             gdouble *param,
                                             const gboolean *fixed_param,
                                             const gint *link_map,
                                             gpointer user_data);
gint        gwy_math_nlfit_get_max_iterations
                                            (GwyNLFitter *nlfit);
void        gwy_math_nlfit_set_max_iterations
                                            (GwyNLFitter *nlfit,
                                             gint maxiter);
gdouble     gwy_math_nlfit_get_dispersion   (GwyNLFitter *nlfit);
gdouble     gwy_math_nlfit_get_correlations (GwyNLFitter *nlfit,
                                             gint par1,
                                             gint par2);
gdouble     gwy_math_nlfit_get_sigma        (GwyNLFitter *nlfit,
                                             gint par);
void        gwy_math_nlfit_derive           (gint i,
                                             const gdouble *x,
                                             gint n_param,
                                             gdouble *param,
                                             GwyNLFitFunc ff,
                                             gpointer user_data,
                                             gdouble *deriv,
                                             gboolean *dres);
gint        gwy_math_nlfit_get_npresets     (void);
GwyNLFitPreset* gwy_math_nlfit_get_preset   (gint preset_id);
GwyNLFitPreset* gwy_math_nlfit_get_preset_by_name
                                            (const gchar *name);
gint        gwy_math_nlfit_get_preset_id    (const GwyNLFitPreset *preset);
gdouble     gwy_math_nlfit_get_preset_value (const GwyNLFitPreset *preset,
                                             gdouble *params,
                                             gdouble x);
gchar*      gwy_math_nlfit_get_preset_name  (const GwyNLFitPreset *preset);
gchar*      gwy_math_nlfit_get_preset_formula
                                            (const GwyNLFitPreset *preset);
gchar*      gwy_math_nlfit_get_preset_param_name
                                            (const GwyNLFitPreset *preset,
                                             gint param);
gdouble     gwy_math_nlfit_get_preset_param_default
                                            (const GwyNLFitPreset *preset,
                                             gint param);
gint        gwy_math_nlfit_get_preset_nparams
                                            (const GwyNLFitPreset *preset);
GwyNLFitter* gwy_math_nlfit_fit_preset      (const GwyNLFitPreset *preset,
                                             gint n_dat,
                                             const gdouble *x,
                                             const gdouble *y,
                                             gint n_param,
                                             gdouble *param,
                                             gdouble *err,
                                             const gboolean *fixed_param,
                                             gpointer user_data);

Description

A new Marquardt-Levenberg nonlinear least square fitter can be created with gwy_math_nlfit_new(), specifying the function to fit (as GwyNLFitFunc) and its derivation (as GwyNLFitDerFunc). For functions for whose analytic derivation is not available or very impractical, gwy_math_nlfit_derive() (computing the derivation numerically) can be used instead.

A fitter can be then repeatedly used on different data either in gwy_math_nlfit_fit(), or gwy_math_nlfit_fit_with_fixed() when there are some fixed parameters. Arbitrary additional (non-fitting) parameters can be passed to the fited function in user_data.

After a successfull fit additional fit information can be obtained with gwy_math_nlfit_get_dispersion(), gwy_math_nlfit_get_correlations(), gwy_math_nlfit_get_sigma(). Note these functions may be used only after a successfull fit. When a fitter is no longer needed, it should be freed with gwy_math_nlfit_free().

Several common functions are also available as fitting presets that can be fitted with gwy_math_nlfit_fit_preset(). Each one can be identified by a unique name or a numeric id (the latter one may however change between releases) the number of presets can be obtained with gwy_math_nlfit_get_npresets(). Preset properties can be obtained with functions like gwy_math_nlfit_get_preset_nparams() or gwy_math_nlfit_get_preset_formula().

Details

GwyNLFitFunc ()

gdouble     (*GwyNLFitFunc)                 (gdouble x,
                                             gint n_param,
                                             const gdouble *param,
                                             gpointer user_data,
                                             gboolean *fres);

Fitting function type.

x : The value to compute the function at.
n_param : The number of parameters (size of param).
param : Parameters.
user_data : User data as passed to gwy_math_nlfit_fit().
fres : Set to TRUE if succeeds, FALSE on failure.
Returns : The value at x.

GwyNLFitDerFunc ()

void        (*GwyNLFitDerFunc)              (gint i,
                                             const gdouble *x,
                                             gint n_param,
                                             gdouble *param,
                                             GwyNLFitFunc fmarq,
                                             gpointer user_data,
                                             gdouble *deriv,
                                             gboolean *dres);

Fitting function partial derivation type.

i : The index of the value in x to compute the derivation at.
x : x-data as passed to gwy_math_nlfit_fit().
n_param : The number of parameters (size of param).
param : Parameters.
fmarq : The fitting function.
user_data : User data as passed to gwy_math_nlfit_fit().
deriv : Array where the n_param partial derivations by each parameter are to be stored.
dres : Set to TRUE if succeeds, FALSE on failure.

GwyNLFitGuessFunc ()

void        (*GwyNLFitGuessFunc)            (gdouble *x,
                                             gdouble *y,
                                             gint n_dat,
                                             gdouble *param,
                                             gpointer user_data,
                                             gboolean *fres);

x :
y :
n_dat :
param :
user_data :
fres :

GwyNLFitParamScaleFunc ()

void        (*GwyNLFitParamScaleFunc)       (gdouble *param,
                                             gdouble xscale,
                                             gdouble yscale,
                                             gint dir);

param :
xscale :
yscale :
dir :

GwyNLFitWeightFunc ()

void        (*GwyNLFitWeightFunc)           (gdouble *x,
                                             gdouble *y,
                                             gint n_dat,
                                             gdouble *weight,
                                             gpointer user_data);

x :
y :
n_dat :
weight :
user_data :

struct GwyNLFitter

struct GwyNLFitter {

    GwyNLFitFunc fmarq;  /* fitting function */
    GwyNLFitDerFunc dmarq;  /* fitting function derivations */
    gint maxiter;  /* max number of iterations */
    gboolean eval;  /* success? */
    gdouble *covar; /* covariance matrix  */
    gdouble dispersion; /* dispersion */
    gdouble mfi;    /* fitting parameters --
                       fi, snizeni, zvyseni lambda, minimalni lambda */
    gdouble mdec;
    gdouble minc;
    gdouble mtol;
};


struct GwyNLFitPreset

struct GwyNLFitPreset {

    const gchar *function_name;
    const gchar *group_name;
    const gchar *function_formula;
    GwyNLFitFunc function;
    GwyNLFitDerFunc function_derivation;
    GwyNLFitGuessFunc function_guess;
    GwyNLFitParamScaleFunc parameter_scale;
    GwyNLFitWeightFunc set_default_weights;
    gint nparams;
    const GwyNLFitParam *param;
    gpointer _reserved1;
};


struct GwyNLFitParam

struct GwyNLFitParam;


gwy_math_nlfit_new ()

GwyNLFitter* gwy_math_nlfit_new             (GwyNLFitFunc ff,
                                             GwyNLFitDerFunc df);

Creates a new Marquardt-Levenberg nonlinear fitter for function ff.

ff : The fitted function.
df : The derivation of fitted function. You can use gwy_math_nlfit_derive() computing the derivation numerically, when you don't know the derivation explicitely.
Returns : The newly created fitter.

gwy_math_nlfit_free ()

void        gwy_math_nlfit_free             (GwyNLFitter *nlfit);

Completely frees a Marquardt-Levenberg nonlinear fitter.

nlfit : A Marquardt-Levenberg nonlinear fitter.

gwy_math_nlfit_fit ()

gdouble     gwy_math_nlfit_fit              (GwyNLFitter *nlfit,
                                             gint n_dat,
                                             const gdouble *x,
                                             const gdouble *y,
                                             gint n_param,
                                             gdouble *param,
                                             gpointer user_data);

Performs a nonlinear fit of nlfit function on (x,y) data.

nlfit : A Marquardt-Levenberg nonlinear fitter.
n_dat : The number of data points in x, y.
x : Array of independent variable values.
y : Array of dependent variable values.
n_param : The nuber of parameters.
param : Array of parameters (of size n_param). Note the parameters must be initialized to reasonably near values.
user_data : Any pointer that will be passed to the function and derivation as user_data.
Returns : The final residual sum, a negative number in the case of failure.

gwy_math_nlfit_fit_full ()

gdouble     gwy_math_nlfit_fit_full         (GwyNLFitter *nlfit,
                                             gint n_dat,
                                             const gdouble *x,
                                             const gdouble *y,
                                             const gdouble *weight,
                                             gint n_param,
                                             gdouble *param,
                                             const gboolean *fixed_param,
                                             const gint *link_map,
                                             gpointer user_data);

nlfit :
n_dat :
x :
y :
weight :
n_param :
param :
fixed_param :
link_map :
user_data :
Returns :

gwy_math_nlfit_get_max_iterations ()

gint        gwy_math_nlfit_get_max_iterations
                                            (GwyNLFitter *nlfit);

Returns the maximum number of iterations of nonlinear fitter nlfit.

nlfit : A Marquardt-Levenberg nonlinear fitter.
Returns : The maximum number of iterations.

gwy_math_nlfit_set_max_iterations ()

void        gwy_math_nlfit_set_max_iterations
                                            (GwyNLFitter *nlfit,
                                             gint maxiter);

Sets the maximum number of iterations for nonlinear fitter nlfit.

nlfit : A Marquardt-Levenberg nonlinear fitter.
maxiter : The maximum number of iterations.

gwy_math_nlfit_get_dispersion ()

gdouble     gwy_math_nlfit_get_dispersion   (GwyNLFitter *nlfit);

Returns the residual sum divided by the number of degrees of freedom.

This function makes sense only after a successful fit.

nlfit : A Marquardt-Levenberg nonlinear fitter.
Returns : The dispersion.

gwy_math_nlfit_get_correlations ()

gdouble     gwy_math_nlfit_get_correlations (GwyNLFitter *nlfit,
                                             gint par1,
                                             gint par2);

Returns the correlation coefficient between par1-th and par2-th parameter.

This function makes sense only after a successful fit.

nlfit : A Marquardt-Levenberg nonlinear fitter.
par1 : First parameter index.
par2 : Second parameter index.
Returns : The correlation coefficient.

gwy_math_nlfit_get_sigma ()

gdouble     gwy_math_nlfit_get_sigma        (GwyNLFitter *nlfit,
                                             gint par);

Returns the standard deviation of parameter number par.

This function makes sense only after a successful fit.

nlfit : A Marquardt-Levenberg nonlinear fitter.
par : Parameter index.
Returns : The SD of par-th parameter.

gwy_math_nlfit_derive ()

void        gwy_math_nlfit_derive           (gint i,
                                             const gdouble *x,
                                             gint n_param,
                                             gdouble *param,
                                             GwyNLFitFunc ff,
                                             gpointer user_data,
                                             gdouble *deriv,
                                             gboolean *dres);

Numerically computes the partial derivations of ff

i : Index in data_x where to compute the derivation.
x : x-data as passed to gwy_math_nlfit_fit().
n_param : The nuber of parameters.
param : Array of parameters (of size n_param).
ff : The fitted function.
user_data : User data as passed to gwy_math_nlfit_fit().
deriv : Array where the put the result to.
dres : Set to TRUE if succeeds, FALSE on failure.

gwy_math_nlfit_get_npresets ()

gint        gwy_math_nlfit_get_npresets     (void);

Returns the number of available NL fitter presets.

Returns : The number of presets.

gwy_math_nlfit_get_preset ()

GwyNLFitPreset* gwy_math_nlfit_get_preset   (gint preset_id);

Returns NL fitter preset number preset_id.

Presets are numbered sequentially from 0 to gwy_math_nlfit_get_npresets()-1. The numbers are not guaranteed to be constants, use preset names as unique identifiers.

preset_id : NL fitter preset number.
Returns : Preset number preset_id. Note the returned value must not be modified or freed.

gwy_math_nlfit_get_preset_by_name ()

GwyNLFitPreset* gwy_math_nlfit_get_preset_by_name
                                            (const gchar *name);

Returns NL fitter preset whose name is name.

name : NL fitter preset name.
Returns : Preset name, NULL if not found. Note the returned value must not be modified or freed.

gwy_math_nlfit_get_preset_id ()

gint        gwy_math_nlfit_get_preset_id    (const GwyNLFitPreset *preset);

Returns the id of a NL fitter preset.

preset : A NL fitter function preset.
Returns : The preset number.

gwy_math_nlfit_get_preset_value ()

gdouble     gwy_math_nlfit_get_preset_value (const GwyNLFitPreset *preset,
                                             gdouble *params,
                                             gdouble x);

Return preset function value in point x with parameters params.

preset : A NL fitter function preset.
params : Preset parameter values.
x : The point to compute value at.
Returns : The function value.

gwy_math_nlfit_get_preset_name ()

gchar*      gwy_math_nlfit_get_preset_name  (const GwyNLFitPreset *preset);

Return preset name (its unique identifier).

preset : A NL fitter function preset.
Returns : The preset name.

gwy_math_nlfit_get_preset_formula ()

gchar*      gwy_math_nlfit_get_preset_formula
                                            (const GwyNLFitPreset *preset);

Returns function formula of preset (with Pango markup).

preset : A NL fitter function preset.
Returns : The preset function formula.

gwy_math_nlfit_get_preset_param_name ()

gchar*      gwy_math_nlfit_get_preset_param_name
                                            (const GwyNLFitPreset *preset,
                                             gint param);

Returns the name of parameter number param of preset preset.

The name may contain Pango markup.

preset : A NL fitter function preset.
param : A parameter number.
Returns : The name of parameter param.

gwy_math_nlfit_get_preset_param_default ()

gdouble     gwy_math_nlfit_get_preset_param_default
                                            (const GwyNLFitPreset *preset,
                                             gint param);

Returns a suitable constant default parameter value.

It is usually better to do an educated guess of initial parameter value.

preset : A NL fitter function preset.
param : A parameter number.
Returns : The default parameter value.

gwy_math_nlfit_get_preset_nparams ()

gint        gwy_math_nlfit_get_preset_nparams
                                            (const GwyNLFitPreset *preset);

Return the number of parameters of preset.

preset : A NL fitter function preset.
Returns : The number of function parameters.

gwy_math_nlfit_fit_preset ()

GwyNLFitter* gwy_math_nlfit_fit_preset      (const GwyNLFitPreset *preset,
                                             gint n_dat,
                                             const gdouble *x,
                                             const gdouble *y,
                                             gint n_param,
                                             gdouble *param,
                                             gdouble *err,
                                             const gboolean *fixed_param,
                                             gpointer user_data);

preset :
n_dat :
x :
y :
n_param :
param :
err :
fixed_param :
user_data :
Returns :