fixed building html docs
authorVadim Pisarevsky <vadim.pisarevsky@gmail.com>
Sat, 2 Aug 2014 22:34:47 +0000 (02:34 +0400)
committerVadim Pisarevsky <vadim.pisarevsky@gmail.com>
Sat, 2 Aug 2014 22:34:47 +0000 (02:34 +0400)
modules/core/doc/basic_structures.rst
modules/ml/doc/boosting.rst
modules/ml/doc/decision_trees.rst
modules/ml/doc/expectation_maximization.rst
modules/ml/doc/mldata.rst
modules/ml/doc/random_trees.rst
modules/ml/doc/statistical_models.rst
modules/ml/doc/support_vector_machines.rst

index a94fa17..4f238df 100644 (file)
@@ -845,7 +845,6 @@ For convenience, the following types from the OpenCV C API already have such a s
 that calls the appropriate release function:
 
 * ``CvCapture``
-* :ocv:struct:`CvDTreeSplit`
 * :ocv:struct:`CvFileStorage`
 * ``CvHaarClassifierCascade``
 * :ocv:struct:`CvMat`
index 76a9293..2ba4a03 100644 (file)
@@ -79,7 +79,7 @@ The constructors.
 
 .. ocv:function:: Boost::Params::Params()
 
-.. ocv:function:: Boost::Params::Params( int boost_type, int weak_count, double weight_trim_rate, int max_depth, bool use_surrogates, const float* priors )
+.. ocv:function:: Boost::Params::Params( int boostType, int weakCount, double weightTrimRate, int maxDepth, bool useSurrogates, const Mat& priors )
 
     :param boost_type: Type of the boosting algorithm. Possible values are:
 
index 9400ae4..1cc9992 100644 (file)
@@ -53,7 +53,7 @@ Importance of each variable is computed over all the splits on this variable in
 
 
 DTrees::Split
-------------
+-------------
 .. ocv:class:: DTrees::Split
 
   The class represents split in a decision tree. It has public members:
@@ -91,7 +91,7 @@ DTrees::Split
           else next_node <- right
 
 DTrees::Node
------------
+------------
 .. ocv:class:: DTrees::Node
 
   The class represents a decision tree node. It has public members:
