// 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_H__ #ifdef DLIB_SVM_C_LiNEAR_TRAINER_ABSTRACT_H__ #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 !*/ 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 !*/ 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 execute. !*/ 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() !*/ 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 ability 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 ability 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_binary_classification_problem(x,y) == true - x == a matrix or something convertible to a matrix via vector_to_matrix(). Also, x should contain sample_type objects. - y == a matrix or something convertible to a matrix via vector_to_matrix(). Also, y should contain scalar_type objects. 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_binary_classification_problem(x,y) == true - x == a matrix or something convertible to a matrix via vector_to_matrix(). Also, x should contain sample_type objects. - y == a matrix or something convertible to a matrix via vector_to_matrix(). Also, y should contain scalar_type objects. 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_H__