OpenCV: cv::ml::EM Class Reference

| OpenCV 3.4.2 Open Source Computer Vision

Public Types | Public Member Functions | Static Public Member Functions | List of all members
cv::ml::EM Class Referenceabstract
Machine Learning

The class implements the Expectation Maximization algorithm. More...

`#include "ml.hpp"`

Inheritance diagram for cv::ml::EM:

## Public Types
enum | { DEFAULT_NCLUSTERS =5, DEFAULT_MAX_ITERS =100 }
| Default parameters. More...
enum | { START_E_STEP =1, START_M_STEP =2, START_AUTO_STEP =0 }
| The initial step. More...
enum | Types { COV_MAT_SPHERICAL =0, COV_MAT_DIAGONAL =1, COV_MAT_GENERIC =2, COV_MAT_DEFAULT =COV_MAT_DIAGONAL }
| Type of covariation matrices. More...
Public Types inherited from cv::ml::StatModel
enum | Flags { UPDATE_MODEL = 1, RAW_OUTPUT =1, COMPRESSED_INPUT =2, PREPROCESSED_INPUT =4 }

## Public Member Functions
virtual int | getClustersNumber () const =0
virtual int | getCovarianceMatrixType () const =0
virtual void | getCovs (std::vector< Mat > &covs) const =0
| Returns covariation matrices. More...
virtual Mat | getMeans () const =0
| Returns the cluster centers (means of the Gaussian mixture) More...
virtual TermCriteria | getTermCriteria () const =0
virtual Mat | getWeights () const =0
| Returns weights of the mixtures. More...
virtual float | predict (InputArray samples, OutputArray results=noArray(), int flags=0) const CV_OVERRIDE=0
| Returns posterior probabilities for the provided samples. More...
virtual Vec2d | predict2 (InputArray sample, OutputArray probs) const =0
| Returns a likelihood logarithm value and an index of the most probable mixture component for the given sample. More...
virtual void | setClustersNumber (int val)=0
virtual void | setCovarianceMatrixType (int val)=0
virtual void | setTermCriteria (const TermCriteria &val)=0
virtual bool | trainE (InputArray samples, InputArray means0, InputArray covs0=noArray(), InputArray weights0=noArray(), OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray())=0
| Estimate the Gaussian mixture parameters from a samples set. More...
virtual bool | trainEM (InputArray samples, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray())=0
| Estimate the Gaussian mixture parameters from a samples set. More...
virtual bool | trainM (InputArray samples, InputArray probs0, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray())=0
| Estimate the Gaussian mixture parameters from a samples set. More...
Public Member Functions inherited from cv::ml::StatModel
virtual float | calcError (const Ptr< TrainData > &data, bool test, OutputArray resp) const
| Computes error on the training or test dataset. More...
virtual bool | empty () const CV_OVERRIDE
| Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read. More...
virtual int | getVarCount () const =0
| Returns the number of variables in training samples. More...
virtual bool | isClassifier () const =0
| Returns true if the model is classifier. More...
virtual bool | isTrained () const =0
| Returns true if the model is trained. More...
virtual bool | train (const Ptr< TrainData > &trainData, int flags=0)
| Trains the statistical model. More...
virtual bool | train (InputArray samples, int layout, InputArray responses)
| Trains the statistical model. More...
Public Member Functions inherited from cv::Algorithm
| Algorithm ()
virtual | ~Algorithm ()
virtual void | clear ()
| Clears the algorithm state. More...
virtual String | getDefaultName () const
virtual void | read (const FileNode &fn)
| Reads algorithm parameters from a file storage. More...
virtual void | save (const String &filename) const
virtual void | write (FileStorage &fs) const
| Stores algorithm parameters in a file storage. More...
void | write (const Ptr< FileStorage > &fs, const String &name=String()) const
| simplified API for language bindings This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

