mirror of
https://github.com/opencv/opencv.git
synced 2026-07-29 23:33:05 +04:00
Improved docs of SVM
This commit is contained in:
Ilya Lysenkov
@@ -31,6 +31,68 @@ For details of implementation and various SVM formulations see:
|
||||
http://www.csie.ntu.edu.tw/~cjlin/papers/libsvm.pdf
|
||||
)
|
||||
|
||||
|
||||
CvParamGrid
|
||||
-----------
|
||||
.. ocv:class:: CvParamGrid
|
||||
|
||||
The structure represents the logarithmic grid range of statmodel parameters. It is used for optimizing statmodel accuracy by varying model parameters, the accuracy estimate being computed by cross-validation.
|
||||
|
||||
.. ocv:member:: double CvParamGrid::min_val
|
||||
|
||||
Minimum value of the statmodel parameter.
|
||||
|
||||
.. ocv:member:: double CvParamGrid::max_val
|
||||
|
||||
Maximum value of the statmodel parameter.
|
||||
|
||||
.. ocv:member:: double CvParamGrid::step
|
||||
|
||||
Logarithmic step for iterating the statmodel parameter.
|
||||
|
||||
The grid determines the following iteration sequence of the statmodel parameter values:
|
||||
|
||||
.. math::
|
||||
|
||||
(min\_val, min\_val*step, min\_val*{step}^2, \dots, min\_val*{step}^n),
|
||||
|
||||
where :math:`n` is the maximal index satisfying
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{min\_val} * \texttt{step} ^n < \texttt{max\_val}
|
||||
|
||||
The grid is logarithmic, so ``step`` must always be greater then 1.
|
||||
|
||||
CvParamGrid::CvParamGrid
|
||||
------------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: CvParamGrid::CvParamGrid()
|
||||
|
||||
.. ocv:function:: CvParamGrid::CvParamGrid( double min_val, double max_val, double log_step )
|
||||
|
||||
The full constructor initializes corresponding members. The default constructor creates a dummy grid:
|
||||
|
||||
::
|
||||
|
||||
CvParamGrid::CvParamGrid()
|
||||
{
|
||||
min_val = max_val = step = 0;
|
||||
}
|
||||
|
||||
CvParamGrid::check
|
||||
------------------
|
||||
Checks validness of the grid.
|
||||
|
||||
.. ocv:function:: bool CvParamGrid::check()
|
||||
|
||||
Returns ``true`` if the grid is valid and ``false`` otherwise. The grid is valid if and only if:
|
||||
|
||||
* Lower bound of the grid is less then the upper one.
|
||||
* Lower bound of the grid is positive.
|
||||
* Grid step is greater then 1.
|
||||
|
||||
CvSVMParams
|
||||
-----------
|
||||
.. ocv:class:: CvSVMParams
|
||||
@@ -45,7 +107,7 @@ The constructors.
|
||||
|
||||
.. ocv:function:: CvSVMParams::CvSVMParams()
|
||||
|
||||
.. ocv:function:: CvSVMParams::CvSVMParams( int svm_type, int kernel_type, double degree, double gamma, double coef0, double Cvalue, double nu, double p, CvMat* class_weights, CvTermCriteria term_crit );
|
||||
.. ocv:function:: CvSVMParams::CvSVMParams( int svm_type, int kernel_type, double degree, double gamma, double coef0, double Cvalue, double nu, double p, CvMat* class_weights, CvTermCriteria term_crit )
|
||||
|
||||
:param svm_type: Type of a SVM formulation. Possible values are:
|
||||
|
||||
@@ -97,76 +159,37 @@ CvSVM
|
||||
-----
|
||||
.. ocv:class:: CvSVM
|
||||
|
||||
Support Vector Machines. ::
|
||||
Support Vector Machines.
|
||||
|
||||
class CvSVM : public CvStatModel
|
||||
{
|
||||
public:
|
||||
// SVM type
|
||||
enum { C_SVC=100, NU_SVC=101, ONE_CLASS=102, EPS_SVR=103, NU_SVR=104 };
|
||||
CvSVM::CvSVM
|
||||
------------
|
||||
Default and training constructors.
|
||||
|
||||
// SVM kernel type
|
||||
enum { LINEAR=0, POLY=1, RBF=2, SIGMOID=3 };
|
||||
.. ocv:function:: CvSVM::CvSVM()
|
||||
|
||||
// SVM params type
|
||||
enum { C=0, GAMMA=1, P=2, NU=3, COEF=4, DEGREE=5 };
|
||||
.. ocv:function:: CvSVM::CvSVM( const Mat& trainData, const Mat& responses, const Mat& varIdx=Mat(), const Mat& sampleIdx=Mat(), CvSVMParams params=CvSVMParams() )
|
||||
|
||||
CvSVM();
|
||||
virtual ~CvSVM();
|
||||
|
||||
CvSVM( const Mat& _train_data, const Mat& _responses,
|
||||
const Mat& _var_idx=Mat(), const Mat& _sample_idx=Mat(),
|
||||
CvSVMParams _params=CvSVMParams() );
|
||||
|
||||
virtual bool train( const Mat& _train_data, const Mat& _responses,
|
||||
const Mat& _var_idx=Mat(), const Mat& _sample_idx=Mat(),
|
||||
CvSVMParams _params=CvSVMParams() );
|
||||
|
||||
virtual bool train_auto( const Mat& _train_data, const Mat& _responses,
|
||||
const Mat& _var_idx, const Mat& _sample_idx, CvSVMParams _params,
|
||||
int k_fold = 10,
|
||||
CvParamGrid C_grid = get_default_grid(CvSVM::C),
|
||||
CvParamGrid gamma_grid = get_default_grid(CvSVM::GAMMA),
|
||||
CvParamGrid p_grid = get_default_grid(CvSVM::P),
|
||||
CvParamGrid nu_grid = get_default_grid(CvSVM::NU),
|
||||
CvParamGrid coef_grid = get_default_grid(CvSVM::COEF),
|
||||
CvParamGrid degree_grid = get_default_grid(CvSVM::DEGREE) );
|
||||
|
||||
virtual float predict( const Mat& _sample ) const;
|
||||
virtual int get_support_vector_count() const;
|
||||
virtual const float* get_support_vector(int i) const;
|
||||
virtual CvSVMParams get_params() const { return params; };
|
||||
virtual void clear();
|
||||
|
||||
static CvParamGrid get_default_grid( int param_id );
|
||||
|
||||
virtual void save( const char* filename, const char* name=0 );
|
||||
virtual void load( const char* filename, const char* name=0 );
|
||||
|
||||
virtual void write( CvFileStorage* storage, const char* name );
|
||||
virtual void read( CvFileStorage* storage, CvFileNode* node );
|
||||
int get_var_count() const { return var_idx ? var_idx->cols : var_all; }
|
||||
|
||||
protected:
|
||||
...
|
||||
};
|
||||
.. ocv:cfunction:: CvSVM::CvSVM( const CvMat* trainData, const CvMat* responses, const CvMat* varIdx=0, const CvMat* sampleIdx=0, CvSVMParams params=CvSVMParams() )
|
||||
|
||||
The constructors follow conventions of :ocv:func:`CvStatModel::CvStatModel`. See :ocv:func:`CvStatModel::train` for parameters descriptions.
|
||||
|
||||
CvSVM::train
|
||||
------------
|
||||
Trains an SVM.
|
||||
|
||||
.. ocv:function:: bool CvSVM::train( const Mat& _train_data, const Mat& _responses, const Mat& _var_idx=Mat(), const Mat& _sample_idx=Mat(), CvSVMParams _params=CvSVMParams() )
|
||||
.. ocv:function:: bool CvSVM::train( const Mat& trainData, const Mat& responses, const Mat& varIdx=Mat(), const Mat& sampleIdx=Mat(), CvSVMParams params=CvSVMParams() )
|
||||
|
||||
.. ocv:cfunction:: bool CvSVM::train( const CvMat* trainData, const CvMat* responses, const CvMat* varIdx=0, const CvMat* sampleIdx=0, CvSVMParams params=CvSVMParams() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.CvSVM.train(trainData, responses[, varIdx[, sampleIdx[, params]]]) -> retval
|
||||
|
||||
The method trains the SVM model. It follows the conventions of the generic ``train`` approach with the following limitations:
|
||||
The method trains the SVM model. It follows the conventions of the generic :ocv:func:`CvStatModel::train` approach with the following limitations:
|
||||
|
||||
* Only the ``CV_ROW_SAMPLE`` data layout is supported.
|
||||
|
||||
* Input variables are all ordered.
|
||||
|
||||
* Output variables can be either categorical ( ``_params.svm_type=CvSVM::C_SVC`` or ``_params.svm_type=CvSVM::NU_SVC`` ), or ordered ( ``_params.svm_type=CvSVM::EPS_SVR`` or ``_params.svm_type=CvSVM::NU_SVR`` ), or not required at all ( ``_params.svm_type=CvSVM::ONE_CLASS`` ).
|
||||
* Output variables can be either categorical (``params.svm_type=CvSVM::C_SVC`` or ``params.svm_type=CvSVM::NU_SVC``), or ordered (``params.svm_type=CvSVM::EPS_SVR`` or ``params.svm_type=CvSVM::NU_SVR``), or not required at all (``params.svm_type=CvSVM::ONE_CLASS``).
|
||||
|
||||
* Missing measurements are not supported.
|
||||
|
||||
@@ -178,41 +201,49 @@ CvSVM::train_auto
|
||||
-----------------
|
||||
Trains an SVM with optimal parameters.
|
||||
|
||||
.. ocv:function:: train_auto( const Mat& _train_data, const Mat& _responses, const Mat& _var_idx, const Mat& _sample_idx, CvSVMParams params, int k_fold = 10, CvParamGrid C_grid = get_default_grid(CvSVM::C), CvParamGrid gamma_grid = get_default_grid(CvSVM::GAMMA), CvParamGrid p_grid = get_default_grid(CvSVM::P), CvParamGrid nu_grid = get_default_grid(CvSVM::NU), CvParamGrid coef_grid = get_default_grid(CvSVM::COEF), CvParamGrid degree_grid = get_default_grid(CvSVM::DEGREE) )
|
||||
.. ocv:function:: bool CvSVM::train_auto( const Mat& trainData, const Mat& responses, const Mat& varIdx, const Mat& sampleIdx, CvSVMParams params, int k_fold = 10, CvParamGrid Cgrid = CvSVM::get_default_grid(CvSVM::C), CvParamGrid gammaGrid = CvSVM::get_default_grid(CvSVM::GAMMA), CvParamGrid pGrid = CvSVM::get_default_grid(CvSVM::P), CvParamGrid nuGrid = CvSVM::get_default_grid(CvSVM::NU), CvParamGrid coeffGrid = CvSVM::get_default_grid(CvSVM::COEF), CvParamGrid degreeGrid = CvSVM::get_default_grid(CvSVM::DEGREE), bool balanced=false)
|
||||
|
||||
:param k_fold: Cross-validation parameter. The training set is divided into ``k_fold`` subsets. One subset is used to train the model, the others form the test set. So, the SVM algorithm is executed ``k_fold`` times.
|
||||
.. ocv:cfunction:: bool CvSVM::train_auto( const CvMat* trainData, const CvMat* responses, const CvMat* varIdx, const CvMat* sampleIdx, CvSVMParams params, int kfold = 10, CvParamGrid Cgrid = get_default_grid(CvSVM::C), CvParamGrid gammaGrid = get_default_grid(CvSVM::GAMMA), CvParamGrid pGrid = get_default_grid(CvSVM::P), CvParamGrid nuGrid = get_default_grid(CvSVM::NU), CvParamGrid coeffGrid = get_default_grid(CvSVM::COEF), CvParamGrid degreeGrid = get_default_grid(CvSVM::DEGREE), bool balanced=false )
|
||||
|
||||
:param k_fold: Cross-validation parameter. The training set is divided into ``k_fold`` subsets. One subset is used to train the model, the others form the test set. So, the SVM algorithm is executed ``k_fold`` times.
|
||||
|
||||
:param \*Grid: Iteration grid for the corresponding SVM parameter.
|
||||
|
||||
:param balanced: If ``true`` and the problem is 2-class classification then the method creates more balanced cross-validation subsets that is proportions between classes in subsets are close to such proportion in the whole train dataset.
|
||||
|
||||
The method trains the SVM model automatically by choosing the optimal
|
||||
parameters ``C`` , ``gamma`` , ``p`` , ``nu`` , ``coef0`` , ``degree`` from
|
||||
parameters ``C``, ``gamma``, ``p``, ``nu``, ``coef0``, ``degree`` from
|
||||
:ocv:class:`CvSVMParams`. Parameters are considered optimal
|
||||
when the cross-validation estimate of the test set error
|
||||
is minimal. The parameters are iterated by a logarithmic grid, for
|
||||
example, the parameter ``gamma`` takes values in the set
|
||||
(
|
||||
:math:`min`,
|
||||
:math:`min*step`,
|
||||
:math:`min*{step}^2` , ...
|
||||
:math:`min*{step}^n` )
|
||||
where
|
||||
:math:`min` is ``gamma_grid.min_val`` ,
|
||||
:math:`step` is ``gamma_grid.step`` , and
|
||||
:math:`n` is the maximal index where
|
||||
is minimal.
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{gamma\_grid.min\_val} * \texttt{gamma\_grid.step} ^n < \texttt{gamma\_grid.max\_val}
|
||||
|
||||
So ``step`` must always be greater than 1.
|
||||
|
||||
If there is no need to optimize a parameter, the corresponding grid step should be set to any value less than or equal to 1. For example, to avoid optimization in ``gamma`` , set ``gamma_grid.step = 0`` , ``gamma_grid.min_val`` , ``gamma_grid.max_val`` as arbitrary numbers. In this case, the value ``params.gamma`` is taken for ``gamma`` .
|
||||
If there is no need to optimize a parameter, the corresponding grid step should be set to any value less than or equal to 1. For example, to avoid optimization in ``gamma``, set ``gamma_grid.step = 0``, ``gamma_grid.min_val``, ``gamma_grid.max_val`` as arbitrary numbers. In this case, the value ``params.gamma`` is taken for ``gamma``.
|
||||
|
||||
And, finally, if the optimization in a parameter is required but
|
||||
the corresponding grid is unknown, you may call the function ``CvSVM::get_default_grid`` . To generate a grid, for example, for ``gamma`` , call ``CvSVM::get_default_grid(CvSVM::GAMMA)`` .
|
||||
the corresponding grid is unknown, you may call the function :ocv:func:`CvSVM::get_default_grid`. To generate a grid, for example, for ``gamma``, call :ocv:func:`CvSVM::get_default_grid(CvSVM::GAMMA)`.
|
||||
|
||||
This function works for the classification
|
||||
( ``params.svm_type=CvSVM::C_SVC`` or ``params.svm_type=CvSVM::NU_SVC`` )
|
||||
(``params.svm_type=CvSVM::C_SVC`` or ``params.svm_type=CvSVM::NU_SVC``)
|
||||
as well as for the regression
|
||||
( ``params.svm_type=CvSVM::EPS_SVR`` or ``params.svm_type=CvSVM::NU_SVR`` ). If ``params.svm_type=CvSVM::ONE_CLASS`` , no optimization is made and the usual SVM with parameters specified in ``params`` is executed.
|
||||
(``params.svm_type=CvSVM::EPS_SVR`` or ``params.svm_type=CvSVM::NU_SVR``). If ``params.svm_type=CvSVM::ONE_CLASS``, no optimization is made and the usual SVM with parameters specified in ``params`` is executed.
|
||||
|
||||
CvSVM::predict
|
||||
--------------
|
||||
Predicts the response for input sample(s).
|
||||
|
||||
.. ocv:function:: float CvSVM::predict( const Mat& sample, bool returnDFVal=false ) const
|
||||
|
||||
.. ocv:cfunction:: float CvSVM::predict( const CvMat* sample, bool returnDFVal=false ) const
|
||||
|
||||
.. ocv:cfunction:: float CvSVM::predict( const CvMat* samples, CvMat* results ) const
|
||||
|
||||
:param sample(s): Input sample(s) for prediction.
|
||||
|
||||
:param returnDFVal: Specifies a type of the return value. If ``true`` and the problem is 2-class classification then the method returns the decision function value that is signed distance to the margin, else the function returns a class label (classification) or estimated function value (regression).
|
||||
|
||||
:param results: Output prediction responses for corresponding samples.
|
||||
|
||||
If you pass one sample then prediction result is returned. If you want to get responses for several samples then you should pass the ``results`` matrix where prediction results will be stored.
|
||||
|
||||
CvSVM::get_default_grid
|
||||
-----------------------
|
||||
@@ -220,7 +251,7 @@ Generates a grid for SVM parameters.
|
||||
|
||||
.. ocv:function:: CvParamGrid CvSVM::get_default_grid( int param_id )
|
||||
|
||||
:param param_id: SVN parameters IDs that must be one of the following:
|
||||
:param param_id: SVM parameters IDs that must be one of the following:
|
||||
|
||||
* **CvSVM::C**
|
||||
|
||||
@@ -236,7 +267,7 @@ Generates a grid for SVM parameters.
|
||||
|
||||
The grid is generated for the parameter with this ID.
|
||||
|
||||
The function generates a grid for the specified parameter of the SVM algorithm. The grid may be passed to the function ``CvSVM::train_auto`` .
|
||||
The function generates a grid for the specified parameter of the SVM algorithm. The grid may be passed to the function :ocv:func:`CvSVM::train_auto`.
|
||||
|
||||
CvSVM::get_params
|
||||
-----------------
|
||||
@@ -244,7 +275,7 @@ Returns the current SVM parameters.
|
||||
|
||||
.. ocv:function:: CvSVMParams CvSVM::get_params() const
|
||||
|
||||
This function may be used to get the optimal parameters obtained while automatically training ``CvSVM::train_auto`` .
|
||||
This function may be used to get the optimal parameters obtained while automatically training :ocv:func:`CvSVM::train_auto`.
|
||||
|
||||
CvSVM::get_support_vector
|
||||
--------------------------
|
||||
@@ -254,5 +285,12 @@ Retrieves a number of support vectors and the particular vector.
|
||||
|
||||
.. ocv:function:: const float* CvSVM::get_support_vector(int i) const
|
||||
|
||||
:param i: Index of the particular support vector.
|
||||
|
||||
The methods can be used to retrieve a set of support vectors.
|
||||
|
||||
CvSVM::get_var_count
|
||||
--------------------
|
||||
Returns the number of used features (variables count).
|
||||
|
||||
.. ocv:function:: int CvSVM::get_var_count() const
|
||||
|
||||
Reference in New Issue
Block a user