libdspl-2.0
Digital Signal Processing Algorithm Library
Math statistic functions.

Functions

int DSPL_API xcorr_cmplx (complex_t *x, int nx, complex_t *y, int ny, int flag, int nr, complex_t *r, double *t)
 Estimates the cross-correlation vector for complex discrete-time sequences x and y. More...
 
int DSPL_API find_max_abs (double *a, int n, double *m, int *ind)
 Find maximum absolute value from the real vector a More...
 
int DSPL_API mean (double *x, int n, double *m)
 Calculates the mean of the input vector x More...
 
int DSPL_API mean_cmplx (complex_t *x, int n, complex_t *m)
 Calculates the mean of the complex input vector x More...
 
int DSPL_API std (double *x, int n, double *s)
 Calculates the standard deviation of the input vector x More...
 
int DSPL_API std_cmplx (complex_t *x, int n, double *s)
 Calculates the standard deviation of the complex input vector x More...
 
int DSPL_API xcorr (double *x, int nx, double *y, int ny, int flag, int nr, double *r, double *t)
 Estimates the cross-correlation vector for real discrete-time sequences x and y. More...
 

Detailed Description

Function Documentation

◆ find_max_abs()

int find_max_abs ( double *  a,
int  n,
double *  m,
int *  ind 
)

Find maximum absolute value from the real vector a


Function searches maximum absolute value in the real vector a. This value writes to the address m and index keeps to te address ind.

Parameters
[in]aPointer to the real vector a.
Vector size is [n x 1].

[in]nSize of the input vector a.

[out]mPointer to the variable which keeps vector a maximum absolute value.
Pointer can be NULL, maximum value will not return in this case.

[out]indPointer to the variable which keeps index of a maximum absolute value inside vector a.
Pointer can be NULL, index will not return in this case.

Returns
RES_OK if function calculates successfully, else code error.

Example:

double a[5] = {0.0, 2.0, -5.0, 4.0, 2.0};
double m;
int ind;
find_max_abs(a, 5, &m, &ind);
printf("\n\nmax absolute value: %8.1f (index %d)", m, ind);

As result the variable m will keep value 5, and variable ind will keep 2.

Author
Sergey Bakhurin www.dsplib.org

Definition at line 123 of file statistic.c.

◆ mean()

int mean ( double *  x,
int  n,
double *  m 
)

Calculates the mean of the input vector x


Function calculates the mean value

\[ m = \frac{1}{n}\sum_{i = 0}^{n-1} x(i) \]

Parameters
[in]xPointer to the real input vector x.
Vector size is [n x 1].

[in]nSize of input vector x.

[out]mPointer to the variable which keeps vector x mean value.
Memory must be allocated.

RES_OK if function calculates successfully, else code error.

Example:

double a[5] = {0.0, 1.0, 2.0, 3.0, 4.0};
double m;
mean(a, 5, &m);
printf("\n\n Mean value: %8.1f\n", m);

As result the variable m will keep value 2.

Author
Sergey Bakhurin www.dsplib.org

Definition at line 309 of file statistic.c.

Referenced by std().

◆ mean_cmplx()

int mean_cmplx ( complex_t x,
int  n,
complex_t m 
)

Calculates the mean of the complex input vector x


Function calculates the mean value

\[ m = \frac{1}{n}\sum_{i = 0}^{n-1} x(i) \]

Parameters
[in]xPointer to the complex input vector x.
Vector size is [n x 1].

[in]nSize of input vector x.

[out]mPointer to the variable which keeps vector x mean value.
Memory must be allocated.

RES_OK if function calculates successfully, else code error.

Example:

complex_t a[3] = {{0.0, -1.0}, {1.0, 2.0}, {3.0, 5.0}};
mean_cmplx(a, 3, &m);
printf("\n\n Mean value: %8.1f%+3.1fj\n", RE(m), IM(m));

As result the variable m will keep value 1 + 3j.

Author
Sergey Bakhurin www.dsplib.org

Definition at line 407 of file statistic.c.

Referenced by std_cmplx().

◆ std()

int std ( double *  x,
int  n,
double *  s 
)

Calculates the standard deviation of the input vector x


Function calculates the the standard deviation value