## Static Public Member Functions
static Ptr< EM > | create ()
static Ptr< EM > | load (const String &filepath, const String &nodeName=String())
| Loads and creates a serialized EM from a file. More...
Static Public Member Functions inherited from cv::ml::StatModel
template<typename _Tp >
static Ptr< _Tp > | train (const Ptr< TrainData > &data, int flags=0)
| Create and train model with default parameters. More...
Static Public Member Functions inherited from cv::Algorithm
template<typename _Tp >
static Ptr< _Tp > | load (const String &filename, const String &objname=String())
| Loads algorithm from the file. More...
template<typename _Tp >
static Ptr< _Tp > | loadFromString (const String &strModel, const String &objname=String())
| Loads algorithm from a String. More...
template<typename _Tp >
static Ptr< _Tp > | read (const FileNode &fn)
| Reads algorithm from the file node. More...

## Additional Inherited Members
Protected Member Functions inherited from cv::Algorithm
void | writeFormat (FileStorage &fs) const

## Detailed Description

The class implements the Expectation Maximization algorithm.

See also
  Expectation Maximization

## Member Enumeration Documentation

## ◆ anonymous enum

anonymous enum

Default parameters.

Enumerator
DEFAULT_NCLUSTERS |
DEFAULT_MAX_ITERS |

## ◆ anonymous enum

anonymous enum

The initial step.

Enumerator
START_E_STEP |
START_M_STEP |
START_AUTO_STEP |

## ◆ Types

enum cv::ml::EM::Types

Type of covariation matrices.

Enumerator
COV_MAT_SPHERICAL | A scaled identity matrix \(\mu_k * I\). There is the only parameter \(\mu_k\) to be estimated for each matrix. The option may be used in special cases, when the constraint is relevant, or as a first step in the optimization (for example in case when the data is preprocessed with PCA). The results of such preliminary estimation may be passed again to the optimization procedure, this time with covMatType=EM::COV_MAT_DIAGONAL.
COV_MAT_DIAGONAL | A diagonal matrix with positive diagonal elements. The number of free parameters is d for each matrix. This is most commonly used option yielding good estimation results.
COV_MAT_GENERIC | A symmetric positively defined matrix. The number of free parameters in each matrix is about \(d^2/2\). It is not recommended to use this option, unless there is pretty accurate initial estimation of the parameters and/or a huge number of training samples.
COV_MAT_DEFAULT |

## Member Function Documentation

## ◆ create()

static Ptr<EM> cv::ml::EM::create | ( |  | ) |
| static

Creates empty EM model. The model should be trained then using StatModel::train(traindata, flags) method. Alternatively, you can use one of the EM::train* methods or load it from file using Algorithm::load<EM>(filename).

## ◆ getClustersNumber()

virtual int cv::ml::EM::getClustersNumber | ( |  | ) | const
| pure virtual

The number of mixture components in the Gaussian mixture model. Default value of the parameter is EM::DEFAULT_NCLUSTERS=5. Some of EM implementation could determine the optimal number of mixtures within a specified value range, but that is not the case in ML yet.

See also
  setClustersNumber

## ◆ getCovarianceMatrixType()

virtual int cv::ml::EM::getCovarianceMatrixType | ( |  | ) | const
| pure virtual

Constraint on covariance matrices which defines type of matrices. See EM::Types.

See also
  setCovarianceMatrixType

## ◆ getCovs()

virtual void cv::ml::EM::getCovs | ( | std::vector< Mat > & | covs | ) | const
| pure virtual

Returns covariation matrices.

Returns vector of covariation matrices. Number of matrices is the number of gaussian mixtures, each matrix is a square floating-point matrix NxN, where N is the space dimensionality.

## ◆ getMeans()

virtual Mat cv::ml::EM::getMeans | ( |  | ) | const
| pure virtual

Returns the cluster centers (means of the Gaussian mixture)

Returns matrix with the number of rows equal to the number of mixtures and number of columns equal to the space dimensionality.

## ◆ getTermCriteria()

virtual TermCriteria cv::ml::EM::getTermCriteria | ( |  | ) | const
| pure virtual

The termination criteria of the EM algorithm. The EM algorithm can be terminated by the number of iterations termCrit.maxCount (number of M-steps) or when relative change of likelihood logarithm is less than termCrit.epsilon. Default maximum number of iterations is EM::DEFAULT_MAX_ITERS=100.

See also
  setTermCriteria

## ◆ getWeights()

virtual Mat cv::ml::EM::getWeights | ( |  | ) | const
| pure virtual

Returns weights of the mixtures.

Returns vector with the number of elements equal to the number of mixtures.

## ◆ load()

static Ptr<EM> cv::ml::EM::load | ( | const String & | filepath,
|  | const String & | nodeName = `String()`
| ) |  |
| static

Loads and creates a serialized EM from a file.

Use EM::save to serialize and store an EM to disk. Load the EM from this file again, by calling this function with the path to the file. Optionally specify the node for the file containing the classifier

Parameters

  filepath | path to serialized EM
  nodeName | name of node containing the classifier

## ◆ predict()

virtual float cv::ml::EM::predict | ( | InputArray | samples,
|  | OutputArray | results = `noArray()`,
|  | int | flags = `0`
| ) |  | const
| pure virtual

Returns posterior probabilities for the provided samples.

Parameters

  samples | The input samples, floating-point matrix
  results | The optional output \( nSamples \times nClusters\) matrix of results. It contains posterior probabilities for each sample from the input
  flags | This parameter will be ignored

Implements cv::ml::StatModel.

## ◆ predict2()

virtual Vec2d cv::ml::EM::predict2 | ( | InputArray | sample,
|  | OutputArray | probs
| ) |  | const
| pure virtual

Returns a likelihood logarithm value and an index of the most probable mixture component for the given sample.

Parameters

  sample | A sample for classification. It should be a one-channel matrix of \(1 \times dims\) or \(dims \times 1\) size.
  probs | Optional output matrix that contains posterior probabilities of each component given the sample. It has \(1 \times nclusters\) size and CV_64FC1 type.

The method returns a two-element double vector. Zero element is a likelihood logarithm value for the sample. First element is an index of the most probable mixture component for the given sample.

## ◆ setClustersNumber()

virtual void cv::ml::EM::setClustersNumber | ( | int | val | ) |
| pure virtual

See also
  getClustersNumber

## ◆ setCovarianceMatrixType()

virtual void cv::ml::EM::setCovarianceMatrixType | ( | int | val | ) |
| pure virtual

See also
  getCovarianceMatrixType

## ◆ setTermCriteria()

virtual void cv::ml::EM::setTermCriteria | ( | const TermCriteria & | val | ) |
| pure virtual

See also
  getTermCriteria

## ◆ trainE()

virtual bool cv::ml::EM::trainE | ( | InputArray | samples,
|  | InputArray | means0,
|  | InputArray | covs0 = `noArray()`,
|  | InputArray | weights0 = `noArray()`,
|  | OutputArray | logLikelihoods = `noArray()`,
|  | OutputArray | labels = `noArray()`,
|  | OutputArray | probs = `noArray()`
| ) |  |
| pure virtual

Estimate the Gaussian mixture parameters from a samples set.

This variation starts with Expectation step. You need to provide initial means \(a_k\) of mixture components. Optionally you can pass initial weights \(\pi_k\) and covariance matrices \(S_k\) of mixture components.

