Direct Graphical Models  v.1.6.0
DirectGraphicalModels::CKDGauss Class Reference

Multivariate Gaussian distribution class. More...

#include <KDGauss.h>

Public Member Functions

 CKDGauss (dword k)
 Constructor. More...
 
 CKDGauss (const Mat &mu)
 Constructor. More...
 
 CKDGauss (const CKDGauss &rhs)
 Copy constructor. More...
 
CKDGaussoperator= (const CKDGauss &rhs)
 Copy operator. More...
 
CKDGaussoperator+= (const CKDGauss &rhs)
 Compound merge operator. More...
 
CKDGaussoperator+= (const Mat &point)
 Compound merge operator. More...
 
void clear (void)
 Clears class variables. More...
 
void freeze (void)
 Freezes the state of the Gaussian function. More...
 
bool empty (void) const
 Checks weather the Gaussian function is approximated. More...
 
Accessors
void setNumPoints (long nPoints)
 Sets the number of approximation points. More...
 
size_t getNumPoints (void) const
 Returns the number of approximation points. 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...
 
Main functionality
void addPoint (const Mat &point, bool approximate=false)
 Adds new k-dimensional point (sample) for Gaussian distribution approximation. More...
 
long double getAlpha (void) const
 Returns \(\alpha\). More...
 
double getValue (Mat &x, Mat &aux1=EmptyMat, Mat &aux2=EmptyMat, Mat &aux3=EmptyMat) const
 Returns unscaled value of the Gaussian function. More...
 
Mat getSample (void) const
 Returns a random vector (sample) from multivariate normal distribution. More...
 
Similarity measures
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 (const CKDGauss &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...
 

Detailed Description

Multivariate Gaussian distribution 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+=(const Mat &); 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 the functions getAlpha() and getValue():

double value = CKDGauss::getAlpha() * CKDGauss::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 28 of file KDGauss.h.

Constructor & Destructor Documentation

◆ CKDGauss() [1/3]

DirectGraphicalModels::CKDGauss::CKDGauss ( dword  k)

Constructor.

Parameters
kDimensions

Definition at line 13 of file KDGauss.cpp.

◆ CKDGauss() [2/3]

DirectGraphicalModels::CKDGauss::CKDGauss ( const Mat &  mu)

Constructor.

The dimension of the Gauss function will be derived from the dimension k of the argument \(\mu\)

Parameters
muThe mean vector \(\mu\) : Mat(size: k x 1; type: CV_XXC1)

Definition at line 20 of file KDGauss.cpp.

◆ CKDGauss() [3/3]

DirectGraphicalModels::CKDGauss::CKDGauss ( const CKDGauss rhs)

Copy constructor.

Definition at line 28 of file KDGauss.cpp.

Member Function Documentation

◆ addPoint()

void DirectGraphicalModels::CKDGauss::addPoint ( const Mat &  point,
bool  approximate = false 
)

Adds new k-dimensional point (sample) for Gaussian distribution approximation.

This function is an analog to the merging operator (Ref. operator+=()) and updates the Gaussian distribution in respect to one new observed point, using the following update rules:

\[ \begin{aligned} \hat{\mu} &= \frac{n\mu + p}{n + 1} \\ \hat{\Sigma} &= \frac{n(\Sigma + \mu\mu^\top) + p~p^\top}{n + 1} - \hat{\mu}\hat{\mu}^\top \\ \end{aligned} \]

while(point) estGaussian.addPoint(point); // estimated Gauss function is updated
Parameters
pointk-dimensional point: Mat(size: k x 1; type: CV_64FC1)
approximateFlag indicating whether a faster approximation of the update rule for \(\Sigma\) should be used: \( \hat{\Sigma} = \frac{n\Sigma + (p-\hat{\mu})(p-\hat{\mu})^\top}{n + 1} \). For large \(n\) this approximation is equevalent to the original update rool.

Definition at line 106 of file KDGauss.cpp.

Here is the caller graph for this function:

◆ clear()

void DirectGraphicalModels::CKDGauss::clear ( void  )

Clears class variables.

Allows to re-use the class

Definition at line 82 of file KDGauss.cpp.

◆ empty()

bool DirectGraphicalModels::CKDGauss::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 93 of file KDGauss.h.

◆ freeze()

void DirectGraphicalModels::CKDGauss::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 91 of file KDGauss.cpp.

◆ getAlpha()

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

Returns \(\alpha\).

Returns
The Gaussian coefficient \(\alpha\).

Definition at line 183 of file KDGauss.cpp.

◆ getEuclidianDistance()

double DirectGraphicalModels::CKDGauss::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
xA k-dimensional point (sample): Mat(size: k x 1; type: CV_64FC1)
Returns
The Euclidian distance: \(D_E(x)\)

Definition at line 210 of file KDGauss.cpp.

◆ getKullbackLeiberDivergence()

double DirectGraphicalModels::CKDGauss::getKullbackLeiberDivergence ( const CKDGauss 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 228 of file KDGauss.cpp.

Here is the call graph for this function:

◆ getMahalanobisDistance()

double DirectGraphicalModels::CKDGauss::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 219 of file KDGauss.cpp.

Here is the caller graph for this function:

◆ getMu()

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

Returns \(\mu\).

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

Definition at line 116 of file KDGauss.h.

Here is the caller graph for this function:

◆ getNumPoints()

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

Returns the number of approximation points.

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

Definition at line 106 of file KDGauss.h.

◆ getSample()

Mat DirectGraphicalModels::CKDGauss::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 250 of file KDGauss.cpp.

Here is the call graph for this function:

◆ getSigma()

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

Returns \(\Sigma\).

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

Definition at line 126 of file KDGauss.h.

Here is the caller graph for this function:

◆ getValue()

double DirectGraphicalModels::CKDGauss::getValue ( Mat &  x,
Mat &  aux1 = EmptyMat,
Mat &  aux2 = EmptyMat,
Mat &  aux3 = EmptyMat 
) 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 196 of file KDGauss.cpp.

◆ operator+=() [1/2]

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

Compound merge operator.

This operator merges two Gaussian distributions together:

\[ \begin{aligned} \hat{\mu} &= \frac{n_1\mu_1 + n_2\mu_2}{n1 + n2} \\ \hat{\Sigma} &= \frac{n_1(\Sigma_1 + \mu_1\mu^{\top}_{1}) + n2(\Sigma_2 + \mu_2\mu^{\top}_{2})}{n_1 + n_2} - \hat{\mu}\hat{\mu}^\top \\ \end{aligned} \]

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

while(point) estGaussian += CNDGauss(point); // estimated Gauss function is updated

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

Definition at line 51 of file KDGauss.cpp.

Here is the call graph for this function:

◆ operator+=() [2/2]

CKDGauss & DirectGraphicalModels::CKDGauss::operator+= ( const Mat &  point)

Compound merge operator.

This operator is equivalent to

and might be used for sequential estimation of the Gaussian distribution

while(point) estGaussian += point; // estimated Gauss function is updated

Definition at line 76 of file KDGauss.cpp.

Here is the call graph for this function:

◆ operator=()

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

Copy operator.

Definition at line 38 of file KDGauss.cpp.

◆ setMu()

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

Sets \(\mu\).

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

Definition at line 150 of file KDGauss.cpp.

◆ setNumPoints()

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

Sets the number of approximation points.

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

Definition at line 101 of file KDGauss.h.

◆ setSigma()

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

Sets \(\Sigma\).

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

Definition at line 161 of file KDGauss.cpp.


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