Direct Graphical Models  v.1.5.2
DirectGraphicalModels::CNDGauss Class Reference

Multi - dimensional Gauss function class. More...

#include <NDGauss.h>

Public Member Functions

 CNDGauss (dword k)
 Constructor. More...
 
 CNDGauss (const CNDGauss &rhs)
 
 ~CNDGauss (void)
 
CNDGaussoperator= (const CNDGauss &rhs)
 
CNDGaussoperator+= (const CNDGauss &rhs)
 
const CNDGauss operator+ (const CNDGauss &rhs) const
 Merging operator. More...
 
void clear (void)
 Clears class variables. More...
 
void freeze (void)
 Freezes the state of the Gaussian function. More...
 
void addPoint (Mat &point)
 Adds new n-dimensional point (sample) for Gaussian function approximation. More...
 
bool empty (void) const
 Checks weather the Gaussian function is approximated. More...
 
void setMu (Mat &mu)
 Sets \(\mu\). More...
 
Mat getMu (void) const
 Returns \(\mu\). More...
 
void setSigma (Mat &sigma)
 Sets \(\Sigma\). More...
 
Mat getSigma (void) const
 Returns \(\Sigma\). More...
 
Mat getSigmaInv (void) const
 Returns \(\Sigma^{-1}\). More...
 
long double getAlpha (void) const
 Returns \(\alpha\). More...
 
double getValue (Mat &x, Mat &aux1=Mat(), Mat &aux2=Mat(), Mat &aux3=Mat()) const
 Returns unscaled value of the Gaussian function. More...
 
void setNumPoints (long nPoints)
 Sets the number of approximation points. More...
 
size_t getNumPoints (void) const
 Returns the number of approximation points. More...
 
double getEuclidianDistance (const Mat &x) const
 Returns the Euclidian distance between argument point x and the center of multivariate normal distribution \(\mu\). More...
 
double getMahalanobisDistance (const Mat &x) const
 Returns the Mahalanobis distance between argument point x and the center of multivariate normal distribution \(\mathcal{N}(\mu,\Sigma)\). More...
 
double getKullbackLeiberDivergence (CNDGauss &x) const
 Returns the Kullback-Leiber divergence from the multivariate normal distribution \(\mathcal{N}(\mu,\Sigma)\) to argument multivariate normal distribution \(\mathcal{N}_x(\mu_x,\Sigma_x)\). More...
 
Mat getSample (void) const
 Returns a random vector (sample) from multivariate normal distribution. More...
 

Detailed Description

Multi - dimensional Gauss function class.

This class allows to approximate the distribution of random variables (samples) \( \textbf{x} \), represented as k - dinemstional points \( [x_1,x_2,\dots,x_k] \). Under the assumption, that the random variables \( \textbf{x} \) are normally distributed, the approximation is done with multivariate normal distribution: \( \mathcal{N}_k(\mu,\Sigma)= \alpha\cdot\exp\big( -\frac{1}{2}(x-\mu)^T\Sigma^{-1}(x-\mu)\big) \) whith coefficient \( \alpha = \frac{1}{(2\pi)^{k/2}|\Sigma|^{1/2}} \). The parameters \( \mu\) and \(\Sigma \) of the Gaussian function \( \mathcal{N}(\mu,\Sigma) \) may be estimated sequentially with function addPoint() or operator operator+(); also they may be set directly with functions setMu() and setSigma().

The value of the Gaussian function \( \mathcal{N}(\mu,\Sigma) \) in point \( \textbf{x} \) is achieved with functions getAlpha() and getValue():

double value = CNDGauss::getAlpha() * CNDGauss::getValue(x);

In order to generate a random sample from the distribution, given by Gaussian function \( \mathcal{N}(\mu,\Sigma) \), one uses function getSample().

Author
Sergey G. Kosov, serge.nosp@m.y.ko.nosp@m.sov@p.nosp@m.roje.nosp@m.ct-10.nosp@m..de

Definition at line 26 of file NDGauss.h.

Constructor & Destructor Documentation

◆ CNDGauss() [1/2]

DirectGraphicalModels::CNDGauss::CNDGauss ( dword  k)

Constructor.

Parameters
kdimensions

Definition at line 13 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ CNDGauss() [2/2]

DirectGraphicalModels::CNDGauss::CNDGauss ( const CNDGauss rhs)

Definition at line 30 of file NDGauss.cpp.

◆ ~CNDGauss()

DirectGraphicalModels::CNDGauss::~CNDGauss ( void  )

Definition at line 41 of file NDGauss.cpp.

Member Function Documentation

◆ addPoint()

void DirectGraphicalModels::CNDGauss::addPoint ( Mat &  point)

Adds new n-dimensional point (sample) for Gaussian function approximation.

This function is a faster approximation of the merging operator (Ref. operator+()):
\( \hat{\mu} = \frac{n\mu + p}{n + 1} \); \( \hat{\Sigma} = \frac{n\Sigma + (p-\hat{\mu})(p-\hat{\mu})^\top}{n + 1}\)

while(point) estGaussian.addPoint(point); // estimated Gauss function is updated
Parameters
pointk-dimensional point: Mat(size: k x 1; type: CV_64FC1)

Definition at line 112 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ clear()

void DirectGraphicalModels::CNDGauss::clear ( void  )

Clears class variables.

Allows to re-use the class

Definition at line 86 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ empty()

bool DirectGraphicalModels::CNDGauss::empty ( void  ) const
inline

Checks weather the Gaussian function is approximated.

Return values
TRUEif the Gaussian had at least 1 point for approximation, or
FALSEotherwise

Definition at line 92 of file NDGauss.h.

Here is the call graph for this function:

◆ freeze()

void DirectGraphicalModels::CNDGauss::freeze ( void  )

Freezes the state of the Gaussian function.

This is an optimization function, which calculates and fills internal variables need for major get- accessors of this class. If the function was not called, tese variable will be calculated in the get- accessors every tiime on call.

Definition at line 94 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ getAlpha()

long double DirectGraphicalModels::CNDGauss::getAlpha ( void  ) const

Returns \(\alpha\).

Returns
The Gaussian coefficient \(\alpha\).

Definition at line 168 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ getEuclidianDistance()

double DirectGraphicalModels::CNDGauss::getEuclidianDistance ( const Mat &  x) const

Returns the Euclidian distance between argument point x and the center of multivariate normal distribution \(\mu\).

The Euclidian distance is calculated by the formula: \(D_E(\mathcal{N};x)=\sqrt{ (x-\mu)^\top(x-\mu) }\).

Parameters
xn-dimensional point (sample): Mat(size: k x 1; type: CV_64FC1)
Returns
the Euclidian distance: \(D_E(x)\)

Definition at line 194 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ getKullbackLeiberDivergence()

double DirectGraphicalModels::CNDGauss::getKullbackLeiberDivergence ( CNDGauss x) const

Returns the Kullback-Leiber divergence from the multivariate normal distribution \(\mathcal{N}(\mu,\Sigma)\) to argument multivariate normal distribution \(\mathcal{N}_x(\mu_x,\Sigma_x)\).

The Kullback-Leiber divergence (or relative entropy) is calculated by the formula: \(D_{KL}(\mathcal{N};\mathcal{N}_x)=\frac{1}{2}\Big( tr(\Sigma^{-1}_{x}\Sigma) + D^{2}_{M}(\mathcal{N}_x;\mu) - k - \ln\big(\frac{\left|\Sigma\right|}{\left|\Sigma_x\right|}\big) \Big)\) and expressed in nats. Here \(D_M(\mathcal{N}_x;\mu)\) is the Mahalanobis distance beween the centers of multivariate normal distributions \(\mu_x\) and \(\mu\) with respect to \(\mathcal{N}_x\) (see getMahalanobisDistance() for more details). Please note, that it is not a symmetrical quantity, that is to say \( D_{KL}(\mathcal{N};\mathcal{N}_x) \neq D_{KL}(\mathcal{N}_x;\mathcal{N})\) and so could be hardly used as a "distance".

Parameters
xmultivariate normal distribution \(\mathcal{N}_x(\mu_x,\Sigma_x)\) of the dimension k.
Returns
the Kullback-Leiber divergence: \(D_{KL}(\mathcal{N}_x)\)

Definition at line 212 of file NDGauss.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getMahalanobisDistance()

double DirectGraphicalModels::CNDGauss::getMahalanobisDistance ( const Mat &  x) const

Returns the Mahalanobis distance between argument point x and the center of multivariate normal distribution \(\mathcal{N}(\mu,\Sigma)\).

The Mahalanobis distance is calculated by the formula: \(D_M(\mathcal{N};x)=\sqrt{ (x-\mu)^\top\Sigma^{-1}(x-\mu) }\)

Parameters
xn-dimensional point (sample): Mat(size: k x 1; type: CV_64FC1)
Returns
the Mahalanobis distance: \(D_M(x)\)

Definition at line 203 of file NDGauss.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getMu()

Mat DirectGraphicalModels::CNDGauss::getMu ( void  ) const
inline

Returns \(\mu\).

Returns
the mean vector \(\mu\): Mat(size: k x 1; type: CV_64FC1)

Definition at line 102 of file NDGauss.h.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getNumPoints()

size_t DirectGraphicalModels::CNDGauss::getNumPoints ( void  ) const
inline

Returns the number of approximation points.

Returns
the number of sample points, used for the approximation.

Definition at line 155 of file NDGauss.h.

Here is the call graph for this function:

◆ getSample()

Mat DirectGraphicalModels::CNDGauss::getSample ( void  ) const

Returns a random vector (sample) from multivariate normal distribution.

The implementation is based on the paper Generating Random Vectors from the Multivariate Normal Distribution

Returns
n-dimensional point (sample): Mat(size: k x 1; type: CV_64FC1)

Definition at line 234 of file NDGauss.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getSigma()

Mat DirectGraphicalModels::CNDGauss::getSigma ( void  ) const
inline

Returns \(\Sigma\).

Returns
the covariance matrix \(\Sigma\): Mat(size: k x k; type: CV_64FC1)

Definition at line 112 of file NDGauss.h.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getSigmaInv()

Mat DirectGraphicalModels::CNDGauss::getSigmaInv ( void  ) const

Returns \(\Sigma^{-1}\).

Returns
The inversed covariance matrix \(\Sigma^{-1}\): Mat(size: k x k; type: CV_64FC1)

Definition at line 158 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ getValue()

double DirectGraphicalModels::CNDGauss::getValue ( Mat &  x,
Mat &  aux1 = Mat(),
Mat &  aux2 = Mat(),
Mat &  aux3 = Mat() 
) const

Returns unscaled value of the Gaussian function.

This function returns unscaled value of the Gaussian function, i.e. \( \exp\big( -\frac{1}{2}(x-\mu)^T\Sigma^{-1}(x-\mu)\big) \). In order to get the value of \( \mathcal{N}_k(\mu,\Sigma) \), the output of this function must be multiplied with \( \alpha \) from the getAlpha() function.

Note
Three auxilary parameters aux1, aux2 and aux3 are needed for more efficient sequential calculation and do not influent the resulting value, e.g. the code:
Mat aux1, aux2, aux3;
for (int i = 0; i < 100; i++) y[i] = getValue(x[i], aux1, aux2, aux3);
will run about two times faster, then the code:
for (int i = 0; i < 100; i++) y[i] = getValue(x[i]);

This function is PPL-safe function.

Parameters
xn-dimensional point (sample): Mat(size: k x 1; type: CV_64FC1)
aux1Auxilary variable
aux2Auxilary variable
aux3Auxilary variable
Returns
unscaled value of the Gaussian function

Definition at line 180 of file NDGauss.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ operator+()

const CNDGauss DirectGraphicalModels::CNDGauss::operator+ ( const CNDGauss rhs) const
inline

Merging operator.

This operator merges two Gauss finctions into one:

\( \hat{\mu} = \frac{n_1\mu_1 + n_2\mu_2}{n_1 + n_2} \); \( \hat{\Sigma} = \frac{n_1(\Sigma_1 + \mu_1\mu^{\top}_{1}) + n_2(\Sigma_2 + \mu_2\mu^{\top}_{2})}{n_1 + n_2} - \hat{\mu}\hat{\mu}^\top\)

For the sequential Gauss function estimation one also may use this operator (see the code below) or addPoint() function:

CNDGauss newGaussian(point.rows); // auxilary Gauss function
while(point) { // set of all sample points
newGaussian.setMu(point); // mu is set to be equal to the sample
estGaussian += newGaussian; // estimated Gauss function is updated
}

In this case \(n_2 = 1\) and \(\Sigma_2 = 0\).

Definition at line 62 of file NDGauss.h.

Here is the call graph for this function:

◆ operator+=()

CNDGauss & DirectGraphicalModels::CNDGauss::operator+= ( const CNDGauss rhs)

Definition at line 68 of file NDGauss.cpp.

◆ operator=()

CNDGauss & DirectGraphicalModels::CNDGauss::operator= ( const CNDGauss rhs)

Definition at line 50 of file NDGauss.cpp.

◆ setMu()

void DirectGraphicalModels::CNDGauss::setMu ( Mat &  mu)

Sets \(\mu\).

Parameters
muthe mean vector \(\mu\) : Mat(size: k x 1; type: CV_64FC1)

Definition at line 136 of file NDGauss.cpp.

Here is the caller graph for this function:

◆ setNumPoints()

void DirectGraphicalModels::CNDGauss::setNumPoints ( long  nPoints)
inline

Sets the number of approximation points.

Parameters
nPointsthe number of sample points, used for the approximation.

Definition at line 150 of file NDGauss.h.

◆ setSigma()

void DirectGraphicalModels::CNDGauss::setSigma ( Mat &  sigma)

Sets \(\Sigma\).

Parameters
sigmathe covariance matrix \(\Sigma\): Diagonal Mat(size: k x k; type: CV_64FC1)

Definition at line 147 of file NDGauss.cpp.

Here is the caller graph for this function:

The documentation for this class was generated from the following files: