High-level functions for non-linear fitting


Functions

cpl_imagelist * cpl_fit_imagelist_polynomial (const cpl_vector *x_pos, const cpl_imagelist *values, int mindeg, int maxdeg, cpl_boolean is_symsamp, cpl_type pixeltype, cpl_image *fiterror)
 Least-squares fit a polynomial to each pixel in a list of images.
cpl_imagelist * cpl_fit_imagelist_polynomial_window (const cpl_vector *x_pos, const cpl_imagelist *values, int llx, int lly, int urx, int ury, int mindeg, int maxdeg, cpl_boolean is_symsamp, cpl_type pixeltype, cpl_image *fiterror)
 Least-squares fit a polynomial to each pixel in a list of images.
cpl_error_code cpl_fit_lvmq (const cpl_matrix *x, const cpl_matrix *sigma_x, const cpl_vector *y, const cpl_vector *sigma_y, cpl_vector *a, const int ia[], int(*f)(const double x[], const double a[], double *result), int(*dfda)(const double x[], const double a[], double result[]), double relative_tolerance, int tolerance_count, int max_iterations, double *mse, double *red_chisq, cpl_matrix **covariance)
 Fit a function to a set of data.

Detailed Description

This module provides a routine for non-linear fitting.

Synopsis:
   #include "cpl_fit.h"

Function Documentation

cpl_imagelist* cpl_fit_imagelist_polynomial ( const cpl_vector *  x_pos,
const cpl_imagelist *  values,
int  mindeg,
int  maxdeg,
cpl_boolean  is_symsamp,
cpl_type  pixeltype,
cpl_image *  fiterror 
)

Least-squares fit a polynomial to each pixel in a list of images.

Parameters:
x_pos The vector of positions to fit
values The list of images with values to fit
mindeg The smallest degree with a non-zero coefficient
maxdeg The polynomial degree of the fit, at least mindeg
is_symsamp True iff the x_pos values are symmetric around their mean
pixeltype The pixel-type of the created image list
fiterror When non-NULL, the error of the fit
Note:
values and x_pos must have the same number of elements.

The created imagelist must be deallocated with cpl_imagelist_delete().

x_pos must have at least 1 + (maxdeg - mindeg) distinct values.

Any bad-pixel map in the input is ignored.

Returns:
The image list of the fitted polynomial coefficients or NULL on error.
See also:
cpl_fit_imagelist_polynomial_window()
Possible _cpl_error_code_ set in this function:

cpl_imagelist* cpl_fit_imagelist_polynomial_window ( const cpl_vector *  x_pos,
const cpl_imagelist *  values,
int  llx,
int  lly,
int  urx,
int  ury,
int  mindeg,
int  maxdeg,
cpl_boolean  is_symsamp,
cpl_type  pixeltype,
cpl_image *  fiterror 
)

Least-squares fit a polynomial to each pixel in a list of images.

Parameters:
x_pos The vector of positions to fit
values The list of images with values to fit
llx Lower left x coordinate
lly Lower left y coordinate
urx Upper right x coordinate
ury Upper right y coordinate
mindeg The smallest degree with a non-zero coefficient
maxdeg The polynomial degree of the fit, at least mindeg
is_symsamp True iff the x_pos values are symmetric around their mean
pixeltype The pixel-type of the created image list
fiterror When non-NULL, the error of the fit
Note:
values and x_pos must have the same number of elements.

The created imagelist must be deallocated with cpl_imagelist_delete().

x_pos must have at least 1 + (maxdeg - mindeg) distinct values.

Any bad-pixel map in the input is ignored.

Returns:
The image list of the fitted polynomial coefficients or NULL on error.
See also:
cpl_polynomial_fit_1d_create()
For each pixel, a polynomial representing the relation value = P(x) is computed where: P(x) = x^{mindeg} * (a_0 + a_1 * x + ... + a_{nc-1} * x^{nc-1}), where mindeg >= 0 and maxdeg >= mindeg, and nc is the number of polynomial coefficients to determine, nc = 1 + (maxdeg - mindeg).

The returned image list thus contains nc coefficient images, a_0, a_1, ..., a_{nc-1}.

np is the number of sample points, i.e. the number of elements in x_pos and number of images in the image list.

is_symsamp is ignored if mindeg is nonzero, otherwise is_symsamp may to be set to CPL_TRUE if and only if the values in x_pos are known a-priori to be symmetric around their mean, e.g. (1, 2, 4, 6, 10, 14, 16, 18, 19), but not (1, 2, 4, 6, 10, 14, 16). Setting is_symsamp to CPL_TRUE while mindeg is zero eliminates certain round-off errors. For higher order fitting the fitting problem known as "Runge's phenomenon" is minimized using the socalled "Chebyshev nodes" as sampling points. For Chebyshev nodes is_symsamp can be set to CPL_TRUE.

Even though it is not an error, it is hardly useful to use an image of pixel type integer for the fitting error. An image of pixel type float should on the other hand be sufficient for most fitting errors.

The call requires the following number of FLOPs, where nz is the number of pixels in any one image in the imagelist:

2 * nz * nc * (nc + np) + np * nc^2 + nc^3/3 + O(nc * (nc + np)).

If mindeg is zero an additional nz * nc^2 FLOPs are required.

If fiterror is non-NULL an additional 2 * nz * nc * np FLOPs are required.

Possible _cpl_error_code_ set in this function:

cpl_error_code cpl_fit_lvmq ( const cpl_matrix *  x,
const cpl_matrix *  sigma_x,
const cpl_vector *  y,
const cpl_vector *  sigma_y,
cpl_vector *  a,
const int  ia[],
int(*)(const double x[], const double a[], double *result)  f,
int(*)(const double x[], const double a[], double result[])  dfda,
double  relative_tolerance,
int  tolerance_count,
int  max_iterations,
double *  mse,
double *  red_chisq,
cpl_matrix **  covariance 
)

Fit a function to a set of data.

Parameters:
x N x D matrix of the positions to fit. Each matrix row is a D-dimensional position.
sigma_x Uncertainty (one sigma, gaussian errors assumed) assosiated with x. Taking into account the uncertainty of the independent variable is currently unsupported, and this parameter must therefore be set to NULL.
y The N values to fit.
sigma_y Vector of size N containing the uncertainties of the y-values. If this parameter is NULL, constant uncertainties are assumed.
a Vector containing M fit parameters. Must contain a guess solution on input and contains the best fit parameters on output.
ia Array of size M defining which fit parameters participate in the fit (non-zero) and which fit parameters are held constant (zero). At least one element must be non-zero. Alternatively, pass NULL to fit all parameters.
f Function that evaluates the fit function at the position specified by the first argument (an array of size D) using the fit parameters specified by the second argument (an array of size M). The result must be output using the third parameter, and the function must return zero iff the evaluation succeded.
dfda Function that evaluates the first order partial derivatives of the fit function with respect to the fit parameters at the position specified by the first argument (an array of size D) using the parameters specified by the second argument (an array of size M). The result must be output using the third parameter (array of size M), and the function must return zero iff the evaluation succeded.
relative_tolerance The algorithm converges by definition if the relative decrease in chi squared is less than tolerance tolerance_count times in a row. Recommended default: CPL_FIT_LVMQ_TOLERANCE
tolerance_count The algorithm converges by definition if the relative decrease in chi squared is less than tolerance tolerance_count times in a row. Recommended default: CPL_FIT_LVMQ_COUNT
max_iterations If this number of iterations is reached without convergence, the algorithm diverges, by definition. Recommended default: CPL_FIT_LVMQ_MAXITER
mse If non-NULL, the mean squared error of the best fit is computed.
red_chisq If non-NULL, the reduced chi square of the best fit is computed. This requires sigma_y to be specified.
covariance If non-NULL, the formal covariance matrix of the best fit parameters is computed (or NULL on error). On success the diagonal terms of the covariance matrix are guaranteed to be positive. However, terms that involve a constant parameter (as defined by the input array ia) are always set to zero. Computation of the covariacne matrix requires sigma_y to be specified.
Returns:
CPL_ERROR_NONE iff OK.
This function makes a minimum chi squared fit of the specified function to the specified data set using a Levenberg-Marquardt algorithm.

Possible _cpl_error_code_ set in this function:


Generated on Wed Mar 18 09:40:13 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7