Class cv::ml::EM

The class implements the Expectation Maximization algorithm. View details

#include <opencv2/ml.hpp>

Collaboration diagram for cv::ml::EM:

Public Types

Default parameters.

enum cv::ml::EM {
    cv::ml::DEFAULT_NCLUSTERS =5,
    cv::ml::DEFAULT_MAX_ITERS =100
}

The initial step.

enum cv::ml::EM {
    cv::ml::START_E_STEP =1,
    cv::ml::START_M_STEP =2,
    cv::ml::START_AUTO_STEP =0
}

Type of covariation matrices.

enum Types {
    COV_MAT_SPHERICAL =0,
    COV_MAT_DIAGONAL =1,
    COV_MAT_GENERIC =2,
    COV_MAT_DEFAULT =COV_MAT_DIAGONAL
}

Public Types inherited from cv::ml::StatModel

Return	Name	Description
	Flags

Public Member Functions

Public Member Functions inherited from cv::ml::StatModel

Return	Name	Description
float	calcError(     const Ptr< TrainData > & data,     bool test,     OutputArray resp )	Computes error on the training or test dataset.
bool	empty()	Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read.
int	getVarCount()	Returns the number of variables in training samples.
bool	isClassifier()	Returns true if the model is classifier.
bool	isTrained()	Returns true if the model is trained.
float	predict(     InputArray samples,     OutputArray results = noArray(),     int flags = 0 )	Predicts response(s) for the provided sample(s)
bool	train(     const Ptr< TrainData > & trainData,     int flags = 0 )	Trains the statistical model.
bool	train(     InputArray samples,     int layout,     InputArray responses )	Trains the statistical model.

Public Member Functions inherited from cv::Algorithm

Return	Name	Description
	Algorithm()
	~Algorithm()
void	clear()	Clears the algorithm state.
bool	empty()	Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read.
String	getDefaultName()
void	read(const FileNode & fn)	Reads algorithm parameters from a file storage.
void	save(const String & filename)
void	write(     const Ptr< FileStorage > & fs,     const String & name = String() )
void	write(FileStorage & fs)	Stores algorithm parameters in a file storage.
void	write(     FileStorage & fs,     const String & name )

Static Public Member Functions

Static Public Member Functions inherited from cv::ml::StatModel

Return	Name	Description
static Ptr< _Tp >	train(     const Ptr< TrainData > & data,     int flags = 0 )	Create and train model with default parameters.

Static Public Member Functions inherited from cv::Algorithm

Return	Name	Description
static Ptr< _Tp >	load(     const String & filename,     const String & objname = String() )	Loads algorithm from the file.
static Ptr< _Tp >	loadFromString(     const String & strModel,     const String & objname = String() )	Loads algorithm from a String.
static Ptr< _Tp >	read(const FileNode & fn)	Reads algorithm from the file node.

Additional Inherited Members

Protected Member Functions inherited from cv::Algorithm

Return	Name	Description
void	writeFormat(FileStorage & fs)

Detailed Description

The class implements the Expectation Maximization algorithm.

See also

ml_intro_em

Member Enumeration Documentation

enum EM

Default parameters.

DEFAULT_NCLUSTERS

DEFAULT_MAX_ITERS

enum EM

The initial step.

START_E_STEP

START_M_STEP

START_AUTO_STEP

enum Types

Type of covariation matrices.

COV_MAT_SPHERICAL Python: cv.ml.EM_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 Python: cv.ml.EM_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 Python: cv.ml.EM_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 Python: cv.ml.EM_COV_MAT_DEFAULT

Member Function Documentation

getClustersNumber()

int cv::ml::EM::getClustersNumber()

Python:

cv.ml.EM.getClustersNumber() -> retval

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()

int cv::ml::EM::getCovarianceMatrixType()

Python:

cv.ml.EM.getCovarianceMatrixType() -> retval

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

See also

setCovarianceMatrixType

getCovs()

void cv::ml::EM::getCovs(std::vector< Mat > & covs)

Python:

cv.ml.EM.getCovs([, covs]) -> covs

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()

Mat cv::ml::EM::getMeans()

Python:

cv.ml.EM.getMeans() -> retval

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()

TermCriteria cv::ml::EM::getTermCriteria()

Python:

cv.ml.EM.getTermCriteria() -> retval

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()

Mat cv::ml::EM::getWeights()

Python:

cv.ml.EM.getWeights() -> retval

Returns weights of the mixtures.

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

predict()

float cv::ml::EM::predict(
InputArray samples,
OutputArray results = noArray(),
int flags = 0 )

Python:

cv.ml.EM.predict(samples[, results[, flags]]) -> retval, results

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

Here is the call graph for this function:

predict2()

Vec2d cv::ml::EM::predict2(
InputArray sample,
OutputArray probs )

Python:

cv.ml.EM.predict2(sample[, probs]) -> retval, probs

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

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.

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.

setClustersNumber()

void cv::ml::EM::setClustersNumber(int val)

Python:

cv.ml.EM.setClustersNumber(val)

See also

getClustersNumber

setCovarianceMatrixType()

void cv::ml::EM::setCovarianceMatrixType(int val)

Python:

cv.ml.EM.setCovarianceMatrixType(val)

See also

getCovarianceMatrixType

setTermCriteria()

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

Python:

cv.ml.EM.setTermCriteria(val)

See also

getTermCriteria

trainE()

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

Python:

cv.ml.EM.trainE(samples, means0[, covs0[, weights0[, logLikelihoods[, labels[, probs]]]]]) -> retval, logLikelihoods, labels, probs

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()

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

Python:

cv.ml.EM.trainEM(samples[, logLikelihoods[, labels[, probs]]]) -> retval, logLikelihoods, labels, probs

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()

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

Python:

cv.ml.EM.trainM(samples, probs0[, logLikelihoods[, labels[, probs]]]) -> retval, logLikelihoods, labels, probs

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 — the probabilities

• 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.

create()

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

Python:

cv.ml.EM.create() -> retval

cv.ml.EM_create() -> retval

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).

load()

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

Python:

cv.ml.EM.load(filepath[, nodeName]) -> retval

cv.ml.EM_load(filepath[, nodeName]) -> retval

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

Source file

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

• opencv2/ml.hpp