mlpack::gmm::GMM< FittingType > Class Template Reference

A Gaussian Mixture Model (GMM). More...

List of all members.

Public Member Functions

 GMM (const GMM &other)
 Copy constructor for GMMs using the same fitting type.
template<typename OtherFittingType >
 GMM (const GMM< OtherFittingType > &other)
 Copy constructor for GMMs which use different fitting types.
 GMM (const std::vector< arma::vec > &means, const std::vector< arma::mat > &covariances, const arma::vec &weights, FittingType &fitter)
 Create a GMM with the given means, covariances, and weights, and use the given initialized FittingType class.
 GMM (const std::vector< arma::vec > &means, const std::vector< arma::mat > &covariances, const arma::vec &weights)
 Create a GMM with the given means, covariances, and weights.
 GMM (const size_t gaussians, const size_t dimensionality, FittingType &fitter)
 Create a GMM with the given number of Gaussians, each of which have the specified dimensionality.
 GMM (const size_t gaussians, const size_t dimensionality)
 Create a GMM with the given number of Gaussians, each of which have the specified dimensionality.
 GMM ()
 Create an empty Gaussian Mixture Model, with zero gaussians.
void Classify (const arma::mat &observations, arma::Col< size_t > &labels) const
 Classify the given observations as being from an individual component in this GMM.
std::vector< arma::mat > & Covariances ()
 Return a reference to the vector of covariance matrices (sigma).
const std::vector< arma::mat > & Covariances () const
 Return a const reference to the vector of covariance matrices (sigma).
size_t & Dimensionality ()
 Modify the dimensionality of the model.
size_t Dimensionality () const
 Return the dimensionality of the model.
double Estimate (const arma::mat &observations, const arma::vec &probabilities, const size_t trials=1, const bool useExistingModel=false)
 Estimate the probability distribution directly from the given observations, taking into account the probability of each observation actually being from this distribution, and using the given algorithm in the FittingType class to fit the data.
double Estimate (const arma::mat &observations, const size_t trials=1, const bool useExistingModel=false)
 Estimate the probability distribution directly from the given observations, using the given algorithm in the FittingType class to fit the data.
FittingType & Fitter ()
 Return a reference to the fitting type.
const FittingType & Fitter () const
 Return a const reference to the fitting type.
size_t & Gaussians ()
 Modify the number of gaussians in the model.
size_t Gaussians () const
 Return the number of gaussians in the model.
void Load (const std::string &filename)
 Load a GMM from an XML file.
std::vector< arma::vec > & Means ()
 Return a reference to the vector of means (mu).
const std::vector< arma::vec > & Means () const
 Return a const reference to the vector of means (mu).
GMMoperator= (const GMM &other)
 Copy operator for GMMs which use the same fitting type.
template<typename OtherFittingType >
GMMoperator= (const GMM< OtherFittingType > &other)
 Copy operator for GMMs which use different fitting types.
double Probability (const arma::vec &observation, const size_t component) const
 Return the probability that the given observation came from the given Gaussian component in this distribution.
double Probability (const arma::vec &observation) const
 Return the probability that the given observation came from this distribution.
arma::vec Random () const
 Return a randomly generated observation according to the probability distribution defined by this object.
void Save (const std::string &filename) const
 Save a GMM to an XML file.
arma::vec & Weights ()
 Return a reference to the a priori weights of each Gaussian.
const arma::vec & Weights () const
 Return a const reference to the a priori weights of each Gaussian.

Private Member Functions

double LogLikelihood (const arma::mat &dataPoints, const std::vector< arma::vec > &means, const std::vector< arma::mat > &covars, const arma::vec &weights) const
 This function computes the loglikelihood of the given model.

Private Attributes

std::vector< arma::mat > covariances
 Vector of covariances; one for each Gaussian.
size_t dimensionality
 The dimensionality of the model.
FittingType & fitter
 Reference to the fitting object we should use.
size_t gaussians
 The number of Gaussians in the model.
FittingType localFitter
 Locally-stored fitting object; in case the user did not pass one.
std::vector< arma::vec > means
 Vector of means; one for each Gaussian.
arma::vec weights
 Vector of a priori weights for each Gaussian.

Detailed Description

template<typename FittingType = EMFit<>>
class mlpack::gmm::GMM< FittingType >

A Gaussian Mixture Model (GMM).

This class uses maximum likelihood loss functions to estimate the parameters of the GMM on a given dataset via the given fitting mechanism, defined by the FittingType template parameter. The GMM can be trained using normal data, or data with probabilities of being from this GMM (see GMM::Estimate() for more information).