\[ s = \sqrt{\frac{1}{n-1} \sum_{i = 0}^{n-1} \big(x(i) - \mu \big)^2}, \]

here \(\mu\) - mean value of the vector x:

\[ \mu = \frac{1}{n} \sum_{i = 0}^{n-1} x(i). \]

Parameters
[in]xPointer to the real input vector x.
Vector size is [n x 1].

[in]nSize of input vector x.

[out]sPointer to the variable which keeps vector x standard deviation value.
Memory must be allocated.

RES_OK if function calculates successfully, else code error.

Example:

double a[5] = {0.0, 1.0, 2.0, 3.0, 4.0};
double s;
std(a, 5, &s);
printf("\n\n Standard deviation value: %8.1f\n", s);

As result the variable s will keep value 1.5811.

Author
Sergey Bakhurin www.dsplib.org

Definition at line 556 of file statistic.c.

◆ std_cmplx()

int std_cmplx ( complex_t x,
int  n,
double *  s 
)

Calculates the standard deviation of the complex input vector x


Function calculates the the standard deviation value

\[ s = \sqrt{\frac{1}{n-1} \sum_{i = 0}^{n-1} \big|x(i) - \mu \big|^2}, \]

here \(\mu\) - mean value of the vector x:

\[ \mu = \frac{1}{n} \sum_{i = 0}^{n-1} x(i). \]

Parameters
[in]xPointer to the complex input vector x.
Vector size is [n x 1].

[in]nSize of input vector x.

[out]sPointer to the variable which keeps vector x standard deviation value.
Memory must be allocated.

RES_OK if function calculates successfully, else code error.

Example:

complex_t a[3] = {{0.0, -1.0}, {1.0, 2.0}, {3.0, 5.0}};
double s;
std_cmplx(a, 3, &s);
printf("\n\n Standard deviation value: %8.1f\n", s);

As result the variable s will keep value 3.3665.

Author
Sergey Bakhurin www.dsplib.org

Definition at line 662 of file statistic.c.

◆ xcorr()

int xcorr ( double *  x,
int  nx,
double *  y,
int  ny,
int  flag,
int  nr,
double *  r,
double *  t 
)

Estimates the cross-correlation vector for real discrete-time sequences x and y.


Estimate the cross correlation \(\widehat{r}_{xy}(k)\) of vector arguments x and y or estimate autocorrelation vector if \(x = y \).

Cross-correlation vector is defined as:

\[ \widehat{r}_{xy}(k) = \frac{1}{N-k} \sum\limits_{n = 0}^{N-k-1} x(n+k)y^*(n), \qquad 0 \leq k <N; \]

\[ \widehat{r}_{xy}(k) = \frac{1}{N+k} \sum\limits_{n = 0}^{N+k-1} y^*(n-k)x(n), \qquad -N < k < 0. \]

here \( N = \max(n_x, n_y) \).

This function uses the FFT algorithm to estimate the scaled correlation vector:

\[ \breve{r}_{xy}(k) = \operatorname{IFFT}\Big[ \operatorname{FFT}\big[ \mathbf{x} \big] \operatorname{FFT}^*\big[ \mathbf{y} \big] \Big] \]

Parameters
[in]xPointer to the discrete-time vector x.
Vector size is [nx x 1].

[in]nxSize of vector x.

[in]yPointer to the discrete-time vector y.
Vector size is [ny x 1].

[in]nySize of vector y.

[in]flagFlag specifies the type of scaling applied to the correlation vector \(\breve{r}_{xy}(k)\).
Is one of:
DSPL_XCORR_NOSCALE unscaled correlation vector from IFFT output \(\breve{r}_{xy}(k)\);
DSPL_XCORR_BIASED biased correlation vector \(\breve{r}_{xy}(k)/N \);
DSPL_XCORR_UNBIASED unbiased correlation vector \(\widehat{r}_{xy}(k) = \frac{\breve{r}_{xy}(k)}{N-|k|} \);

[in]nrMaximum correlation lag.
Correlation vector \(\widehat{r}_{xy}(k)\) is calculated for \( k= -n_r,\,\, -n_r +1, \ldots n_r\).

[out]rPointer to the cross-correlation or autocorrelation vector.
Vector size is [(2*nr+1) x 1].
Memory must be allocated.

[out]rPointer to the cross-correlation argument vector
\( k= -n_r,\,\, -n_r +1, \ldors n_r\).
Vector size is [(2*nr+1) x 1].
Pointer can be NULL.

Returns
RES_OK if function returns successfully.
Else code error.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 214 of file xcorr.c.

◆ xcorr_cmplx()

int DSPL_API xcorr_cmplx ( complex_t x,
int  nx,
complex_t y,
int  ny,
int  flag,
int  nr,
complex_t r,
double *  t 
)

Estimates the cross-correlation vector for complex discrete-time sequences x and y.


int xcorr_cmplx(complex_t* x, int nx, complex_t* y, int ny, int flag, int nr, complex_t* r, double* t)

Estimate the cross correlation \(\widehat{r}_{xy}(k)\) of vector arguments x and y or estimate autocorrelation vector if \(x = y \).

Cross-correlation vector is defined as:

\[ \widehat{r}_{xy}(k) = \frac{1}{N-k} \sum\limits_{n = 0}^{N-k-1} x(n+k)y^*(n), \qquad 0 \leq k <N; \]

\[ \widehat{r}_{xy}(k) = \frac{1}{N+k} \sum\limits_{n = 0}^{N+k-1} y^*(n-k)x(n), \qquad -N < k < 0. \]

here \( N = \max(n_x, n_y) \).

This function uses the FFT algorithm to estimate the scaled correlation vector:

\[ \breve{r}_{xy}(k) = \operatorname{IFFT}\Big[ \operatorname{FFT}\big[ \mathbf{x} \big] \operatorname{FFT}^*\big[ \mathbf{y} \big] \Big] \]

Parameters
[in]xPointer to the discrete-time vector x.
Vector size is [nx x 1].

[in]nxSize of vector x.

[in]yPointer to the discrete-time vector y.
Vector size is [ny x 1].

[in]nySize of vector y.

[in]flagFlag specifies the type of scaling applied to the correlation vector \(\breve{r}_{xy}(k)\).
Is one of:
DSPL_XCORR_NOSCALE unscaled correlation vector from IFFT output \(\breve{r}_{xy}(k)\);
DSPL_XCORR_BIASED biased correlation vector \(\breve{r}_{xy}(k)/N \);
DSPL_XCORR_UNBIASED unbiased correlation vector \(\widehat{r}_{xy}(k) = \frac{\breve{r}_{xy}(k)}{N-|k|} \);

[in]nrMaximum correlation lag.
Correlation vector \(\widehat{r}_{xy}(k)\) is calculated for \( k= -n_r,\,\, -n_r +1, \ldots n_r\).

[out]rPointer to the cross-correlation or autocorrelation vector.
Vector size is [(2*nr+1) x 1].
Memory must be allocated.

[out]rPointer to the cross-correlation argument vector
\( k= -n_r,\,\, -n_r +1, \ldors n_r\).
Vector size is [(2*nr+1) x 1].
Pointer can be NULL.

Returns
RES_OK if function returns successfully.
Else code error.
Author
Sergey Bakhurin www.dsplib.org

Definition at line 449 of file xcorr.c.

#define RE(x)
Macro sets real part of the complex number.
Definition: dspl.h:420
int DSPL_API std_cmplx(complex_t *x, int n, double *s)
Calculates the standard deviation of the complex input vector x
Definition: statistic.c:662
int DSPL_API std(double *x, int n, double *s)
Calculates the standard deviation of the input vector x
Definition: statistic.c:556
double complex_t[2]
Complex data type.
Definition: dspl.h:86
int DSPL_API find_max_abs(double *a, int n, double *m, int *ind)
Find maximum absolute value from the real vector a
Definition: statistic.c:123
int DSPL_API mean_cmplx(complex_t *x, int n, complex_t *m)
Calculates the mean of the complex input vector x
Definition: statistic.c:407
#define IM(x)
Macro sets imaginary part of the complex number.
Definition: dspl.h:478
int DSPL_API mean(double *x, int n, double *m)
Calculates the mean of the input vector x
Definition: statistic.c:309