Commit 8b6fe3b2 authored by Vadim Pisarevsky's avatar Vadim Pisarevsky

integrated grammar fixes from tech writer (part 2)

parent 0bd3d6d2
This diff is collapsed.
Expectation Maximization Expectation Maximization
======================== ========================
The EM (Expectation Maximization) algorithm estimates the parameters of the multivariate probability density function in the form of a Gaussian mixture distribution with a specified number of mixtures. .. highlight:: cpp
The Expectation Maximization(EM) algorithm estimates the parameters of the multivariate probability density function in the form of a Gaussian mixture distribution with a specified number of mixtures.
Consider the set of the N feature vectors Consider the set of the N feature vectors
{ :math:`x_1, x_2,...,x_{N}` } from a d-dimensional Euclidean space drawn from a Gaussian mixture: { :math:`x_1, x_2,...,x_{N}` } from a d-dimensional Euclidean space drawn from a Gaussian mixture:
...@@ -59,7 +61,7 @@ At the second step (Maximization step or M-step), the mixture parameter estimate ...@@ -59,7 +61,7 @@ At the second step (Maximization step or M-step), the mixture parameter estimate
Alternatively, the algorithm may start with the M-step when the initial values for Alternatively, the algorithm may start with the M-step when the initial values for
:math:`p_{i,k}` can be provided. Another alternative when :math:`p_{i,k}` can be provided. Another alternative when
:math:`p_{i,k}` are unknown is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial :math:`p_{i,k}` are unknown is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial
:math:`p_{i,k}` . Often (including ML) the :math:`p_{i,k}` . Often (including macnine learning) the
:ref:`kmeans` algorithm is used for that purpose. :ref:`kmeans` algorithm is used for that purpose.
One of the main problems of the EM algorithm is a large number One of the main problems of the EM algorithm is a large number
...@@ -83,22 +85,16 @@ already a good enough approximation). ...@@ -83,22 +85,16 @@ already a good enough approximation).
* *
Bilmes98 J. A. Bilmes. *A Gentle Tutorial of the EM Algorithm and its Application to Parameter Estimation for Gaussian Mixture and Hidden Markov Models*. Technical Report TR-97-021, International Computer Science Institute and Computer Science Division, University of California at Berkeley, April 1998. Bilmes98 J. A. Bilmes. *A Gentle Tutorial of the EM Algorithm and its Application to Parameter Estimation for Gaussian Mixture and Hidden Markov Models*. Technical Report TR-97-021, International Computer Science Institute and Computer Science Division, University of California at Berkeley, April 1998.
.. index:: CvEMParams
.. _CvEMParams:
CvEMParams CvEMParams
---------- ----------
.. c:type:: CvEMParams .. ocv:class:: CvEMParams
Parameters of the EM algorithm. Parameters of the EM algorithm.
All parameters are public. You can initialize them by a constructor and then override some of them directly if you want. All parameters are public. You can initialize them by a constructor and then override some of them directly if you want.
.. index:: CvEMParams::CvEMParams
.. _CvEMParams::CvEMParams:
CvEMParams::CvEMParams CvEMParams::CvEMParams
---------------------- ----------------------
...@@ -144,26 +140,16 @@ The default constructor represents a rough rule-of-the-thumb: ...@@ -144,26 +140,16 @@ The default constructor represents a rough rule-of-the-thumb:
With another contstructor it is possible to override a variety of parameters from a single number of mixtures (the only essential problem-dependent parameter) to initial values for the mixture parameters. With another contstructor it is possible to override a variety of parameters from a single number of mixtures (the only essential problem-dependent parameter) to initial values for the mixture parameters.
.. index:: CvEM
.. _CvEM:
CvEM CvEM
---- ----
.. c:type:: CvEM .. ocv:class:: CvEM
The EM model.
The class implements the EM algorithm as described in the beginning of this section.
.. index:: CvEM::train The class implements the EM algorithm as described in the beginning of this section.
.. _CvEM::train:
CvEM::train CvEM::train
----------- -----------
.. ocv:function:: void CvEM::train( const Mat& samples, const Mat& sample_idx=Mat(), CvEMParams params=CvEMParams(), Mat* labels=0 ) .. ocv:function:: void CvEM::train( const Mat& samples, const Mat& sample_idx=Mat(), CvEMParams params=CvEMParams(), Mat* labels=0 )
.. ocv:function:: bool CvEM::train( const CvMat* samples, const CvMat* sampleIdx=0, CvEMParams params=CvEMParams(), CvMat* labels=0 ) .. ocv:function:: bool CvEM::train( const CvMat* samples, const CvMat* sampleIdx=0, CvEMParams params=CvEMParams(), CvMat* labels=0 )
...@@ -177,20 +163,21 @@ CvEM::train ...@@ -177,20 +163,21 @@ CvEM::train
:param labels: The optional output "class label" for each sample: :math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (indices of the most probable mixture component for each sample). :param labels: The optional output "class label" for each sample: :math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (indices of the most probable mixture component for each sample).
Estimates the Gaussian mixture parameters from a sample set.
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 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: *Maximum Likelihood Estimate* of the Gaussian mixture parameters from an input sample set, stores all the parameters inside the structure:
:math:`p_{i,k}` in ``probs``, :math:`p_{i,k}` in ``probs``,
:math:`a_k` in ``means`` , :math:`a_k` in ``means`` ,
:math:`S_k` in ``covs[k]``, :math:`S_k` in ``covs[k]``,
:math:`\pi_k` in ``weights`` , :math:`\pi_k` in ``weights`` , and optionally computes the output "class label" for each sample:
:math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (indices of the most probable mixture for each sample).
The trained model can be used further for prediction, just like any other classifier. The trained model is similar to the The trained model can be used further for prediction, just like any other classifier. The trained model is similar to the
:ref:`Bayes classifier`. :ref:`Bayes classifier`.
For an example of clustering random samples of the multi-Gaussian distribution using EM, see ``em.cpp`` sample in the OpenCV distribution.
.. index:: CvEM::predict
.. _CvEM::predict:
CvEM::predict CvEM::predict
------------- -------------
...@@ -205,10 +192,6 @@ CvEM::predict ...@@ -205,10 +192,6 @@ CvEM::predict
:param probs: If it is not null then the method will write posterior probabilities of each component given the sample data to this parameter. :param probs: If it is not null then the method will write posterior probabilities of each component given the sample data to this parameter.
.. index:: CvEM::getNClusters
.. _CvEM::getNClusters:
CvEM::getNClusters CvEM::getNClusters
------------------ ------------------
.. ocv:function:: int CvEM::getNClusters() const .. ocv:function:: int CvEM::getNClusters() const
...@@ -218,10 +201,6 @@ CvEM::getNClusters ...@@ -218,10 +201,6 @@ CvEM::getNClusters
Returns the number of mixture components :math:`M` in the gaussian mixture model. Returns the number of mixture components :math:`M` in the gaussian mixture model.
.. index:: CvEM::getMeans
.. _CvEM::getMeans:
CvEM::getNClusters CvEM::getNClusters
------------------ ------------------
.. ocv:function:: Mat CvEM::getMeans() const .. ocv:function:: Mat CvEM::getMeans() const
...@@ -231,10 +210,6 @@ CvEM::getNClusters ...@@ -231,10 +210,6 @@ CvEM::getNClusters
Returns mixture means :math:`a_k`. Returns mixture means :math:`a_k`.
.. index:: CvEM::getCovs
.. _CvEM::getCovs:
CvEM::getCovs CvEM::getCovs
------------- -------------
.. ocv:function:: void CvEM::getCovs(std::vector<cv::Mat>& covs) const .. ocv:function:: void CvEM::getCovs(std::vector<cv::Mat>& covs) const
...@@ -244,10 +219,6 @@ CvEM::getCovs ...@@ -244,10 +219,6 @@ CvEM::getCovs
Returns mixture covariance matrices :math:`S_k`. Returns mixture covariance matrices :math:`S_k`.
.. index:: CvEM::getWeights
.. _CvEM::getWeights:
CvEM::getWeights CvEM::getWeights
---------------- ----------------
.. ocv:function:: Mat CvEM::getWeights() const .. ocv:function:: Mat CvEM::getWeights() const
...@@ -257,10 +228,6 @@ CvEM::getWeights ...@@ -257,10 +228,6 @@ CvEM::getWeights
Returns mixture weights :math:`\pi_k`. Returns mixture weights :math:`\pi_k`.
.. index:: CvEM::getProbs
.. _CvEM::getProbs:
CvEM::getProbs CvEM::getProbs
-------------- --------------
.. ocv:function:: Mat CvEM::getProbs() const .. ocv:function:: Mat CvEM::getProbs() const
...@@ -270,10 +237,6 @@ CvEM::getProbs ...@@ -270,10 +237,6 @@ CvEM::getProbs
Returns probabilites :math:`p_{i,k}` of sample :math:`i` to belong to a mixture component :math:`k`. Returns probabilites :math:`p_{i,k}` of sample :math:`i` to belong to a mixture component :math:`k`.
.. index:: CvEM::getLikelihood
.. _CvEM::getLikelihood:
CvEM::getLikelihood CvEM::getLikelihood
------------------- -------------------
.. ocv:function:: double CvEM::getLikelihood() const .. ocv:function:: double CvEM::getLikelihood() const
...@@ -283,10 +246,6 @@ CvEM::getLikelihood ...@@ -283,10 +246,6 @@ CvEM::getLikelihood
Returns logarithm of likelihood. Returns logarithm of likelihood.
.. index:: CvEM::getLikelihoodDelta
.. _CvEM::getLikelihoodDelta:
CvEM::getLikelihoodDelta CvEM::getLikelihoodDelta
------------------------ ------------------------
.. ocv:function:: double CvEM::getLikelihoodDelta() const .. ocv:function:: double CvEM::getLikelihoodDelta() const
...@@ -296,10 +255,6 @@ CvEM::getLikelihoodDelta ...@@ -296,10 +255,6 @@ CvEM::getLikelihoodDelta
Returns difference between logarithm of likelihood on the last iteration and logarithm of likelihood on the previous iteration. Returns difference between logarithm of likelihood on the last iteration and logarithm of likelihood on the previous iteration.
.. index:: CvEM::write_params
.. _CvEM::write_params:
CvEM::write_params CvEM::write_params
------------------ ------------------
.. ocv:function:: void CvEM::write_params( CvFileStorage* fs ) const .. ocv:function:: void CvEM::write_params( CvFileStorage* fs ) const
...@@ -309,10 +264,6 @@ CvEM::write_params ...@@ -309,10 +264,6 @@ CvEM::write_params
:param fs: A file storage where parameters will be written. :param fs: A file storage where parameters will be written.
.. index:: CvEM::read_params
.. _CvEM::read_params:
CvEM::read_params CvEM::read_params
----------------- -----------------
.. ocv:function:: void CvEM::read_params( CvFileStorage* fs, CvFileNode* node ) .. ocv:function:: void CvEM::read_params( CvFileStorage* fs, CvFileNode* node )
...@@ -329,4 +280,3 @@ Read parameters will be used for the EM algorithm in this ``CvEM`` object. ...@@ -329,4 +280,3 @@ Read parameters will be used for the EM algorithm in this ``CvEM`` object.
For example of clustering random samples of multi-Gaussian distribution using EM see em.cpp sample in OpenCV distribution. For example of clustering random samples of multi-Gaussian distribution using EM see em.cpp sample in OpenCV distribution.
...@@ -7,9 +7,9 @@ Statistical Models ...@@ -7,9 +7,9 @@ Statistical Models
CvStatModel CvStatModel
----------- -----------
.. c:type:: CvStatModel .. ocv:class:: CvStatModel
Base class for statistical models in ML :: Base class for statistical models in ML. ::
class CvStatModel class CvStatModel
{ {
...@@ -40,21 +40,13 @@ Base class for statistical models in ML :: ...@@ -40,21 +40,13 @@ Base class for statistical models in ML ::
In this declaration, some methods are commented off. These are methods for which there is no unified API (with the exception of the default constructor). However, there are many similarities in the syntax and semantics that are briefly described below in this section, as if they are part of the base class. In this declaration, some methods are commented off. These are methods for which there is no unified API (with the exception of the default constructor). However, there are many similarities in the syntax and semantics that are briefly described below in this section, as if they are part of the base class.
.. index:: CvStatModel::CvStatModel
.. _CvStatModel::CvStatModel:
CvStatModel::CvStatModel CvStatModel::CvStatModel
------------------------ ------------------------
.. ocv:function:: CvStatModel::CvStatModel() .. ocv:function:: CvStatModel::CvStatModel()
Serves as a default constructor. Serves as a default constructor.
Each statistical model class in ML has a default constructor without parameters. This constructor is useful for a 2-stage model construction, when the default constructor is followed by ``train()`` or ``load()`` . Each statistical model class in ML has a default constructor without parameters. This constructor is useful for a two-stage model construction, when the default constructor is followed by ``train()`` or ``load()`` .
.. index:: CvStatModel::CvStatModel(...)
.. _CvStatModel::CvStatModel(...):
CvStatModel::CvStatModel(...) CvStatModel::CvStatModel(...)
----------------------------- -----------------------------
...@@ -64,10 +56,6 @@ CvStatModel::CvStatModel(...) ...@@ -64,10 +56,6 @@ CvStatModel::CvStatModel(...)
Most ML classes provide a single-step constructor and train constructors. This constructor is equivalent to the default constructor, followed by the ``train()`` method with the parameters that are passed to the constructor. Most ML classes provide a single-step constructor and train constructors. This constructor is equivalent to the default constructor, followed by the ``train()`` method with the parameters that are passed to the constructor.
.. index:: CvStatModel::~CvStatModel
.. _CvStatModel::~CvStatModel:
CvStatModel::~CvStatModel CvStatModel::~CvStatModel
------------------------- -------------------------
.. ocv:function:: CvStatModel::~CvStatModel() .. ocv:function:: CvStatModel::~CvStatModel()
...@@ -87,10 +75,6 @@ The destructor of the base class is declared as virtual. So, it is safe to write ...@@ -87,10 +75,6 @@ The destructor of the base class is declared as virtual. So, it is safe to write
Normally, the destructor of each derived class does nothing. But in this instance, it calls the overridden method ``clear()`` that deallocates all the memory. Normally, the destructor of each derived class does nothing. But in this instance, it calls the overridden method ``clear()`` that deallocates all the memory.
.. index:: CvStatModel::clear
.. _CvStatModel::clear:
CvStatModel::clear CvStatModel::clear
------------------ ------------------
.. ocv:function:: void CvStatModel::clear() .. ocv:function:: void CvStatModel::clear()
...@@ -99,10 +83,6 @@ CvStatModel::clear ...@@ -99,10 +83,6 @@ CvStatModel::clear
The method ``clear`` does the same job as the destructor: it deallocates all the memory occupied by the class members. But the object itself is not destructed and can be reused further. This method is called from the destructor, from the ``train`` methods of the derived classes, from the methods ``load()``, ``read()``, or even explicitly by the user. The method ``clear`` does the same job as the destructor: it deallocates all the memory occupied by the class members. But the object itself is not destructed and can be reused further. This method is called from the destructor, from the ``train`` methods of the derived classes, from the methods ``load()``, ``read()``, or even explicitly by the user.
.. index:: CvStatModel::save
.. _CvStatModel::save:
CvStatModel::save CvStatModel::save
----------------- -----------------
.. ocv:function:: void CvStatModel::save( const char* filename, const char* name=0 ) .. ocv:function:: void CvStatModel::save( const char* filename, const char* name=0 )
...@@ -111,10 +91,6 @@ CvStatModel::save ...@@ -111,10 +91,6 @@ CvStatModel::save
The method ``save`` saves the complete model state to the specified XML or YAML file with the specified name or default name (which depends on a particular class). *Data persistence* functionality from ``CxCore`` is used. The method ``save`` saves the complete model state to the specified XML or YAML file with the specified name or default name (which depends on a particular class). *Data persistence* functionality from ``CxCore`` is used.
.. index:: CvStatModel::load
.. _CvStatModel::load:
CvStatModel::load CvStatModel::load
----------------- -----------------
.. ocv:function:: void CvStatModel::load( const char* filename, const char* name=0 ) .. ocv:function:: void CvStatModel::load( const char* filename, const char* name=0 )
...@@ -124,10 +100,6 @@ CvStatModel::load ...@@ -124,10 +100,6 @@ CvStatModel::load
The method ``load`` loads the complete model state with the specified name (or default model-dependent name) from the specified XML or YAML file. The previous model state is cleared by ``clear()`` . The method ``load`` loads the complete model state with the specified name (or default model-dependent name) from the specified XML or YAML file. The previous model state is cleared by ``clear()`` .
.. index:: CvStatModel::write
.. _CvStatModel::write:
CvStatModel::write CvStatModel::write
------------------ ------------------
.. ocv:function:: void CvStatModel::write( CvFileStorage* storage, const char* name ) .. ocv:function:: void CvStatModel::write( CvFileStorage* storage, const char* name )
...@@ -136,9 +108,6 @@ CvStatModel::write ...@@ -136,9 +108,6 @@ CvStatModel::write
The method ``write`` stores the complete model state in the file storage with the specified name or default name (which depends on the particular class). The method is called by ``save()`` . The method ``write`` stores the complete model state in the file storage with the specified name or default name (which depends on the particular class). The method is called by ``save()`` .
.. index:: CvStatModel::read
.. _CvStatModel::read:
CvStatModel::read CvStatModel::read
----------------- -----------------
...@@ -147,14 +116,10 @@ CvStatModel::read ...@@ -147,14 +116,10 @@ CvStatModel::read
Reads the model from the file storage. Reads the model from the file storage.
The method ``read`` restores the complete model state from the specified node of the file storage. Use the function The method ``read`` restores the complete model state from the specified node of the file storage. Use the function
:ref:`GetFileNodeByName` to locate the node. :ocv:func:`GetFileNodeByName` to locate the node.
The previous model state is cleared by ``clear()`` . The previous model state is cleared by ``clear()`` .
.. index:: CvStatModel::train
.. _CvStatModel::train:
CvStatModel::train CvStatModel::train
------------------ ------------------
.. ocv:function:: bool CvStatModel::train( const Mat& train_data, [int tflag,] ..., const Mat& responses, ..., [const Mat& var_idx,] ..., [const Mat& sample_idx,] ... [const Mat& var_type,] ..., [const Mat& missing_mask,] <misc_training_alg_params> ... ) .. ocv:function:: bool CvStatModel::train( const Mat& train_data, [int tflag,] ..., const Mat& responses, ..., [const Mat& var_idx,] ..., [const Mat& sample_idx,] ... [const Mat& var_type,] ..., [const Mat& missing_mask,] <misc_training_alg_params> ... )
...@@ -167,7 +132,7 @@ The method trains the statistical model using a set of input feature vectors and ...@@ -167,7 +132,7 @@ The method trains the statistical model using a set of input feature vectors and
* ``tflag=CV_COL_SAMPLE`` The feature vectors are stored as columns. * ``tflag=CV_COL_SAMPLE`` The feature vectors are stored as columns.
The ``train_data`` must have the ``CV_32FC1`` (32-bit floating-point, single-channel) format. Responses are usually stored in the 1D vector (a row or a column) of ``CV_32SC1`` (only in the classification problem) or ``CV_32FC1`` format, one value per input vector. Although, some algorithms, like various flavors of neural nets, take vector responses. The ``train_data`` must have the ``CV_32FC1`` (32-bit floating-point, single-channel) format. Responses are usually stored in a 1D vector (a row or a column) of ``CV_32SC1`` (only in the classification problem) or ``CV_32FC1`` format, one value per input vector. Although, some algorithms, like various flavors of neural nets, take vector responses.
For classification problems, the responses are discrete class labels. For regression problems, the responses are values of the function to be approximated. Some algorithms can deal only with classification problems, some - only with regression problems, and some can deal with both problems. In the latter case, the type of output variable is either passed as a separate parameter or as the last element of the ``var_type`` vector: For classification problems, the responses are discrete class labels. For regression problems, the responses are values of the function to be approximated. Some algorithms can deal only with classification problems, some - only with regression problems, and some can deal with both problems. In the latter case, the type of output variable is either passed as a separate parameter or as the last element of the ``var_type`` vector:
...@@ -177,16 +142,12 @@ For classification problems, the responses are discrete class labels. For regres ...@@ -177,16 +142,12 @@ For classification problems, the responses are discrete class labels. For regres
Types of input variables can be also specified using ``var_type`` . Most algorithms can handle only ordered input variables. Types of input variables can be also specified using ``var_type`` . Most algorithms can handle only ordered input variables.
Many models in the ML may be trained on a selected feature subset, and/or on a selected sample subset of the training set. To make it easier for you, the method ``train`` usually includes the ``var_idx`` and ``sample_idx`` parameters. The former parameter identifies variables (features) of interest, and the latter one identifies samples of interest. Both vectors are either integer ( ``CV_32SC1`` ) vectors (lists of 0-based indices) or 8-bit ( ``CV_8UC1`` ) masks of active variables/samples. You may pass ``NULL`` pointers instead of either of the arguments, meaning that all of the variables/samples are used for training. Many ML models may be trained on a selected feature subset, and/or on a selected sample subset of the training set. To make it easier for you, the method ``train`` usually includes the ``var_idx`` and ``sample_idx`` parameters. The former parameter identifies variables (features) of interest, and the latter one identifies samples of interest. Both vectors are either integer ( ``CV_32SC1`` ) vectors (lists of 0-based indices) or 8-bit ( ``CV_8UC1`` ) masks of active variables/samples. You may pass ``NULL`` pointers instead of either of the arguments, meaning that all of the variables/samples are used for training.
Additionally, some algorithms can handle missing measurements, that is, when certain features of certain training samples have unknown values (for example, they forgot to measure a temperature of patient A on Monday). The parameter ``missing_mask`` , an 8-bit matrix of the same size as ``train_data`` , is used to mark the missed values (non-zero elements of the mask). Additionally, some algorithms can handle missing measurements, that is, when certain features of certain training samples have unknown values (for example, they forgot to measure a temperature of patient A on Monday). The parameter ``missing_mask`` , an 8-bit matrix of the same size as ``train_data`` , is used to mark the missed values (non-zero elements of the mask).
Usually, the previous model state is cleared by ``clear()`` before running the training procedure. However, some algorithms may optionally update the model state with the new training data, instead of resetting it. Usually, the previous model state is cleared by ``clear()`` before running the training procedure. However, some algorithms may optionally update the model state with the new training data, instead of resetting it.
.. index:: CvStatModel::predict
.. _CvStatModel::predict:
CvStatModel::predict CvStatModel::predict
-------------------- --------------------
.. ocv:function:: float CvStatModel::predict( const Mat& sample[, <prediction_params>] ) const .. ocv:function:: float CvStatModel::predict( const Mat& sample[, <prediction_params>] ) const
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment