updated docs

modules/ml/doc/ertrees.rst

-Extremely randomized trees
-==========================
-
-Extremely randomized trees have been introduced by Pierre Geurts, Damien Ernst and Louis Wehenkel in the article "Extremely randomized trees", 2006 [http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.65.7485&rep=rep1&type=pdf]. The algorithm of growing Extremely randomized trees is similar to :ref:`Random Trees` (Random Forest), but there are two differences:
-
-#. Extremely randomized trees don't apply the bagging procedure to construct a set of the training samples for each tree. The same input training set is used to train all trees.
-
-#. Extremely randomized trees pick a node split very extremely (both a variable index and variable splitting value are chosen randomly), whereas Random Forest finds the best split (optimal one by variable index and variable splitting value) among random subset of variables.
-
-
-CvERTrees
-----------
-.. ocv:class:: CvERTrees : public CvRTrees
-
-    The class implements the Extremely randomized trees algorithm. ``CvERTrees`` is inherited from :ocv:class:`CvRTrees` and has the same interface, so see description of :ocv:class:`CvRTrees` class to get details. To set the training parameters of Extremely randomized trees the same class :ocv:struct:`CvRTParams` is used.

modules/ml/doc/expectation_maximization.rst

@@ -91,22 +91,23 @@ already a good enough approximation).
 
 EM
 --
-.. ocv:class:: EM : public Algorithm
+.. ocv:class:: EM : public StatModel
 
-The class implements the EM algorithm as described in the beginning of this section. It is inherited from :ocv:class:`Algorithm`.
+The class implements the EM algorithm as described in the beginning of this section.
 
+EM::Params
+----------
+.. ocv:class:: EM::Params
 
-EM::EM
-------
-The constructor of the class
+The class describes EM training parameters. It includes:
 
-.. ocv:function:: EM::EM(int nclusters=EM::DEFAULT_NCLUSTERS, int covMatType=EM::COV_MAT_DIAGONAL, const TermCriteria& termCrit=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, EM::DEFAULT_MAX_ITERS, FLT_EPSILON) )
+  .. ocv:member:: int clusters
   
-.. ocv:pyfunction:: cv2.EM([nclusters[, covMatType[, termCrit]]]) -> <EM object>
+    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.
 
-    :param nclusters: 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.
+  .. ocv:member:: int covMatType
 
-    :param covMatType: Constraint on covariance matrices which defines type of matrices. Possible values are:
+    Constraint on covariance matrices which defines type of matrices. Possible values are:
 
         * **EM::COV_MAT_SPHERICAL** A scaled identity matrix :math:`\mu_k * I`. There is the only parameter :math:`\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``.
 
@@ -114,23 +115,30 @@ The constructor of the class
 
         * **EM::COV_MAT_GENERIC** A symmetric positively defined matrix. The number of free parameters in each matrix is about :math:`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.
 
-    :param termCrit: 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``.
+  .. ocv:member:: TermCriteria termCrit
   
-EM::train
----------
-Estimates the Gaussian mixture parameters from a samples set.
+    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``.
+
+
+EM::create
+----------
+Creates empty EM model
 
-.. ocv:function:: bool EM::train(InputArray samples, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray())
+.. ocv:function:: Ptr<EM> EM::create(const Params& params=Params())
 
-.. ocv:function:: bool EM::trainE(InputArray samples, InputArray means0, InputArray covs0=noArray(), InputArray weights0=noArray(), OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray())
+    :param params: EM parameters
 
-.. ocv:function:: bool EM::trainM(InputArray samples, InputArray probs0, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray())
+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 ``StatModel::load<EM>(filename)``.     
+
+EM::train
+---------
+Static methods that estimate the Gaussian mixture parameters from a samples set
 
-.. ocv:pyfunction:: cv2.EM.train(samples[, logLikelihoods[, labels[, probs]]]) -> retval, logLikelihoods, labels, probs
+.. ocv:function:: Ptr<EM> EM::train(InputArray samples, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
 
-.. ocv:pyfunction:: cv2.EM.trainE(samples, means0[, covs0[, weights0[, logLikelihoods[, labels[, probs]]]]]) -> retval, logLikelihoods, labels, probs
+.. ocv:function:: bool EM::train_startWithE(InputArray samples, InputArray means0, InputArray covs0=noArray(), InputArray weights0=noArray(), OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
 
-.. ocv:pyfunction:: cv2.EM.trainM(samples, probs0[, logLikelihoods[, labels[, probs]]]) -> retval, logLikelihoods, labels, probs
+.. ocv:function:: bool EM::train_startWithM(InputArray samples, InputArray probs0, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
 
     :param 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.
 
@@ -148,6 +156,8 @@ Estimates the Gaussian mixture parameters from a samples set.
 
     :param probs: The optional output matrix that contains posterior probabilities of each Gaussian mixture component given the each sample. It has :math:`nsamples \times nclusters` size and ``CV_64FC1`` type.
     
+    :param params: The Gaussian mixture params, see ``EM::Params`` description above.
+
 Three versions of training method differ in the initialization of Gaussian mixture model parameters and start step:
 
 * **train** - Starts with Expectation step. Initial values of the model parameters will be estimated by the k-means algorithm.
@@ -167,15 +177,13 @@ Unlike many of the ML models, EM is an unsupervised learning algorithm and it do
 :math:`\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
-:ocv:class:`CvNormalBayesClassifier`.
+``NormalBayesClassifier``.
 
-EM::predict
------------
+EM::predict2
+------------
 Returns a likelihood logarithm value and an index of the most probable mixture component for the given sample.
 
-.. ocv:function:: Vec2d EM::predict(InputArray sample, OutputArray probs=noArray()) const
-
-.. ocv:pyfunction:: cv2.EM.predict(sample[, probs]) -> retval, probs
+.. ocv:function:: Vec2d EM::predict2(InputArray sample, OutputArray probs=noArray()) const
 
     :param sample: A sample for classification. It should be a one-channel matrix of :math:`1 \times dims` or :math:`dims \times 1` size.
 
@@ -183,28 +191,29 @@ Returns a likelihood logarithm value and an index of the most probable mixture c
 
 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.
 
-CvEM::isTrained
----------------
-Returns ``true`` if the Gaussian mixture model was trained.
 
-.. ocv:function:: bool EM::isTrained() const
+EM::getMeans
+------------
+Returns the cluster centers (means of the Gaussian mixture)
+
+.. ocv:function:: Mat EM::getMeans() const
+
+Returns matrix with the number of rows equal to the number of mixtures and number of columns equal to the space dimensionality.
+
+
+EM::getWeights
+--------------
+Returns weights of the mixtures
+
+.. ocv:function:: Mat EM::getWeights() const
 
-.. ocv:pyfunction:: cv2.EM.isTrained() -> retval
+Returns vector with the number of elements equal to the number of mixtures.
 
-EM::read, EM::write
--------------------
-See :ocv:func:`Algorithm::read` and :ocv:func:`Algorithm::write`.
 
-EM::get, EM::set
-----------------
-See :ocv:func:`Algorithm::get` and :ocv:func:`Algorithm::set`. The following parameters are available:
+EM::getCovs
+--------------
+Returns covariation matrices
 
-* ``"nclusters"``
-* ``"covMatType"``
-* ``"maxIters"``
-* ``"epsilon"``
-* ``"weights"`` *(read-only)*
-* ``"means"`` *(read-only)*
-* ``"covs"`` *(read-only)*
+.. ocv:function:: void EM::getCovs(std::vector<Mat>& covs) const
 
-..
+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.

modules/ml/doc/ml.rst

@@ -15,9 +15,7 @@ Most of the classification and regression algorithms are implemented as C++ clas
     support_vector_machines
     decision_trees
     boosting
-    gradient_boosted_trees
     random_trees
-    ertrees
     expectation_maximization
     neural_networks
     mldata

modules/ml/doc/normal_bayes_classifier.rst

@@ -9,55 +9,26 @@ This simple classification model assumes that feature vectors from each class ar
 
 .. [Fukunaga90] K. Fukunaga. *Introduction to Statistical Pattern Recognition*. second ed., New York: Academic Press, 1990.
 
-CvNormalBayesClassifier
+NormalBayesClassifier
 -----------------------
-.. ocv:class:: CvNormalBayesClassifier : public CvStatModel
+.. ocv:class:: NormalBayesClassifier : public StatModel
 
 Bayes classifier for normally distributed data.
 
-CvNormalBayesClassifier::CvNormalBayesClassifier
-------------------------------------------------
-Default and training constructors.
+NormalBayesClassifier::create
+-----------------------------
+Creates empty model
 
-.. ocv:function:: CvNormalBayesClassifier::CvNormalBayesClassifier()
+.. ocv:function:: Ptr<NormalBayesClassifier> NormalBayesClassifier::create(const NormalBayesClassifier::Params& params=Params())
 
-.. ocv:function:: CvNormalBayesClassifier::CvNormalBayesClassifier( const Mat& trainData, const Mat& responses, const Mat& varIdx=Mat(), const Mat& sampleIdx=Mat() )
+    :param params: The model parameters. There is none so far, the structure is used as a placeholder for possible extensions.
 
-.. ocv:function:: CvNormalBayesClassifier::CvNormalBayesClassifier( const CvMat* trainData, const CvMat* responses, const CvMat* varIdx=0, const CvMat* sampleIdx=0 )
+Use ``StatModel::train`` to train the model, ``StatModel::train<NormalBayesClassifier>(traindata, params)`` to create and train the model, ``StatModel::load<NormalBayesClassifier>(filename)`` to load the pre-trained model.
 
-.. ocv:pyfunction:: cv2.NormalBayesClassifier([trainData, responses[, varIdx[, sampleIdx]]]) -> <NormalBayesClassifier object>
-
-The constructors follow conventions of :ocv:func:`CvStatModel::CvStatModel`. See :ocv:func:`CvStatModel::train` for parameters descriptions.
-
-CvNormalBayesClassifier::train
-------------------------------
-Trains the model.
-
-.. ocv:function:: bool CvNormalBayesClassifier::train( const Mat& trainData, const Mat& responses, const Mat& varIdx = Mat(), const Mat& sampleIdx=Mat(), bool update=false )
-
-.. ocv:function:: bool CvNormalBayesClassifier::train( const CvMat* trainData, const CvMat* responses, const CvMat* varIdx = 0, const CvMat* sampleIdx=0, bool update=false )
-
-.. ocv:pyfunction:: cv2.NormalBayesClassifier.train(trainData, responses[, varIdx[, sampleIdx[, update]]]) -> retval
-
-    :param update: Identifies whether the model should be trained from scratch (``update=false``) or should be updated using the new training data (``update=true``).
-
-The method trains the Normal Bayes classifier. It follows the conventions of the generic :ocv:func:`CvStatModel::train` approach with the following limitations:
-
-* Only ``CV_ROW_SAMPLE`` data layout is supported.
-* Input variables are all ordered.
-* Output variable is categorical , which means that elements of ``responses`` must be integer numbers, though the vector may have the ``CV_32FC1`` type.
-* Missing measurements are not supported.
-
-CvNormalBayesClassifier::predict
---------------------------------
+NormalBayesClassifier::predictProb
+----------------------------------
 Predicts the response for sample(s).
 
-.. ocv:function:: float CvNormalBayesClassifier::predict(  const Mat& samples,  Mat* results=0, Mat* results_prob=0 ) const
-
-.. ocv:function:: float CvNormalBayesClassifier::predict( const CvMat* samples, CvMat* results=0, CvMat* results_prob=0 ) const
-
-.. ocv:pyfunction:: cv2.NormalBayesClassifier.predict(samples) -> retval, results
-
-The method estimates the most probable classes for input vectors. Input vectors (one or more) are stored as rows of the matrix ``samples``. In case of multiple input vectors, there should be one output vector ``results``. The predicted class for a single input vector is returned by the method. The vector ``results_prob`` contains the output probabilities coresponding to each element of ``result``.
+.. ocv:function:: float NormalBayesClassifier::predictProb( InputArray inputs, OutputArray outputs, OutputArray outputProbs, int flags=0 ) const
 
-The function is parallelized with the TBB library.
+The method estimates the most probable classes for input vectors. Input vectors (one or more) are stored as rows of the matrix ``inputs``. In case of multiple input vectors, there should be one output vector ``outputs``. The predicted class for a single input vector is returned by the method. The vector ``outputProbs`` contains the output probabilities corresponding to each element of ``result``.