Direct Graphical Models  v.1.7.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...
 
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...
 

Private Member Functions

Mat getSigmaInv (void) const
 Returns \(\Sigma^{-1}\). More...
 
void reset_SigmaInv_Q_Alpha (void)
 
Mat calculateQ (void) const
 

Private Attributes

size_t m_nPoints
 
Mat m_mu
 
Mat m_sigma
 
Mat m_sigmaInv = Mat()
 
Mat m_Q = Mat()
 
long double m_alpha = -1
 

Static Private Attributes

static const bool USE_SAFE_SIGMA = false
 

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 12 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 19 of file KDGauss.cpp.

◆ CKDGauss() [3/3]

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

Copy constructor.

Definition at line 27 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 90 of file KDGauss.cpp.

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

◆ calculateQ()

Mat DirectGraphicalModels::CKDGauss::calculateQ ( void  ) const
private

Definition at line 249 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 81 of file KDGauss.cpp.

Here is the call graph for this function:

◆ 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 86 of file KDGauss.h.

◆ getAlpha()

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

Returns \(\alpha\).

Returns
The Gaussian coefficient \(\alpha\).

Definition at line 163 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 189 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 207 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 198 of file KDGauss.cpp.

Here is the call graph for this function:
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 109 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 99 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 229 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 119 of file KDGauss.h.

Here is the caller graph for this function:

◆ getSigmaInv()

Mat DirectGraphicalModels::CKDGauss::getSigmaInv ( void  ) const
private

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

Note
All non-constant methods must end with calling this function.
Returns
The inversed covariance matrix \(\Sigma^{-1}\): Mat(size: k x k; type: CV_64FC1)

Definition at line 156 of file KDGauss.cpp.

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 175 of file KDGauss.cpp.

Here is the call graph for this function:

◆ 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 50 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 75 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 37 of file KDGauss.cpp.

◆ reset_SigmaInv_Q_Alpha()

void DirectGraphicalModels::CKDGauss::reset_SigmaInv_Q_Alpha ( void  )
inlineprivate

Definition at line 242 of file KDGauss.cpp.

Here is the caller graph for this function:

◆ 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 134 of file KDGauss.cpp.

Here is the call graph for this function:

◆ 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 94 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 145 of file KDGauss.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ m_alpha

long double DirectGraphicalModels::CKDGauss::m_alpha = -1
mutableprivate

Definition at line 216 of file KDGauss.h.

◆ m_mu

Mat DirectGraphicalModels::CKDGauss::m_mu
private

Definition at line 212 of file KDGauss.h.

◆ m_nPoints

size_t DirectGraphicalModels::CKDGauss::m_nPoints
private

Definition at line 211 of file KDGauss.h.

◆ m_Q

Mat DirectGraphicalModels::CKDGauss::m_Q = Mat()
mutableprivate

Definition at line 215 of file KDGauss.h.

◆ m_sigma

Mat DirectGraphicalModels::CKDGauss::m_sigma
private

Definition at line 213 of file KDGauss.h.

◆ m_sigmaInv

Mat DirectGraphicalModels::CKDGauss::m_sigmaInv = Mat()
mutableprivate

Definition at line 214 of file KDGauss.h.

◆ USE_SAFE_SIGMA

const bool DirectGraphicalModels::CKDGauss::USE_SAFE_SIGMA = false
staticprivate

Definition at line 207 of file KDGauss.h.


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