The FittingType template class must provide a way for the GMM to train on data. It must provide the following two functions:

 void Estimate(const arma::mat& observations,
               std::vector<arma::vec>& means,
               std::vector<arma::mat>& covariances,
               arma::vec& weights);

 void Estimate(const arma::mat& observations,
               const arma::vec& probabilities,
               std::vector<arma::vec>& means,
               std::vector<arma::mat>& covariances,
               arma::vec& weights);

These functions should produce a trained GMM from the given observations and probabilities. These may modify the size of the model (by increasing the size of the mean and covariance vectors as well as the weight vectors), but the method should expect that these vectors are already set to the size of the GMM as specified in the constructor.

For a sample implementation, see the EMFit class; this class uses the EM algorithm to train a GMM, and is the default fitting type.

The GMM, once trained, can be used to generate random points from the distribution and estimate the probability of points being from the distribution. The parameters of the GMM can be obtained through the accessors and mutators.

Example use:

 // Set up a mixture of 5 gaussians in a 4-dimensional space (uses the default
 // EM fitting mechanism).
 GMM<> g(5, 4);

 // Train the GMM given the data observations.
 g.Estimate(data);

 // Get the probability of 'observation' being observed from this GMM.
 double probability = g.Probability(observation);

 // Get a random observation from the GMM.
 arma::vec observation = g.Random();

Definition at line 89 of file gmm.hpp.


Constructor & Destructor Documentation

template<typename FittingType = EMFit<>>
mlpack::gmm::GMM< FittingType >::GMM (  )  [inline]

Create an empty Gaussian Mixture Model, with zero gaussians.

Definition at line 107 of file gmm.hpp.

References mlpack::Log::Debug.

template<typename FittingType = EMFit<>>
mlpack::gmm::GMM< FittingType >::GMM ( const size_t  gaussians,
const size_t  dimensionality 
) [inline]

Create a GMM with the given number of Gaussians, each of which have the specified dimensionality.

Parameters:
gaussians Number of Gaussians in this GMM.
dimensionality Dimensionality of each Gaussian.

Definition at line 127 of file gmm.hpp.

template<typename FittingType = EMFit<>>
mlpack::gmm::GMM< FittingType >::GMM ( const size_t  gaussians,
const size_t  dimensionality,
FittingType &  fitter 
) [inline]

Create a GMM with the given number of Gaussians, each of which have the specified dimensionality.

Also, pass in an initialized FittingType class; this is useful in cases where the FittingType class needs to store some state.

Parameters:
gaussians Number of Gaussians in this GMM.
dimensionality Dimensionality of each Gaussian.
fitter Initialized fitting mechanism.

Definition at line 146 of file gmm.hpp.

template<typename FittingType = EMFit<>>
mlpack::gmm::GMM< FittingType >::GMM ( const std::vector< arma::vec > &  means,
const std::vector< arma::mat > &  covariances,
const arma::vec &  weights 
) [inline]

Create a GMM with the given means, covariances, and weights.

Parameters:
means Means of the model.
covariances Covariances of the model.
weights Weights of the model.

Definition at line 163 of file gmm.hpp.

template<typename FittingType = EMFit<>>
mlpack::gmm::GMM< FittingType >::GMM ( const std::vector< arma::vec > &  means,
const std::vector< arma::mat > &  covariances,
const arma::vec &  weights,
FittingType &  fitter 
) [inline]

Create a GMM with the given means, covariances, and weights, and use the given initialized FittingType class.

This is useful in cases where the FittingType class needs to store some state.

Parameters:
means Means of the model.
covariances Covariances of the model.
weights Weights of the model.

Definition at line 183 of file gmm.hpp.

template<typename FittingType = EMFit<>>
template<typename OtherFittingType >
mlpack::gmm::GMM< FittingType >::GMM ( const GMM< OtherFittingType > &  other  )  [inline]

Copy constructor for GMMs which use different fitting types.

template<typename FittingType = EMFit<>>
mlpack::gmm::GMM< FittingType >::GMM ( const GMM< FittingType > &  other  ) 

Copy constructor for GMMs using the same fitting type.

This also copies the fitter.


Member Function Documentation

template<typename FittingType = EMFit<>>
void mlpack::gmm::GMM< FittingType >::Classify ( const arma::mat &  observations,
arma::Col< size_t > &  labels 
) const

Classify the given observations as being from an individual component in this GMM.

The resultant classifications are stored in the 'labels' object, and each label will be between 0 and (Gaussians() - 1). Supposing that a point was classified with label 2, and that our GMM object was called 'gmm', one could access the relevant Gaussian distribution as follows:

 arma::vec mean = gmm.Means()[2];
 arma::mat covariance = gmm.Covariances()[2];
 double priorWeight = gmm.Weights()[2];
Parameters:
observations List of observations to classify.
labels Object which will be filled with labels.
template<typename FittingType = EMFit<>>
std::vector<arma::mat>& mlpack::gmm::GMM< FittingType >::Covariances (  )  [inline]

Return a reference to the vector of covariance matrices (sigma).

Definition at line 253 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::covariances.

template<typename FittingType = EMFit<>>
const std::vector<arma::mat>& mlpack::gmm::GMM< FittingType >::Covariances (  )  const [inline]

Return a const reference to the vector of covariance matrices (sigma).

Definition at line 251 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::covariances.

template<typename FittingType = EMFit<>>
size_t& mlpack::gmm::GMM< FittingType >::Dimensionality (  )  [inline]

Modify the dimensionality of the model.

Careful! You will have to update each mean and covariance matrix yourself.

Definition at line 243 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::dimensionality.

template<typename FittingType = EMFit<>>
size_t mlpack::gmm::GMM< FittingType >::Dimensionality (  )  const [inline]

Return the dimensionality of the model.

Definition at line 240 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::dimensionality.

template<typename FittingType = EMFit<>>
double mlpack::gmm::GMM< FittingType >::Estimate ( const arma::mat &  observations,
const arma::vec &  probabilities,
const size_t  trials = 1,
const bool  useExistingModel = false 
)

Estimate the probability distribution directly from the given observations, taking into account the probability of each observation actually being from this distribution, and using the given algorithm in the FittingType class to fit the data.

The fitting will be performed 'trials' times; from these trials, the model with the greatest log-likelihood will be selected. By default, only one trial is performed. The log-likelihood of the best fitting is returned.

Optionally, the existing model can be used as an initial model for the estimation by setting 'useExistingModel' to true. If the fitting procedure is deterministic after the initial position is given, then 'trials' should be set to 1.

Parameters:
observations Observations of the model.
probabilities Probability of each observation being from this distribution.
trials Number of trials to perform; the model in these trials with the greatest log-likelihood will be selected.
useExistingModel If true, the existing model is used as an initial model for the estimation.
Returns:
The log-likelihood of the best fit.
template<typename FittingType = EMFit<>>
double mlpack::gmm::GMM< FittingType >::Estimate ( const arma::mat &  observations,
const size_t  trials = 1,
const bool  useExistingModel = false 
)

Estimate the probability distribution directly from the given observations, using the given algorithm in the FittingType class to fit the data.

The fitting will be performed 'trials' times; from these trials, the model with the greatest log-likelihood will be selected. By default, only one trial is performed. The log-likelihood of the best fitting is returned.

Optionally, the existing model can be used as an initial model for the estimation by setting 'useExistingModel' to true. If the fitting procedure is deterministic after the initial position is given, then 'trials' should be set to 1.

Template Parameters:
FittingType The type of fitting method which should be used (EMFit<> is suggested).
Parameters:
observations Observations of the model.
trials Number of trials to perform; the model in these trials with the greatest log-likelihood will be selected.
useExistingModel If true, the existing model is used as an initial model for the estimation.
Returns:
The log-likelihood of the best fit.
template<typename FittingType = EMFit<>>
FittingType& mlpack::gmm::GMM< FittingType >::Fitter (  )  [inline]

Return a reference to the fitting type.

Definition at line 263 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::fitter.

template<typename FittingType = EMFit<>>
const FittingType& mlpack::gmm::GMM< FittingType >::Fitter (  )  const [inline]

Return a const reference to the fitting type.

Definition at line 261 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::fitter.

template<typename FittingType = EMFit<>>
size_t& mlpack::gmm::GMM< FittingType >::Gaussians (  )  [inline]

Modify the number of gaussians in the model.

Careful! You will have to resize the means, covariances, and weights yourself.

Definition at line 237 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::gaussians.

template<typename FittingType = EMFit<>>
size_t mlpack::gmm::GMM< FittingType >::Gaussians (  )  const [inline]

Return the number of gaussians in the model.

Definition at line 234 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::gaussians.

template<typename FittingType = EMFit<>>
void mlpack::gmm::GMM< FittingType >::Load ( const std::string &  filename  ) 

Load a GMM from an XML file.

The format of the XML file should be the same as is generated by the Save() method.

Parameters:
filename Name of XML file containing model to be loaded.
template<typename FittingType = EMFit<>>
double mlpack::gmm::GMM< FittingType >::LogLikelihood ( const arma::mat &  dataPoints,
const std::vector< arma::vec > &  means,
const std::vector< arma::mat > &  covars,
const arma::vec &  weights 
) const [private]

This function computes the loglikelihood of the given model.

This function is used by GMM::Estimate().

Parameters:
dataPoints Observations to calculate the likelihood for.
means Means of the given mixture model.
covars Covariances of the given mixture model.
weights Weights of the given mixture model.
template<typename FittingType = EMFit<>>
std::vector<arma::vec>& mlpack::gmm::GMM< FittingType >::Means (  )  [inline]

Return a reference to the vector of means (mu).

Definition at line 248 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::means.

template<typename FittingType = EMFit<>>
const std::vector<arma::vec>& mlpack::gmm::GMM< FittingType >::Means (  )  const [inline]

Return a const reference to the vector of means (mu).

Definition at line 246 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::means.

template<typename FittingType = EMFit<>>
GMM& mlpack::gmm::GMM< FittingType >::operator= ( const GMM< FittingType > &  other  ) 

Copy operator for GMMs which use the same fitting type.

This also copies the fitter.

template<typename FittingType = EMFit<>>
template<typename OtherFittingType >
GMM& mlpack::gmm::GMM< FittingType >::operator= ( const GMM< OtherFittingType > &  other  )  [inline]

Copy operator for GMMs which use different fitting types.

template<typename FittingType = EMFit<>>
double mlpack::gmm::GMM< FittingType >::Probability ( const arma::vec &  observation,
const size_t  component 
) const

Return the probability that the given observation came from the given Gaussian component in this distribution.

Parameters:
observation Observation to evaluate the probability of.
component Index of the component of the GMM to be considered.
template<typename FittingType = EMFit<>>
double mlpack::gmm::GMM< FittingType >::Probability ( const arma::vec &  observation  )  const

Return the probability that the given observation came from this distribution.

Parameters:
observation Observation to evaluate the probability of.
template<typename FittingType = EMFit<>>
arma::vec mlpack::gmm::GMM< FittingType >::Random (  )  const

Return a randomly generated observation according to the probability distribution defined by this object.

Returns:
Random observation from this GMM.
template<typename FittingType = EMFit<>>
void mlpack::gmm::GMM< FittingType >::Save ( const std::string &  filename  )  const

Save a GMM to an XML file.

Parameters:
filename Name of XML file to write to.
template<typename FittingType = EMFit<>>
arma::vec& mlpack::gmm::GMM< FittingType >::Weights (  )  [inline]

Return a reference to the a priori weights of each Gaussian.

Definition at line 258 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::weights.

template<typename FittingType = EMFit<>>
const arma::vec& mlpack::gmm::GMM< FittingType >::Weights (  )  const [inline]

Return a const reference to the a priori weights of each Gaussian.

Definition at line 256 of file gmm.hpp.

References mlpack::gmm::GMM< FittingType >::weights.


Member Data Documentation

template<typename FittingType = EMFit<>>
std::vector<arma::mat> mlpack::gmm::GMM< FittingType >::covariances [private]

Vector of covariances; one for each Gaussian.

Definition at line 99 of file gmm.hpp.

Referenced by mlpack::gmm::GMM< FittingType >::Covariances().

template<typename FittingType = EMFit<>>
size_t mlpack::gmm::GMM< FittingType >::dimensionality [private]

The dimensionality of the model.

Definition at line 95 of file gmm.hpp.

Referenced by mlpack::gmm::GMM< FittingType >::Dimensionality().

template<typename FittingType = EMFit<>>
FittingType& mlpack::gmm::GMM< FittingType >::fitter [private]

Reference to the fitting object we should use.

Definition at line 384 of file gmm.hpp.

Referenced by mlpack::gmm::GMM< FittingType >::Fitter().

template<typename FittingType = EMFit<>>
size_t mlpack::gmm::GMM< FittingType >::gaussians [private]

The number of Gaussians in the model.

Definition at line 93 of file gmm.hpp.

Referenced by mlpack::gmm::GMM< FittingType >::Gaussians().

template<typename FittingType = EMFit<>>
FittingType mlpack::gmm::GMM< FittingType >::localFitter [private]

Locally-stored fitting object; in case the user did not pass one.

Definition at line 381 of file gmm.hpp.

template<typename FittingType = EMFit<>>
std::vector<arma::vec> mlpack::gmm::GMM< FittingType >::means [private]

Vector of means; one for each Gaussian.

Definition at line 97 of file gmm.hpp.

Referenced by mlpack::gmm::GMM< FittingType >::Means().

template<typename FittingType = EMFit<>>
arma::vec mlpack::gmm::GMM< FittingType >::weights [private]

Vector of a priori weights for each Gaussian.

Definition at line 101 of file gmm.hpp.

Referenced by mlpack::gmm::GMM< FittingType >::Weights().


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

Generated on 29 Sep 2016 for MLPACK by  doxygen 1.6.1