diff options
Diffstat (limited to 'ml/dlib/dlib/svm/svm_c_linear_trainer_abstract.h')
-rw-r--r-- | ml/dlib/dlib/svm/svm_c_linear_trainer_abstract.h | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/ml/dlib/dlib/svm/svm_c_linear_trainer_abstract.h b/ml/dlib/dlib/svm/svm_c_linear_trainer_abstract.h new file mode 100644 index 000000000..1b7a128f0 --- /dev/null +++ b/ml/dlib/dlib/svm/svm_c_linear_trainer_abstract.h @@ -0,0 +1,359 @@ +// Copyright (C) 2010 Davis E. King (davis@dlib.net) +// License: Boost Software License See LICENSE.txt for the full license. +#undef DLIB_SVM_C_LiNEAR_TRAINER_ABSTRACT_Hh_ +#ifdef DLIB_SVM_C_LiNEAR_TRAINER_ABSTRACT_Hh_ + +#include "../matrix/matrix_abstract.h" +#include "../algs.h" +#include "function_abstract.h" +#include "kernel_abstract.h" +#include "sparse_kernel_abstract.h" + +namespace dlib +{ + template < + typename K + > + class svm_c_linear_trainer + { + /*! + REQUIREMENTS ON K + Is either linear_kernel or sparse_linear_kernel. + + WHAT THIS OBJECT REPRESENTS + This object represents a tool for training the C formulation of + a support vector machine. It is optimized for the case where + linear kernels are used. + + + In particular, it is implemented using the OCAS algorithm + described in the following paper: + Optimized Cutting Plane Algorithm for Large-Scale Risk Minimization + Vojtech Franc, Soren Sonnenburg; Journal of Machine Learning + Research, 10(Oct):2157--2192, 2009. + !*/ + + public: + typedef K kernel_type; + typedef typename kernel_type::scalar_type scalar_type; + typedef typename kernel_type::sample_type sample_type; + typedef typename kernel_type::mem_manager_type mem_manager_type; + typedef decision_function<kernel_type> trained_function_type; + + svm_c_linear_trainer ( + ); + /*! + ensures + - This object is properly initialized and ready to be used + to train a support vector machine. + - #get_oca() == oca() (i.e. an instance of oca with default parameters) + - #get_c_class1() == 1 + - #get_c_class2() == 1 + - #get_epsilon() == 0.001 + - this object will not be verbose unless be_verbose() is called + - #get_max_iterations() == 10000 + - #learns_nonnegative_weights() == false + - #force_last_weight_to_1() == false + - #has_prior() == false + !*/ + + explicit svm_c_linear_trainer ( + const scalar_type& C + ); + /*! + requires + - C > 0 + ensures + - This object is properly initialized and ready to be used + to train a support vector machine. + - #get_oca() == oca() (i.e. an instance of oca with default parameters) + - #get_c_class1() == C + - #get_c_class2() == C + - #get_epsilon() == 0.001 + - this object will not be verbose unless be_verbose() is called + - #get_max_iterations() == 10000 + - #learns_nonnegative_weights() == false + - #force_last_weight_to_1() == false + - #has_prior() == false + !*/ + + void set_epsilon ( + scalar_type eps + ); + /*! + requires + - eps > 0 + ensures + - #get_epsilon() == eps + !*/ + + const scalar_type get_epsilon ( + ) const; + /*! + ensures + - returns the error epsilon that determines when training should stop. + Smaller values may result in a more accurate solution but take longer to + train. You can think of this epsilon value as saying "solve the + optimization problem until the probability of misclassification is within + epsilon of its optimal value". + !*/ + + void set_max_iterations ( + unsigned long max_iter + ); + /*! + ensures + - #get_max_iterations() == max_iter + !*/ + + unsigned long get_max_iterations ( + ); + /*! + ensures + - returns the maximum number of iterations the SVM optimizer is allowed to + run before it is required to stop and return a result. + !*/ + + void be_verbose ( + ); + /*! + ensures + - This object will print status messages to standard out so that a + user can observe the progress of the algorithm. + !*/ + + void be_quiet ( + ); + /*! + ensures + - this object will not print anything to standard out + !*/ + + void set_oca ( + const oca& item + ); + /*! + ensures + - #get_oca() == item + !*/ + + const oca get_oca ( + ) const; + /*! + ensures + - returns a copy of the optimizer used to solve the SVM problem. + !*/ + + const kernel_type get_kernel ( + ) const; + /*! + ensures + - returns a copy of the kernel function in use by this object. Since + the linear kernels don't have any parameters this function just + returns kernel_type() + !*/ + + bool learns_nonnegative_weights ( + ) const; + /*! + ensures + - The output of training is a weight vector and a bias value. These + two things define the resulting decision function. That is, the + decision function simply takes the dot product between the learned + weight vector and a test sample, then subtracts the bias value. + Therefore, if learns_nonnegative_weights() == true then the resulting + learned weight vector will always have non-negative entries. The + bias value may still be negative though. + !*/ + + void set_learns_nonnegative_weights ( + bool value + ); + /*! + ensures + - #learns_nonnegative_weights() == value + - if (value == true) then + - #has_prior() == false + !*/ + + void set_prior ( + const trained_function_type& prior + ); + /*! + requires + - prior == a function produced by a call to this class's train() function. + Therefore, it must be the case that: + - prior.basis_vectors.size() == 1 + - prior.alpha(0) == 1 + ensures + - Subsequent calls to train() will try to learn a function similar to the + given prior. + - #has_prior() == true + - #learns_nonnegative_weights() == false + - #forces_last_weight_to_1() == false + !*/ + + bool has_prior ( + ) const + /*! + ensures + - returns true if a prior has been set and false otherwise. Having a prior + set means that you have called set_prior() and supplied a previously + trained function as a reference. In this case, any call to train() will + try to learn a function that matches the behavior of the prior as close + as possible but also fits the supplied training data. In more technical + detail, having a prior means we replace the ||w||^2 regularizer with one + of the form ||w-prior||^2 where w is the set of parameters for a learned + function. + !*/ + + bool forces_last_weight_to_1 ( + ) const; + /*! + ensures + - returns true if this trainer has the constraint that the last weight in + the learned parameter vector must be 1. This is the weight corresponding + to the feature in the training vectors with the highest dimension. + - Forcing the last weight to 1 also disables the bias and therefore the b + field of the learned decision_function will be 0 when forces_last_weight_to_1() == true. + !*/ + + void force_last_weight_to_1 ( + bool should_last_weight_be_1 + ); + /*! + ensures + - #forces_last_weight_to_1() == should_last_weight_be_1 + - if (should_last_weight_be_1 == true) then + - #has_prior() == false + !*/ + + void set_c ( + scalar_type C + ); + /*! + requires + - C > 0 + ensures + - #get_c_class1() == C + - #get_c_class2() == C + !*/ + + const scalar_type get_c_class1 ( + ) const; + /*! + ensures + - returns the SVM regularization parameter for the +1 class. + It is the parameter that determines the trade off between + trying to fit the +1 training data exactly or allowing more errors + but hopefully improving the generalization of the resulting + classifier. Larger values encourage exact fitting while + smaller values of C may encourage better generalization. + !*/ + + const scalar_type get_c_class2 ( + ) const; + /*! + ensures + - returns the SVM regularization parameter for the -1 class. + It is the parameter that determines the trade off between + trying to fit the -1 training data exactly or allowing more errors + but hopefully improving the generalization of the resulting + classifier. Larger values encourage exact fitting while + smaller values of C may encourage better generalization. + !*/ + + void set_c_class1 ( + scalar_type C + ); + /*! + requires + - C > 0 + ensures + - #get_c_class1() == C + !*/ + + void set_c_class2 ( + scalar_type C + ); + /*! + requires + - C > 0 + ensures + - #get_c_class2() == C + !*/ + + template < + typename in_sample_vector_type, + typename in_scalar_vector_type + > + const decision_function<kernel_type> train ( + const in_sample_vector_type& x, + const in_scalar_vector_type& y + ) const; + /*! + requires + - is_learning_problem(x,y) == true + (Note that it is ok for x.size() == 1) + - All elements of y must be equal to +1 or -1 + - x == a matrix or something convertible to a matrix via mat(). + Also, x should contain sample_type objects. + - y == a matrix or something convertible to a matrix via mat(). + Also, y should contain scalar_type objects. + - if (has_prior()) then + - The vectors in x must have the same dimensionality as the vectors + used to train the prior given to set_prior(). + ensures + - trains a C support vector classifier given the training samples in x and + labels in y. + - returns a decision function F with the following properties: + - F.alpha.size() == 1 + - F.basis_vectors.size() == 1 + - F.alpha(0) == 1 + - if (new_x is a sample predicted have +1 label) then + - F(new_x) >= 0 + - else + - F(new_x) < 0 + !*/ + + template < + typename in_sample_vector_type, + typename in_scalar_vector_type + > + const decision_function<kernel_type> train ( + const in_sample_vector_type& x, + const in_scalar_vector_type& y, + scalar_type& svm_objective + ) const; + /*! + requires + - is_learning_problem(x,y) == true + (Note that it is ok for x.size() == 1) + - All elements of y must be equal to +1 or -1 + - x == a matrix or something convertible to a matrix via mat(). + Also, x should contain sample_type objects. + - y == a matrix or something convertible to a matrix via mat(). + Also, y should contain scalar_type objects. + - if (has_prior()) then + - The vectors in x must have the same dimensionality as the vectors + used to train the prior given to set_prior(). + ensures + - trains a C support vector classifier given the training samples in x and + labels in y. + - #svm_objective == the final value of the SVM objective function + - returns a decision function F with the following properties: + - F.alpha.size() == 1 + - F.basis_vectors.size() == 1 + - F.alpha(0) == 1 + - if (new_x is a sample predicted have +1 label) then + - F(new_x) >= 0 + - else + - F(new_x) < 0 + !*/ + + }; + +} + +#endif // DLIB_SVM_C_LiNEAR_TRAINER_ABSTRACT_Hh_ + |