dlib C++ Library - svm_c_ekm_trainer_abstract.h

    // Copyright (C) 2010  Davis E. King (davis@dlib.net)
    // License: Boost Software License   See LICENSE.txt for the full license.
    #undef DLIB_SVM_C_EKm_TRAINER_ABSTRACT_Hh_
    #ifdef DLIB_SVM_C_EKm_TRAINER_ABSTRACT_Hh_

    #include "../algs.h"
    #include "function_abstract.h"
    #include "kernel_abstract.h"
    #include "empirical_kernel_map_abstract.h"
    #include "svm_c_linear_trainer_abstract.h"

    namespace dlib
    {
        template <
            typename K
            >
        class svm_c_ekm_trainer
        {
            /*!
                REQUIREMENTS ON K
                    is a kernel function object as defined in dlib/svm/kernel_abstract.h

                WHAT THIS OBJECT REPRESENTS
                    This object represents a tool for training the C formulation of
                    a support vector machine.   It is implemented using the empirical_kernel_map
                    to kernelize the svm_c_linear_trainer.  This makes it a very fast algorithm
                    capable of learning from very large datasets.
            !*/

        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_ekm_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
                    - #basis_loaded() == false
                    - #get_initial_basis_size() == 10
                    - #get_basis_size_increment() == 50
                    - #get_max_basis_size() == 300
                    - this object will not be verbose unless be_verbose() is called
                    - #get_max_iterations() == 10000
            !*/

            explicit svm_c_ekm_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
                    - #basis_loaded() == false
                    - #get_initial_basis_size() == 10
                    - #get_basis_size_increment() == 50
                    - #get_max_basis_size() == 300
                    - this object will not be verbose unless be_verbose() is called
                    - #get_max_iterations() == 10000
            !*/

            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 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_very_verbose (
            );
            /*!
                ensures
                    - This object will print a lot of status messages to standard out so that a
                      user can observe the progress of the algorithm.  In addition to the
                      few status messages normal verbosity produces this setting also causes
                      the underlying svm_c_linear_trainer to be verbose.
            !*/

            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
            !*/

            void set_kernel (
                const kernel_type& k
            );
            /*!
                ensures
                    - #get_kernel() == k
            !*/

            template <typename T>
            void set_basis (
                const T& basis_samples
            );
            /*!
                requires
                    - T must be a dlib::matrix type or something convertible to a matrix via mat()
                      (e.g. a std::vector)
                    - is_vector(basis_samples) == true
                    - basis_samples.size() > 0
                    - get_kernel() must be capable of operating on the elements of basis_samples.  That is,
                      expressions such as get_kernel()(basis_samples(0), basis_samples(0)) should make sense.
                ensures
                    - #basis_loaded() == true
                    - training will be carried out in the span of the given basis_samples
            !*/

            bool basis_loaded (
            ) const;
            /*!
                ensures
                    - returns true if this object has been loaded with user supplied basis vectors and false otherwise.
            !*/

            void clear_basis (
            );
            /*!
                ensures
                    - #basis_loaded() == false
            !*/

            unsigned long get_max_basis_size (
            ) const;
            /*!
                ensures
                    - returns the maximum number of basis vectors this object is allowed
                      to use.  This parameter only matters when the user has not supplied
                      a basis via set_basis().
            !*/

            void set_max_basis_size (
                unsigned long max_basis_size
            );
            /*!
                requires
                    - max_basis_size > 0
                ensures
                    - #get_max_basis_size() == max_basis_size
                    - if (get_initial_basis_size() > max_basis_size) then
                        - #get_initial_basis_size() == max_basis_size
            !*/

            unsigned long get_initial_basis_size (
            ) const;
            /*!
                ensures
                    - If the user does not supply a basis via set_basis() then this object
                      will generate one automatically.  It does this by starting with
                      a small basis of size N and repeatedly adds basis vectors to it
                      until a stopping condition is reached.  This function returns that
                      initial size N.
            !*/

            void set_initial_basis_size (
                unsigned long initial_basis_size
            );
            /*!
                requires
                    - initial_basis_size > 0
                ensures
                    - #get_initial_basis_size() == initial_basis_size
                    - if (initial_basis_size > get_max_basis_size()) then
                        - #get_max_basis_size() == initial_basis_size
            !*/

            unsigned long get_basis_size_increment (
            ) const;
            /*!
                ensures
                    - If the user does not supply a basis via set_basis() then this object
                      will generate one automatically.  It does this by starting with a small
                      basis and repeatedly adds sets of N basis vectors to it until a stopping
                      condition is reached.  This function returns that increment size N.
            !*/

            void set_basis_size_increment (
                unsigned long basis_size_increment
            );
            /*!
                requires
                    - basis_size_increment > 0
                ensures
                    - #get_basis_size_increment() == basis_size_increment
            !*/

            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 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.
                ensures
                    - trains a C support vector classifier given the training samples in x and
                      labels in y.
                    - if (basis_loaded()) then
                        - training will be carried out in the span of the user supplied basis vectors
                    - else
                        - this object will attempt to automatically select an appropriate basis

                    - returns a decision function F with the following properties:
                        - 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 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.
                ensures
                    - trains a C support vector classifier given the training samples in x and
                      labels in y.
                    - if (basis_loaded()) then
                        - training will be carried out in the span of the user supplied basis vectors
                    - else
                        - this object will attempt to automatically select an appropriate basis

                    - #svm_objective == the final value of the SVM objective function
                    - returns a decision function F with the following properties:
                        - if (new_x is a sample predicted have +1 label) then
                            - F(new_x) >= 0
                        - else
                            - F(new_x) < 0
            !*/

        };

    }

    #endif // DLIB_SVM_C_EKm_TRAINER_ABSTRACT_Hh_