added a spec for the rvm_regression_trainer

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%402459

dlib/svm/rvm_abstract.h

@@ -135,6 +135,126 @@ namespace dlib
         provides a global swap
     !*/
 
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename kern_type 
+        >
+    class rvm_regression_trainer
+    {
+        /*!
+            REQUIREMENTS ON kern_type
+                is a kernel function object as defined in dlib/svm/kernel_abstract.h 
+
+            WHAT THIS OBJECT REPRESENTS
+                This object implements a trainer for a relevance vector machine for 
+                solving regression problems.
+
+                The implementation of the RVM training algorithm used by this object is based
+                on the following excellent paper:
+                    Tipping, M. E. and A. C. Faul (2003). Fast marginal likelihood maximisation 
+                    for sparse Bayesian models. In C. M. Bishop and B. J. Frey (Eds.), Proceedings 
+                    of the Ninth International Workshop on Artificial Intelligence and Statistics, 
+                    Key West, FL, Jan 3-6.
+        !*/
+
+    public:
+        typedef kern_type 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;
+
+        rvm_regression_trainer (
+        );
+        /*!
+            ensures
+                - This object is properly initialized and ready to be used
+                  to train a relevance vector machine.
+                - #get_epsilon() == 0.001
+        !*/
+
+        void set_kernel (
+            const kernel_type& k
+        );
+        /*!
+            ensures
+                - #get_kernel() == k 
+        !*/
+
+        const kernel_type& get_kernel (
+        ) const;
+        /*!
+            ensures
+                - returns a copy of the kernel function in use by this object
+        !*/
+
+        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.
+                  Generally a good value for this is 0.001.  Smaller values may result
+                  in a more accurate solution but take longer to execute.
+        !*/
+
+        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
+                - 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.
+                - x.nr() > 1
+                - x.nr() == y.nr() && x.nc() == 1 && y.nc() == 1 
+                  (i.e. x and y are both column vectors of the same length)
+            ensures
+                - trains a RVM given the training samples in x and 
+                  labels in y and returns the resulting decision_function.  
+            throws
+                - std::bad_alloc
+        !*/
+
+        void swap (
+            rvm_regression_trainer& item
+        );
+        /*!
+            ensures
+                - swaps *this and item
+        !*/
+
+    };  
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename K>
+    void swap (
+        rvm_regression_trainer<K>& a,
+        rvm_regression_trainer<K>& b
+    ) { a.swap(b); }
+    /*!
+        provides a global swap
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
 }