index 82450be..9b306fd 100644 (file)
@@ -66,7 +66,7 @@ Alternatively, the algorithm may start with the M-step when the initial values f
 :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}` . Often (including machine learning) the
-:ocv:func:`kmeans` algorithm is used for that purpose.
+``k-means`` algorithm is used for that purpose.
 
 One of the main problems of the EM algorithm is a large number
 of parameters to estimate. The majority of the parameters reside in
@@ -99,15 +99,17 @@ EM::Params
 ----------
 .. ocv:class:: EM::Params
 
-The class describes EM training parameters. It includes:
+The class describes EM training parameters.
 
-  .. ocv:member:: int clusters
-  
-    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.
+EM::Params::Params
+------------------
+The constructor
 
-  .. ocv:member:: int covMatType
+.. ocv:function:: EM::Params::Params( int nclusters=DEFAULT_NCLUSTERS, int covMatType=EM::COV_MAT_DIAGONAL,const TermCriteria& termCrit=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, EM::DEFAULT_MAX_ITERS, 1e-6))
 
-    Constraint on covariance matrices which defines type of matrices. Possible values are:
+    :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.
+
+    :param covMatType: 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``.
 
@@ -115,9 +117,7 @@ The class describes EM training parameters. It includes:
 
         * **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.
 
-  .. ocv:member:: TermCriteria 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``.
+    :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``.
 
 
 EM::create
index 8a3b796..9a795b6 100644 (file)
@@ -22,7 +22,7 @@ In machine learning algorithms there is notion of training data. Training data i
 As you can see, training data can have rather complex structure; besides, it may be very big and/or not entirely available, so there is need to make abstraction for this concept. In OpenCV ml there is ``cv::ml::TrainData`` class for that.
 
 TrainData
---------
+---------
 .. ocv:class:: TrainData
 
 Class encapsulating training data. Please note that the class only specifies the interface of training data, but not implementation. All the statistical model classes in ml take Ptr<TrainData>. In other words, you can create your own class derived from ``TrainData`` and supply smart pointer to the instance of this class into ``StatModel::train``.
@@ -31,7 +31,7 @@ TrainData::loadFromCSV
 ----------------------
 Reads the dataset from a .csv file and returns the ready-to-use training data.
 
-.. ocv:function:: Ptr<TrainData> loadFromCSV(const String& filename, int headerLineCount, int responseStartIdx=-1, int responseEndIdx=-1, const String& varTypeSpec=String(), char delimiter=',', char missch='?');
+.. ocv:function:: Ptr<TrainData> loadFromCSV(const String& filename, int headerLineCount, int responseStartIdx=-1, int responseEndIdx=-1, const String& varTypeSpec=String(), char delimiter=',', char missch='?')
 
     :param filename: The input file name
 
index 3b85126..951dfe7 100644 (file)
@@ -69,7 +69,7 @@ The constructors
 
     :param termCrit: The termination criteria that specifies when the training algorithm stops - either when the specified number of trees is trained and added to the ensemble or when sufficient accuracy (measured as OOB error) is achieved. Typically the more trees you have the better the accuracy. However, the improvement in accuracy generally diminishes and asymptotes pass a certain number of trees. Also to keep in mind, the number of tree increases the prediction time linearly.
 
-The default constructor sets all parameters to default values which are different from default values of :ocv:class:`CvDTreeParams`:
+The default constructor sets all parameters to default values which are different from default values of ``DTrees::Params``:
 
 ::
 
index af250b7..754b45e 100644 (file)
@@ -3,161 +3,110 @@ Statistical Models
 
 .. highlight:: cpp
 
-.. index:: CvStatModel
+.. index:: StatModel
 
-CvStatModel
+StatModel
 -----------
-.. ocv:class:: CvStatModel
+.. ocv:class:: StatModel
 
-Base class for statistical models in ML. ::
+Base class for statistical models in OpenCV ML.
 
-    class CvStatModel
-    {
-    public:
-        /* CvStatModel(); */
-        /* CvStatModel( const Mat& train_data ... ); */
 
-        virtual ~CvStatModel();
-
-        virtual void clear()=0;
-
-        /* virtual bool 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> ... )=0;
-          */
-
-        /* virtual float predict( const Mat& sample ... ) const=0; */
+StatModel::train
+------------------------
+Trains the statistical model
 
-        virtual void save( const char* filename, const char* name=0 )=0;
-        virtual void load( const char* filename, const char* name=0 )=0;
+.. ocv:function:: bool StatModel::train( const Ptr<TrainData>& trainData, int flags=0 )
 
-        virtual void write( CvFileStorage* storage, const char* name )=0;
-        virtual void read( CvFileStorage* storage, CvFileNode* node )=0;
-    };
+.. ocv:function:: bool StatModel::train( InputArray samples, int layout, InputArray responses )
 
+.. ocv:function:: Ptr<_Tp> StatModel::train(const Ptr<TrainData>& data, const _Tp::Params& p, int flags=0 )
 
-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.
+.. ocv:function:: Ptr<_Tp> StatModel::train(InputArray samples, int layout, InputArray responses, const _Tp::Params& p, int flags=0 )
 
-CvStatModel::CvStatModel
-------------------------
-The default constructor.
+    :param trainData: training data that can be loaded from file using ``TrainData::loadFromCSV`` or created with ``TrainData::create``.
+    
+    :param samples: training samples
+    
+    :param layout: ``ROW_SAMPLE`` (training samples are the matrix rows) or ``COL_SAMPLE`` (training samples are the matrix columns)
+    
+    :param responses: vector of responses associated with the training samples.
+    
+    :param p: the stat model parameters.
+    
+    :param flags: optional flags, depending on the model. Some of the models can be updated with the new training samples, not completely overwritten (such as ``NormalBayesClassifier`` or ``ANN_MLP``).
 
-.. ocv:function:: CvStatModel::CvStatModel()
+There are 2 instance methods and 2 static (class) template methods. The first two train the already created model (the very first method must be overwritten in the derived classes). And the latter two variants are convenience methods that construct empty model and then call its train method.
 
-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 :ocv:func:`CvStatModel::train` or :ocv:func:`CvStatModel::load`.
 
-CvStatModel::CvStatModel(...)
+StatModel::isTrained
 -----------------------------
-The training constructor.
+Returns true if the model is trained
 
-.. ocv:function:: CvStatModel::CvStatModel()
+.. ocv:function:: bool StatModel::isTrained()
 
-Most ML classes provide a single-step constructor and train constructors. This constructor is equivalent to the default constructor, followed by the :ocv:func:`CvStatModel::train` method with the parameters that are passed to the constructor.
+The method must be overwritten in the derived classes.
 
-CvStatModel::~CvStatModel
--------------------------
-The virtual destructor.
+StatModel::isClassifier
+-----------------------------
+Returns true if the model is classifier
 
-.. ocv:function:: CvStatModel::~CvStatModel()
+.. ocv:function:: bool StatModel::isClassifier()
 
-The destructor of the base class is declared as virtual. So, it is safe to write the following code: ::
+The method must be overwritten in the derived classes.
 
-    CvStatModel* model;
-    if( use_svm )
-        model = new CvSVM(... /* SVM params */);
-    else
-        model = new CvDTree(... /* Decision tree params */);
-    ...
-    delete model;
+StatModel::getVarCount
+-----------------------------
+Returns the number of variables in training samples
 
+.. ocv:function:: int StatModel::getVarCount()
 
-Normally, the destructor of each derived class does nothing. But in this instance, it calls the overridden method :ocv:func:`CvStatModel::clear` that deallocates all the memory.
+The method must be overwritten in the derived classes.
 
-CvStatModel::clear
+StatModel::predict
 ------------------
-Deallocates memory and resets the model state.
-
-.. ocv:function:: void 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 :ocv:func:`CvStatModel::train` methods of the derived classes, from the methods :ocv:func:`CvStatModel::load`, :ocv:func:`CvStatModel::read()`, or even explicitly by the user.
-
-CvStatModel::save
------------------
-Saves the model to a file.
-
-.. ocv:function:: void CvStatModel::save( const char* filename, const char* name=0 )
-
-.. ocv:pyfunction:: cv2.StatModel.save(filename[, name]) -> None
-
-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.
-
-CvStatModel::load
------------------
-Loads the model from a file.
-
-.. ocv:function:: void CvStatModel::load( const char* filename, const char* name=0 )
+Predicts response(s) for the provided sample(s)
 
-.. ocv:pyfunction:: cv2.StatModel.load(filename[, name]) -> None
+.. ocv:function:: float StatModel::predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const
 
-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 :ocv:func:`CvStatModel::clear`.
+    :param samples: The input samples, floating-point matrix
+    
+    :param results: The optional output matrix of results.
+    
+    :param flags: The optional flags, model-dependent. Some models, such as ``Boost``, ``SVM`` recognize ``StatModel::RAW_OUTPUT`` flag, which makes the method return the raw results (the sum), not the class label.
+    
 
+StatModel::calcError
+-------------------------
+Computes error on the training or test dataset
 
-CvStatModel::write
-------------------
-Writes the model to the file storage.
+.. ocv:function:: float StatModel::calcError( const Ptr<TrainData>& data, bool test, OutputArray resp ) const
 
-.. ocv:function:: void CvStatModel::write( CvFileStorage* storage, const char* name )
+    :param data: the training data
+    
+    :param test: if true, the error is computed over the test subset of the data, otherwise it's computed over the training subset of the data. Please note that if you loaded a completely different dataset to evaluate already trained classifier, you will probably want not to set the test subset at all with ``TrainData::setTrainTestSplitRatio`` and specify ``test=false``, so that the error is computed for the whole new set. Yes, this sounds a bit confusing.
 
-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 :ocv:func:`CvStatModel::save`.
+    :param resp: the optional output responses.
+    
+The method uses ``StatModel::predict`` to compute the error. For regression models the error is computed as RMS, for classifiers - as a percent of missclassified samples (0%-100%).
 
 
-CvStatModel::read
+StatModel::save
 -----------------
-Reads the model from the file storage.
-
-.. ocv:function:: void CvStatModel::read( CvFileStorage* storage, CvFileNode* node )
-
-The method ``read`` restores the complete model state from the specified node of the file storage. Use the function
-:ocv:cfunc:`GetFileNodeByName` to locate the node.
-
-The previous model state is cleared by :ocv:func:`CvStatModel::clear`.
-
-CvStatModel::train
-------------------
-Trains the model.
-
-.. 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> ... )
-
-The method trains the statistical model using a set of input feature vectors and the corresponding output values (responses). Both input and output vectors/values are passed as matrices. By default, the input feature vectors are stored as ``train_data`` rows, that is, all the components (features) of a training vector are stored continuously. However, some algorithms can handle the transposed representation when all values of each particular feature (component/input variable) over the whole input set are stored continuously. If both layouts are supported, the method includes the ``tflag`` parameter that specifies the orientation as follows:
-
-* ``tflag=CV_ROW_SAMPLE``     The feature vectors are stored as rows.
-
-* ``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 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:
-
-* ``CV_VAR_CATEGORICAL``     The output values are discrete class labels.
-
-* ``CV_VAR_ORDERED(=CV_VAR_NUMERICAL)``     The output values are ordered. This means that two different values can be compared as numbers, and this is a regression problem.
-
-Types of input variables can be also specified using ``var_type``. Most algorithms can handle only ordered input variables.
+Saves the model to a file.
 
-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.
+.. ocv:function:: void StatModel::save( const String& filename )
 
-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).
+In order to make this method work, the derived class must overwrite ``Algorithm::write(FileStorage& fs)``.
 
-Usually, the previous model state is cleared by :ocv:func:`CvStatModel::clear` before running the training procedure. However, some algorithms may optionally update the model state with the new training data, instead of resetting it.
+StatModel::load
+-----------------
+Loads model from the file
 
-CvStatModel::predict
---------------------
-Predicts the response for a sample.
+.. ocv:function:: Ptr<_Tp> StatModel::load( const String& filename )
 
-.. ocv:function:: float CvStatModel::predict( const Mat& sample, ... ) const
+This is static template method of StatModel. It's usage is following (in the case of SVM): ::
 
-The method is used to predict the response for a new sample. In case of a classification, the method returns the class label. In case of a regression, the method returns the output function value. The input sample must have as many components as the ``train_data`` passed to ``train`` contains. If the ``var_idx`` parameter is passed to ``train``, it is remembered and then is used to extract only the necessary components from the input sample in the method ``predict``.
+    Ptr<SVM> svm = StatModel::load<SVM>("my_svm_model.xml");
 
-The suffix ``const`` means that prediction does not affect the internal model state, so the method can be safely called from within different threads.
+In order to make this method work, the derived class must overwrite ``Algorithm::read(const FileNode& fn)``.
index 003ec4d..60724af 100644 (file)
@@ -181,7 +181,7 @@ Trains an SVM with optimal parameters.
 
 The method trains the SVM model automatically by choosing the optimal
 parameters ``C``, ``gamma``, ``p``, ``nu``, ``coef0``, ``degree`` from
-:ocv:class:`SVMParams`. Parameters are considered optimal
+``SVM::Params``. Parameters are considered optimal
 when the cross-validation estimate of the test set error
 is minimal.
 
@@ -226,7 +226,7 @@ Returns the current SVM parameters.
 
 .. ocv:function:: SVM::Params SVM::getParams() const
 
-This function may be used to get the optimal parameters obtained while automatically training :ocv:func:`SVM::train_auto`.
+This function may be used to get the optimal parameters obtained while automatically training ``SVM::trainAuto``.
 
 SVM::getSupportVectors
 --------------------------