Functions
cpl_polynomial *	clipm_math_regression_linear_1d (const double x, const double y, int N, double *out_mse)
	Do a single linear regression. More...

cpl_polynomial *	clipm_math_regression_linear (const cpl_matrix Xpos, const cpl_vector Y, double *out_mse)
	Do a multiple (multivariate) linear regression. More...

cpl_matrix *	clipm_math_regression_linear_series (const cpl_matrix Xpos, const cpl_matrix Y, double *out_mse)
	Do a multiple (multivariate) linear regression respectively for test data sets in a series. More...

Detailed Description

This module provides functions for regression.

Synopsis:: #include "clipm_math_regression.h"

*

Function Documentation

cpl_polynomial* clipm_math_regression_linear	(	const cpl_matrix *	Xpos,
		const cpl_vector *	Y,
		double *	out_mse
	)

Do a multiple (multivariate) linear regression.

Parameters

Xpos	Multi-dimensional positions
Y	Values
out_mse	Output mean square error, can be NULL

Returns: Multivariate polynomial of degree 1 (hyperplane), NULL in the case of error

Overview:: A multiple (or multi-dimensional) linear regression is performed. In analogy to a single linear regression (cp. clipm_math_regression_linear_1d()), a set of positions is passed, here in the matrix Xpos: each row contains one position. The number of columns defines the number of dimensions, or in other words the number of variables on which the Y values depend.

The number of positions must be greater than the number of dimensions. If this is not the case, or if the values don't allow a non-ambigous solution, then the error CPL_ERROR_SINGULAR_MATRIX will be set.

Y is a vector containing the set of data values. It must have the size as the number of rows in the matrix Xpos.

In mathematical speech, the resulting coefficients define a hyperplane in the space $\mathbf{R}^{Dim+1}$ , where Dim is the number of columns of the matrix Xpos.

If mse is not a NULL pointer, then the remaining mean square error is computed and put out via this parameter. Since a linear regression is analytically solveable, this computation is performed extra and decreases the performance.

Parameter Details:: Searching a polynome $y = b_0 + b_1x_1 + b_2x_2 + \cdots + b_Px_P$ , and having N data sets, it is with $X=\left\lgroup \begin{array}{ccc} x_{11}&\cdots&x_{1P}\\ \vdots&\ddots&\vdots\\ x_{N1}&\cdots&x_{NP} \end{array}\right\rgroup$ , $Y=\left\lgroup \begin{array}{c} y_1\\ \vdots\\ y_N \end{array}\right\rgroup$ , and $B=\left\lgroup \begin{array}{c} b_1\\ \vdots\\ b_P \end{array}\right\rgroup$ :
$Y=XB + b_0$
b0 to bP are returned as the coefficients of the polynome. The returned mean square error is $mse=(Y-XB+b_0)'(Y-XB+b_0)\cdot\frac{1}{N}$ .

Note: If a cpl_matrix containing the coefficients is preferred as a return value, please consider using the function clipm_math_regression_linear_series() with a one-column input matrix Y.

Error Handling:

In the case of error, one of the following error codes is set, and NULL is returned:

CPL_ERROR_NULL_INPUT: x or y is NULL
CPL_ERROR_SINGULAR_MATRIX: the equations are not solveable

Example:: A test value depends on (or correlates with) 4 variables. Each measurement gives the 4 variable values and the test value. The 4 variable values are stored in one row of the matrix Xpos, and the test value in the same row of the vector Y. The minimum required number of measurements (which is the same as the number of rows) is 5.

cpl_polynomial* clipm_math_regression_linear_1d	(	const double *	x,
		const double *	y,
		int	N,
		double *	out_mse
	)

Do a single linear regression.

Parameters

x	X positions
y	Values
N	Number of positions
out_mse	Output mean square error, can be NULL

Returns: Univariate (one-dimensional) polynomial of degree 1 (straight line), NULL in the case of error

Overview:: This function computes the coefficients of a straight regression line through a set of N positions. The underlying strategy is the minimization of the mean square error between the line and the values in Y. The two coefficients are stored in the returned univariate (1-dimensional) polynomial of degree 1.

If mse is not a NULL pointer, then the remaining mean square error is computed and put out via this parameter. Since a linear regression is analytically solveable, this computation is performed extra and decreases the performance.

If all X positions are the same, then a division by zero will occur.

The number of positions must be greater or equal 2.

Note: If a cpl_matrix containing the coefficients is preferred as a return value, please consider using the function clipm_math_regression_linear_series() with a one-column input matrix Y. But also be aware that this function might be a bit less efficient due to its generality.

Error Handling:

In the case of error, one of the following error codes is set, and NULL is returned:

CPL_ERROR_ILLEGAL_INPUT: N < 2
CPL_ERROR_NULL_INPUT: x or y is NULL
CPL_ERROR_DIVISION_BY_ZERO: all x are the same

cpl_matrix* clipm_math_regression_linear_series	(	const cpl_matrix *	Xpos,
		const cpl_matrix *	Y,
		double *	out_mse
	)

Do a multiple (multivariate) linear regression respectively for test data sets in a series.

Parameters

Xpos	Multi-dimensional positions
Y	Values
out_mse	Output array of mean square errors, can be NULL

Returns: Multivariate polynomial of degree 1 (hyperplane)

Overview:: For a series of test data sets, respectively for each set a multiple (or multi-dimensional) linear regression is performed. This function is a general form of clipm_math_regression_linear(), please read its documentation first!

A set of test values is stored in each column of Y. Each column of Y is interpreted as a single vector, and a multiple linear regression is done for it using the same set of position values stored in Xpos.

Parameter Details:

Extending the formulae from clipm_math_regression_linear(), it is with a number of Q datasets in Y :
$X=\left\lgroup \begin{array}{ccc} x_{11}&\cdots&x_{1P}\\ \vdots&\ddots&\vdots\\ x_{N1}&\cdots&x_{NP} \end{array}\right\rgroup$ , $\Psi_q=\left\lgroup \begin{array}{c} y_{1q}\\ \vdots\\ y_{Nq} \end{array}\right\rgroup$ , $Y=\left\lgroup \begin{array}{ccc} \Psi_1&\cdots&\Psi_Q \end{array}\right\rgroup$ , and $B_q=\left\lgroup \begin{array}{c} b_{1q}\\ \vdots\\ b_{Pq} \end{array}\right\rgroup$ :

$\Psi_q=XB_q + b_{0q}$

The returned mean square error mse[1...Q] is: $mse_q=(\Psi_q-XB_q+b_{0q})'(\Psi_q-XB_q+b_{0q})\cdot\frac{1}{N}$ .
The returned matrix has the form:

$B=\left\lgroup \begin{array}{ccc} B_1 & \cdots & B_Q \end{array}\right\rgroup =\left\lgroup \begin{array}{ccc} b_{01}&\cdots&b_{0Q}\\ b_{11}&\cdots&b_{1Q}\\ \vdots&\ddots&\vdots\\ b_{P1}&\cdots&b_{PQ} \end{array}\right\rgroup$

$b_{0q}$ to $b_{Pq}$ are the respective coefficients of a polynome $y_{0q}(x_1,\cdots,x_P)$ .

Error Handling:

In the case of error, one of the following error codes is set, and NULL is returned:

CPL_ERROR_NULL_INPUT: Xpos or Y is NULL
CPL_ERROR_INCOMPATIBLE_INPUT: Xpos and Y have not the same number of rows
CPL_ERROR_SINGULAR_MATRIX: the equations are not solveable

Functions

Detailed Description

Function Documentation