Gaussian Expectation-Maximisation algorithm. More...

#include <EM.hpp>

Inheritance diagram for ml::EM:

Collaboration diagram for ml::EM:

Public Member Functions
	EM (unsigned int number_components)
	Constructs an EM ready to fit. More...

void	set_seed (unsigned int seed)
	Sets PRNG seed. More...

void	set_absolute_tolerance (double absolute_tolerance)
	Sets absolute tolerance for convergence test. More...

void	set_relative_tolerance (double relative_tolerance)
	Sets relative tolerance for convergence test. More...

void	set_maximum_steps (unsigned int maximum_steps)
	Sets maximum number of E-M steps. More...

void	set_means_initialiser (std::shared_ptr< const Clustering::CentroidsInitialiser > means_initialiser)
	Sets means initialiser. More...

void	set_responsibilities_initialiser (std::shared_ptr< const Clustering::ResponsibilitiesInitialiser > responsibilities_initialiser)
	Sets responsibilities initialiser. More...

void	set_verbose (bool verbose)
	Switches between verbose and quiet mode. More...

void	set_maximise_first (bool maximise_first)
	Switches between starting with E or M step first. More...

bool	fit (Eigen::Ref< const Eigen::MatrixXd > data) override
	Fits the model. More...

auto	number_components () const
	Returns the number of components.

unsigned int	number_clusters () const override
	Returns the number of clusters. More...

const auto &	means () const
	Returns a const reference to matrix containing fitted component means. More...

const Eigen::MatrixXd &	centroids () const override
	Returns a const reference to the matrix of cluster centroids (in columns). More...

const auto &	covariances () const
	Returns a const reference to fitted component covariance matrices. More...

const Eigen::MatrixXd &	covariance (unsigned int k) const
	Returns a const reference to fitted k-th component's covariance matrix. More...

const auto &	mixing_probabilities () const
	Returns a const reference to fitted component mixing probabilities. More...

const auto &	responsibilities () const
	Returns a const reference to resulting component responsibilities. More...

double	log_likelihood () const
	Returns a const reference to maximised log-likelihood of training data.

std::shared_ptr< const Clustering::CentroidsInitialiser >	means_initialiser () const
	Returns a shared pointer to means initialiser implementation.

void	assign_responsibilities (Eigen::Ref< const Eigen::VectorXd > x, Eigen::Ref< Eigen::VectorXd > u) const
	Given a data point x, calculate each component's responsibilities for x and save them in u. More...

const std::vector< unsigned int > &	labels () const override
	Returns a const reference to resulting cluster labels for each datapoint. Value make sense only if fitting converged successfully.

bool	converged () const override
	Reports if the model converged.

Public Member Functions inherited from ml::Clustering::Model
virtual	~Model ()
	Virtual destructor.

Detailed Description

Gaussian Expectation-Maximisation algorithm.

Iterates until log-likelihood converges.

Constructor & Destructor Documentation

◆ EM()

ml::EM::EM ( unsigned int number_components )

Constructs an EM ready to fit.

Parameters

[in] number_components Number of Gaussian components.

Exceptions

If	`number_components == 0`.

Member Function Documentation

◆ set_seed()

void ml::EM::set_seed ( unsigned int seed )

Sets PRNG seed.

Parameters

[in] seed PRNG seed.

◆ set_absolute_tolerance()

void ml::EM::set_absolute_tolerance ( double absolute_tolerance )

Sets absolute tolerance for convergence test.

Parameters

[in] absolute_tolerance Absolute tolerance.

Exceptions

std::domain_error If absolute_tolerance < 0.

◆ set_relative_tolerance()

void ml::EM::set_relative_tolerance ( double relative_tolerance )

Sets relative tolerance for convergence test.

Parameters

[in] relative_tolerance Relative tolerance.

Exceptions

std::domain_error If relative_tolerance < 0.

◆ set_maximum_steps()

void ml::EM::set_maximum_steps ( unsigned int maximum_steps )

Sets maximum number of E-M steps.

Parameters

[in] maximum_steps Maximum number of E-M steps.

Exceptions

std::invalid_argument If maximum_steps < 2.

◆ set_means_initialiser()

void ml::EM::set_means_initialiser ( std::shared_ptr< const Clustering::CentroidsInitialiser > means_initialiser )

Sets means initialiser.

Parameters

[in] means_initialiser Pointer to Clustering::CentroidsInitialiser implementation.

Exceptions

std::invalid_argument If means_initialiser is null.

◆ set_responsibilities_initialiser()

void ml::EM::set_responsibilities_initialiser ( std::shared_ptr< const Clustering::ResponsibilitiesInitialiser > responsibilities_initialiser )

Sets responsibilities initialiser.

Parameters

[in] responsibilities_initialiser Pointer to ResponsibilitiesInitialiser implementation.

Exceptions

std::invalid_argument If responsibilities_initialiser is null.

◆ set_verbose()

void ml::EM::set_verbose ( bool verbose )

inline

Switches between verbose and quiet mode.

Parameters

[in] verbose true if we want verbose output.

◆ set_maximise_first()

void ml::EM::set_maximise_first ( bool maximise_first )

inline

Switches between starting with E or M step first.

Parameters

[in] maximise_first true if we want to start with the E step.

◆ fit()

bool ml::EM::fit ( Eigen::Ref< const Eigen::MatrixXd > data )

overridevirtual

Fits the model.

Parameters

[in] data Matrix (column-major order) with a data point in every column.

Returns: true if fitting converged successfully.

Implements ml::Clustering::Model.

◆ number_clusters()

unsigned int ml::EM::number_clusters ( ) const

inlineoverridevirtual

Returns the number of clusters.

Value make sense only if fitting converged successfully.

Implements ml::Clustering::Model.

◆ means()

const auto& ml::EM::means ( ) const

inline

Returns a const reference to matrix containing fitted component means.

Returns: Const reference to number_dimensions x number_components() matrix.

◆ centroids()

const Eigen::MatrixXd& ml::EM::centroids ( ) const

inlineoverridevirtual

Returns a const reference to the matrix of cluster centroids (in columns).

A centroid represent the central location of the cluster. It is e.g. a mean of all points in the cluster. Value make sense only if fitting converged successfully.

Implements ml::Clustering::Model.

◆ covariances()

const auto& ml::EM::covariances ( ) const

inline

Returns a const reference to fitted component covariance matrices.

Returns: Const reference to std::vector<Eigen::MatrixXd> with length equal to number_components(). Each matrix has size means().rows() x means().rows().

◆ covariance()

const Eigen::MatrixXd& ml::EM::covariance ( unsigned int k ) const

Returns a const reference to fitted k-th component's covariance matrix.

Returns: Const reference to symmetric matrix with size means().rows() x means().rows().

◆ mixing_probabilities()

const auto& ml::EM::mixing_probabilities ( ) const

inline

Returns a const reference to fitted component mixing probabilities.

Returns: Const reference to vector with size number_components().

◆ responsibilities()

const auto& ml::EM::responsibilities ( ) const

inline

Returns a const reference to resulting component responsibilities.

Returns: Const reference to sample_size x number_components() matrix.

◆ assign_responsibilities()

void ml::EM::assign_responsibilities	(	Eigen::Ref< const Eigen::VectorXd >	x,
		Eigen::Ref< Eigen::VectorXd >	u
	)		const

Given a data point x, calculate each component's responsibilities for x and save them in u.

Parameters

[in]	x	Data point with correct dimension.
[out]	u	Vector for responsibilities with length equal to number_components().

Exceptions

std::invalid_argument If x.size() != means().rows() or u.size() != number_components().

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

ML/EM.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ EM()

Member Function Documentation

◆ set_seed()

◆ set_absolute_tolerance()

◆ set_relative_tolerance()

◆ set_maximum_steps()

◆ set_means_initialiser()

◆ set_responsibilities_initialiser()

◆ set_verbose()

◆ set_maximise_first()

◆ fit()

◆ number_clusters()

◆ means()

◆ centroids()

◆ covariances()

◆ covariance()

◆ mixing_probabilities()

◆ responsibilities()

◆ assign_responsibilities()