Parameters

  samples | Samples from which the Gaussian mixture model will be estimated. It should be a one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type it will be converted to the inner matrix of such type for the further computing.
  means0 | Initial means \(a_k\) of mixture components. It is a one-channel matrix of \(nclusters \times dims\) size. If the matrix does not have CV_64F type it will be converted to the inner matrix of such type for the further computing.
  covs0 | The vector of initial covariance matrices \(S_k\) of mixture components. Each of covariance matrices is a one-channel matrix of \(dims \times dims\) size. If the matrices do not have CV_64F type they will be converted to the inner matrices of such type for the further computing.
  weights0 | Initial weights \(\pi_k\) of mixture components. It should be a one-channel floating-point matrix with \(1 \times nclusters\) or \(nclusters \times 1\) size.
  logLikelihoods | The optional output matrix that contains a likelihood logarithm value for each sample. It has \(nsamples \times 1\) size and CV_64FC1 type.
  labels | The optional output "class label" for each sample: \(\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\) (indices of the most probable mixture component for each sample). It has \(nsamples \times 1\) size and CV_32SC1 type.
  probs | The optional output matrix that contains posterior probabilities of each Gaussian mixture component given the each sample. It has \(nsamples \times nclusters\) size and CV_64FC1 type.

## ◆ trainEM()

virtual bool cv::ml::EM::trainEM | ( | InputArray | samples,
|  | OutputArray | logLikelihoods = `noArray()`,
|  | OutputArray | labels = `noArray()`,
|  | OutputArray | probs = `noArray()`
| ) |  |
| pure virtual

Estimate the Gaussian mixture parameters from a samples set.

This variation starts with Expectation step. Initial values of the model parameters will be estimated by the k-means algorithm.

Unlike many of the ML models, EM is an unsupervised learning algorithm and it does not take responses (class labels or function values) as input. Instead, it computes the Maximum Likelihood Estimate of the Gaussian mixture parameters from an input sample set, stores all the parameters inside the structure: \(p_{i,k}\) in probs, \(a_k\) in means , \(S_k\) in covs[k], \(\pi_k\) in weights , and optionally computes the output "class label" for each sample: \(\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\) (indices of the most probable mixture component for each sample).

The trained model can be used further for prediction, just like any other classifier. The trained model is similar to the NormalBayesClassifier.

Parameters

  samples | Samples from which the Gaussian mixture model will be estimated. It should be a one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type it will be converted to the inner matrix of such type for the further computing.
  logLikelihoods | The optional output matrix that contains a likelihood logarithm value for each sample. It has \(nsamples \times 1\) size and CV_64FC1 type.
  labels | The optional output "class label" for each sample: \(\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\) (indices of the most probable mixture component for each sample). It has \(nsamples \times 1\) size and CV_32SC1 type.
  probs | The optional output matrix that contains posterior probabilities of each Gaussian mixture component given the each sample. It has \(nsamples \times nclusters\) size and CV_64FC1 type.

## ◆ trainM()

virtual bool cv::ml::EM::trainM | ( | InputArray | samples,
|  | InputArray | probs0,
|  | OutputArray | logLikelihoods = `noArray()`,
|  | OutputArray | labels = `noArray()`,
|  | OutputArray | probs = `noArray()`
| ) |  |
| pure virtual

Estimate the Gaussian mixture parameters from a samples set.

This variation starts with Maximization step. You need to provide initial probabilities \(p_{i,k}\) to use this option.

Parameters

  samples | Samples from which the Gaussian mixture model will be estimated. It should be a one-channel matrix, each row of which is a sample. If the matrix does not have CV_64F type it will be converted to the inner matrix of such type for the further computing.
  probs0 |
  logLikelihoods | The optional output matrix that contains a likelihood logarithm value for each sample. It has \(nsamples \times 1\) size and CV_64FC1 type.
  labels | The optional output "class label" for each sample: \(\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N\) (indices of the most probable mixture component for each sample). It has \(nsamples \times 1\) size and CV_32SC1 type.
  probs | The optional output matrix that contains posterior probabilities of each Gaussian mixture component given the each sample. It has \(nsamples \times nclusters\) size and CV_64FC1 type.

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

- ml/include/opencv2/ml.hpp