Generic Mixture of Gaussians (MOG) class. Used as a base for other MOG classes. More...

#include <itpp/stat/mog_generic.h>

Inheritance diagram for itpp::MOG_generic:

Public Member Functions
	MOG_generic ()
	Default constructor.

	MOG_generic (const std::string &name_in)
	Construct the MOG_generic object by loading the parameters from a model file.

	MOG_generic (const int &K_in, const int &D_in, bool full_in=false)
	construct a default model (all Gaussians have zero mean and unit variance for all dimensions)

	MOG_generic (Array< vec > &means_in, bool full_in=false)
	Construct a model using user supplied mean vectors.

	MOG_generic (Array< vec > &means_in, Array< vec > &diag_covs_in, vec &weights_in)
	Construct a model using user supplied parameters (diagonal covariance version)

	MOG_generic (Array< vec > &means_in, Array< mat > &full_covs_in, vec &weights_in)
	Construct a model using user supplied parameters (full covariance version)

virtual	~MOG_generic ()
	Default destructor.

void	init ()
	Initialise the model to be empty.

void	init (const int &K_in, const int &D_in, bool full_in=false)
	initialise the model so that all Gaussians have zero mean and unit variance for all dimensions

void	init (Array< vec > &means_in, bool full_in=false)
	Initialise the model using user supplied mean vectors.

void	init (Array< vec > &means_in, Array< vec > &diag_covs_in, vec &weights_in)
	Initialise the model using user supplied parameters (diagonal covariance version)

void	init (Array< vec > &means_in, Array< mat > &full_covs_in, vec &weights_in)
	Initialise the model using user supplied parameters (full covariance version)

virtual void	cleanup ()
	Release memory used by the model. The model will be empty.

bool	is_valid () const
	Returns true if the model's parameters are valid.

bool	is_full () const
	Returns true if the model has full covariance matrices.

int	get_K () const
	Return the number of Gaussians.

int	get_D () const
	Return the dimensionality.

vec	get_weights () const
	Obtain a copy of the weight vector.

Array< vec >	get_means () const
	Obtain a copy of the array of mean vectors.

Array< vec >	get_diag_covs () const
	Obtain a copy of the array of diagonal covariance vectors.

Array< mat >	get_full_covs () const
	Obtain a copy of the array of full covariance matrices.

void	set_means (Array< vec > &means_in)
	Set the means of the model.

void	set_diag_covs (Array< vec > &diag_covs_in)
	Set the diagonal covariance vectors of the model.

void	set_full_covs (Array< mat > &full_covs_in)
	Set the full covariance matrices of the model.

void	set_weights (vec &weights_in)
	Set the weight vector of the model.

void	set_means_zero ()
	Set the means in the model to be zero.

void	set_diag_covs_unity ()
	Set the diagonal covariance vectors to be unity.

void	set_full_covs_unity ()
	Set the full covariance matrices to be unity.

void	set_weights_uniform ()
	Set all the weights to 1/K, where K is the number of Gaussians.

void	set_checks (bool do_checks_in)
	Enable/disable internal checks for likelihood functions.

void	set_paranoid (bool paranoid_in)
	Enable/disable paranoia about numerical stability.

virtual void	load (const std::string &name_in)
	Initialise the model by loading the parameters from a model file.

virtual void	save (const std::string &name_in) const
	Save the model's parameters to a model file.

virtual void	join (const MOG_generic &B_in)
	Mathematically join the model with a user supplied model.

virtual void	convert_to_diag ()
	Convert the model to use diagonal covariances.

virtual void	convert_to_full ()
	Convert the model to have full covariance matrices.

virtual double	log_lhood_single_gaus (const vec &x_in, const int k)
	calculate the log likelihood of vector `x_in` using only Gaussian `k`

virtual double	log_lhood (const vec &x_in)
	calculate the log likelihood of vector `x_in`

virtual double	lhood (const vec &x_in)
	calculate the likelihood of vector `x_in`

virtual double	avg_log_lhood (const Array< vec > &X_in)
	calculate the average log likelihood of an array of vectors `X_in`

Protected Member Functions
bool	check_size (const vec &x_in) const
	Check if vector `x_in` has the same dimensionality as the model.

bool	check_size (const Array< vec > &X_in) const
	Check if all vectors in Array `X_in` have the same dimensionality as the model.

bool	check_array_uniformity (const Array< vec > &A) const
	Check if all vectors in Array `X_in` have the same dimensionality.

void	set_means_internal (Array< vec > &means_in)
	ADD DOCUMENTATION HERE.

void	set_diag_covs_internal (Array< vec > &diag_covs_in)
	ADD DOCUMENTATION HERE.

void	set_full_covs_internal (Array< mat > &full_covs_in)
	ADD DOCUMENTATION HERE.

void	set_weights_internal (vec &_weigths)
	ADD DOCUMENTATION HERE.

void	set_means_zero_internal ()
	ADD DOCUMENTATION HERE.

void	set_diag_covs_unity_internal ()
	ADD DOCUMENTATION HERE.

void	set_full_covs_unity_internal ()
	ADD DOCUMENTATION HERE.

void	set_weights_uniform_internal ()
	ADD DOCUMENTATION HERE.

void	convert_to_diag_internal ()
	ADD DOCUMENTATION HERE.

void	convert_to_full_internal ()
	ADD DOCUMENTATION HERE.

virtual void	setup_means ()
	additional processing of mean vectors, done as the last step of mean initialisation

virtual void	setup_covs ()
	additional processing of covariance vectors/matrices, done as the last step of covariance initialisation

virtual void	setup_weights ()
	additional processing of the weight vector, done as the last step of weight initialisation

virtual void	setup_misc ()
	additional processing of miscellaneous parameters, done as the last step of overall initialisation

virtual double	log_lhood_single_gaus_internal (const vec &x_in, const int k)
	ADD DOCUMENTATION HERE.

virtual double	log_lhood_internal (const vec &x_in)
	ADD DOCUMENTATION HERE.

virtual double	lhood_internal (const vec &x_in)
	ADD DOCUMENTATION HERE.

Protected Attributes
bool	do_checks
	indicates whether checks on input data are done

bool	valid
	indicates whether the parameters are valid

bool	full
	indicates whether we are using full or diagonal covariance matrices

bool	paranoid
	indicates whether we are paranoid about numerical stability

int	K
	number of gaussians

int	D
	dimensionality

Array< vec >	means
	means

Array< vec >	diag_covs
	diagonal covariance matrices, stored as vectors

Array< mat >	full_covs
	full covariance matrices

vec	weights
	weights

double	log_max_K
	Pre-calcualted std::log(std::numeric_limits<double>::max() / K), where K is the number of Gaussians.

vec	log_det_etc
	Gaussian specific pre-calcualted constants.

vec	log_weights
	Pre-calculated log versions of the weights.

Array< mat >	full_covs_inv
	Pre-calcuated inverted version of each full covariance matrix.

Array< vec >	diag_covs_inv_etc
	Pre-calcuated inverted version of each diagonal covariance vector, where the covariance elements are first multiplied by two.

Detailed Description

Generic Mixture of Gaussians (MOG) class. Used as a base for other MOG classes.

Author: Conrad Sanderson

Used for representing a statistical distribution as a convex combination of multi-variate Gaussian functions. Also known as a Gaussian Mixture Model. This class handles both full and diagonal covariance matrices, allows loading and saving of the MOG's parameters, as well as calculation of likelihoods. The parameters are set by the user or an optimisation algorithm (for example, see the MOG_diag_EM class). For speed and space reasons, diagonal and full covariance matrices are stored and handled separately.

Definition at line 57 of file mog_generic.h.

Constructor & Destructor Documentation

itpp::MOG_generic::MOG_generic ( )

inline

Default constructor.

Note: An empty model is created. The likelihood functions are not useable until the model's parameters are set

Definition at line 67 of file mog_generic.h.

itpp::MOG_generic::MOG_generic ( const std::string & name_in )

inline

Construct the MOG_generic object by loading the parameters from a model file.

Parameters

name_in The model's filename

Definition at line 72 of file mog_generic.h.

itpp::MOG_generic::MOG_generic	(	const int &	K_in,
		const int &	D_in,
		bool	full_in = `false`
	)

inline

construct a default model (all Gaussians have zero mean and unit variance for all dimensions)

Parameters

K_in	Number of Gaussians
D_in	Dimensionality
full_in	If true, use full covariance matrices; if false, use diagonal covariance matrices. Default = false.

Definition at line 79 of file mog_generic.h.

itpp::MOG_generic::MOG_generic	(	Array< vec > &	means_in,
		bool	full_in = `false`
	)

inline

Construct a model using user supplied mean vectors.

Parameters

means_in	Array of mean vectors
full_in	If true, use full covariance matrices; if false, use diagonal covariance matrices. Default = false.

Note: The number of mean vectors specifies the number of Gaussians. The covariance matrices are set to the identity matrix. The weights for all Gaussians are the same, equal to 1/K, where K is the number of Gaussians

Definition at line 88 of file mog_generic.h.

itpp::MOG_generic::MOG_generic	(	Array< vec > &	means_in,
		Array< vec > &	diag_covs_in,
		vec &	weights_in
	)

inline

Construct a model using user supplied parameters (diagonal covariance version)

Parameters

means_in	Array of mean vectors
diag_covs_in	Array of vectors representing diagonal covariances
weights_in	vector of weights

Note: The number of mean vectors, covariance vectors and weights must be the same

Definition at line 96 of file mog_generic.h.

itpp::MOG_generic::MOG_generic	(	Array< vec > &	means_in,
		Array< mat > &	full_covs_in,
		vec &	weights_in
	)

inline

Construct a model using user supplied parameters (full covariance version)

Parameters

means_in	Array of mean vectors
full_covs_in	Array of full covariance matrices
weights_in	vector of weights

Note: The number of mean vectors, covariance matrices and weights must be the same

Definition at line 104 of file mog_generic.h.

Member Function Documentation

void itpp::MOG_generic::init ( )

Initialise the model to be empty.

Note: The likelihood functions are not useable until the model's parameters are set

Definition at line 43 of file mog_generic.cpp.

References cleanup().

Referenced by join(), load(), itpp::MOG_diag_EM_sup::ml(), and itpp::MOG_diag_kmeans_sup::run().

void itpp::MOG_generic::init	(	const int &	K_in,
		const int &	D_in,
		bool	full_in = `false`
	)

initialise the model so that all Gaussians have zero mean and unit variance for all dimensions

Parameters

K_in	Number of Gaussians
D_in	Dimensionality
full_in	If true, use full covariance matrices; if false, use diagonal covariance matrices. Default = false.

Definition at line 46 of file mog_generic.cpp.

References D, do_checks, full, it_assert, K, paranoid, set_diag_covs_unity_internal(), set_full_covs_unity_internal(), set_means_zero_internal(), set_weights_uniform_internal(), setup_misc(), and valid.

void itpp::MOG_generic::init	(	Array< vec > &	means_in,
		bool	full_in = `false`
	)

Initialise the model using user supplied mean vectors.

Parameters

means_in	Array of mean vectors
full_in	If true, use full covariance matrices; if false, use diagonal covariance matrices. Default = false.

Note: The number of mean vectors specifies the number of Gaussians. The covariance matrices are set to the identity matrix. The weights for all Gaussians are the same, equal to 1/K, where K is the number of Gaussians

Definition at line 69 of file mog_generic.cpp.

References check_array_uniformity(), D, do_checks, full, it_assert, K, paranoid, set_diag_covs_unity_internal(), set_full_covs_unity_internal(), set_means(), set_weights_uniform_internal(), setup_misc(), itpp::Array< T >::size(), and valid.

void itpp::MOG_generic::init	(	Array< vec > &	means_in,
		Array< vec > &	diag_covs_in,
		vec &	weights_in
	)

Initialise the model using user supplied parameters (diagonal covariance version)

Parameters

means_in	Array of mean vectors
diag_covs_in	Array of vectors representing diagonal covariances
weights_in	vector of weights

Note: The number of mean vectors, covariance vectors and weights must be the same

Definition at line 89 of file mog_generic.cpp.

References check_array_uniformity(), D, do_checks, full, it_assert, K, paranoid, set_diag_covs_internal(), set_means_internal(), set_weights_internal(), setup_misc(), itpp::Array< T >::size(), and valid.

void itpp::MOG_generic::init	(	Array< vec > &	means_in,
		Array< mat > &	full_covs_in,
		vec &	weights_in
	)

Initialise the model using user supplied parameters (full covariance version)

Parameters

means_in	Array of mean vectors
full_covs_in	Array of covariance matrices
weights_in	vector of weights

Note: The number of mean vectors, covariance matrices and weights must be the same

Definition at line 110 of file mog_generic.cpp.

References check_array_uniformity(), D, do_checks, full, it_assert, K, paranoid, set_full_covs_internal(), set_means_internal(), set_weights_internal(), setup_misc(), itpp::Array< T >::size(), and valid.

void itpp::MOG_generic::cleanup ( )

virtual

Release memory used by the model. The model will be empty.

Note: The likelihood functions are not useable until the model's parameters are re-initialised

Reimplemented in itpp::MOG_diag.

Definition at line 329 of file mog_generic.cpp.

References D, diag_covs, diag_covs_inv_etc, do_checks, full_covs, full_covs_inv, K, log_det_etc, log_weights, means, itpp::Array< T >::set_size(), valid, and weights.

Referenced by itpp::MOG_diag::cleanup(), and init().

void itpp::MOG_generic::set_means ( Array< vec > & means_in )

Set the means of the model.

Note: The number of means must match the number of Gaussians in the model

Definition at line 351 of file mog_generic.cpp.

References set_means_internal(), and valid.

Referenced by init().

void itpp::MOG_generic::set_diag_covs ( Array< vec > & diag_covs_in )

Set the diagonal covariance vectors of the model.

Note: The number of diagonal covariance vectors must match the number of Gaussians in the model

Definition at line 365 of file mog_generic.cpp.

References set_diag_covs_internal(), and valid.

void itpp::MOG_generic::set_full_covs ( Array< mat > & full_covs_in )

Set the full covariance matrices of the model.

Note: The number of covariance matrices must match the number of Gaussians in the model

Definition at line 372 of file mog_generic.cpp.

References set_full_covs_internal(), and valid.

void itpp::MOG_generic::set_weights ( vec & weights_in )

Set the weight vector of the model.

Note: The number of elements in the weight vector must match the number of Gaussians in the model

Definition at line 379 of file mog_generic.cpp.

References set_weights_internal(), and valid.

void itpp::MOG_generic::set_checks ( bool do_checks_in )

inline

Enable/disable internal checks for likelihood functions.

Parameters

do_checks_in If true, checks are enabled; if false, checks are disabled

Note: Disabling checks will provide a speedup in the likelihood functions. Disable them only when you're happy that everything is working correctly.

Definition at line 214 of file mog_generic.h.

void itpp::MOG_generic::set_paranoid ( bool paranoid_in )

inline

Enable/disable paranoia about numerical stability.

Parameters

paranoid_in If true, calculate likelihoods using a safer, but slower method.

Definition at line 219 of file mog_generic.h.

void itpp::MOG_generic::load ( const std::string & name_in )

virtual

Initialise the model by loading the parameters from a model file.

Parameters

name_in The model's filename

Reimplemented in itpp::MOG_diag.

Definition at line 407 of file mog_generic.cpp.

References itpp::it_file::close(), itpp::exist(), itpp::it_file::exists(), init(), it_assert, and valid.

Referenced by itpp::MOG_diag::load().

void itpp::MOG_generic::save ( const std::string & name_in ) const

virtual

Save the model's parameters to a model file.

Parameters

name_in The model's filename

Definition at line 438 of file mog_generic.cpp.

References itpp::it_file::close(), diag_covs, full, full_covs, means, valid, and weights.

void itpp::MOG_generic::join ( const MOG_generic & B_in )

virtual

Mathematically join the model with a user supplied model.

\param B_in user supplied model
\note The Arrays of mean vectors and covariance vectors/matrices from the two models
      are simply concatenated, while the weights of the resultant model are a function
      of the original weights and numbers of Gaussians from both models.
      Specifically,

$w_{new} = [ \alpha \cdot w_{A} ~~~ \beta \cdot w_{B} ]^T$ , where $w_{new}$ is the new weight vector, $w_{A}$ and $w_{B}$ are the weight vectors from model A and B, while $\alpha = K_A / (K_A + KB_in)$ and $\beta = 1-\alpha$ . In turn, $ K_A $ and $ KB_in $ are the numbers of Gaussians in model A and B, respectively.

See On transforming statistical models... for more information.

Definition at line 453 of file mog_generic.cpp.

References itpp::concat(), D, diag_covs, full, full_covs, get_D(), get_diag_covs(), get_full_covs(), get_K(), get_means(), get_weights(), init(), is_full(), is_valid(), it_assert, K, means, valid, and weights.

void itpp::MOG_generic::convert_to_diag ( )

virtual

Convert the model to use diagonal covariances.

Note: If the model is already diagonal, nothing is done. If the model has full covariance matrices, this results in irreversible information loss (in effect the off-diagonal covariance elements are now zero)

Definition at line 499 of file mog_generic.cpp.

References convert_to_diag_internal(), and valid.

Referenced by itpp::MOG_diag::load().

void itpp::MOG_generic::convert_to_full ( )

virtual

Convert the model to have full covariance matrices.

Note: If the model has full covariance matrices, nothing is done. If the model has diagonal covariances, the off-diagonal elements in the full covariance matrices are set to zero.

Reimplemented in itpp::MOG_diag.

Definition at line 518 of file mog_generic.cpp.

References convert_to_full_internal(), and valid.

Member Data Documentation

vec itpp::MOG_generic::log_det_etc

protected

Gaussian specific pre-calcualted constants.

Note: Vector of pre-calculated $-\frac{D}{2}\log(2\pi) -\frac{1}{2}\log(|\Sigma|)$ for each Gaussian, where is the dimensionality and $|\Sigma|$ is the determinant for the Gaussian's covariance matrix $\Sigma$ .

Definition at line 317 of file mog_generic.h.

Referenced by cleanup(), log_lhood_single_gaus_internal(), itpp::MOG_diag::setup_covs(), and setup_covs().

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

itpp/stat/mog_generic.h
itpp/stat/mog_generic.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation