1 // Copyright (C) 2008 Davis E. King (davis@dlib.net) 2 // License: Boost Software License See LICENSE.txt for the full license. 3 #undef DLIB_REDUCED_TRAINERs_ABSTRACT_ 4 #ifdef DLIB_REDUCED_TRAINERs_ABSTRACT_ 5 6 #include "../matrix.h" 7 #include "../algs.h" 8 #include "function_abstract.h" 9 #include "kernel_abstract.h" 10 #include "../optimization.h" 11 12 namespace dlib 13 { 14 15 // ---------------------------------------------------------------------------------------- 16 // ---------------------------------------------------------------------------------------- 17 // ---------------------------------------------------------------------------------------- 18 19 template < 20 typename trainer_type 21 > 22 class reduced_decision_function_trainer 23 { 24 /*! 25 REQUIREMENTS ON trainer_type 26 - trainer_type == some kind of batch trainer object (e.g. svm_nu_trainer) 27 28 WHAT THIS OBJECT REPRESENTS 29 This object represents an implementation of a reduced set algorithm. 30 This object acts as a post processor for anything that creates 31 decision_function objects. It wraps another trainer object and 32 performs this reduced set post processing with the goal of 33 representing the original decision function in a form that 34 involves fewer basis vectors. 35 !*/ 36 37 public: 38 typedef typename trainer_type::kernel_type kernel_type; 39 typedef typename trainer_type::scalar_type scalar_type; 40 typedef typename trainer_type::sample_type sample_type; 41 typedef typename trainer_type::mem_manager_type mem_manager_type; 42 typedef typename trainer_type::trained_function_type trained_function_type; 43 44 reduced_decision_function_trainer ( 45 ); 46 /*! 47 ensures 48 - This object is in an uninitialized state. You must 49 construct a real one with the other constructor and assign it 50 to this instance before you use this object. 51 !*/ 52 53 reduced_decision_function_trainer ( 54 const trainer_type& trainer, 55 const unsigned long num_bv 56 ); 57 /*! 58 requires 59 - num_bv > 0 60 ensures 61 - returns a trainer object that applies post processing to the decision_function 62 objects created by the given trainer object with the goal of creating 63 decision_function objects with fewer basis vectors. 64 - The reduced decision functions that are output will have at most 65 num_bv basis vectors. 66 !*/ 67 68 template < 69 typename in_sample_vector_type, 70 typename in_scalar_vector_type 71 > 72 const decision_function<kernel_type> train ( 73 const in_sample_vector_type& x, 74 const in_scalar_vector_type& y 75 ) const; 76 /*! 77 ensures 78 - trains a decision_function using the trainer that was supplied to 79 this object's constructor and then finds a reduced representation 80 for it and returns the reduced version. 81 throws 82 - std::bad_alloc 83 - any exceptions thrown by the trainer_type object 84 !*/ 85 86 }; 87 88 // ---------------------------------------------------------------------------------------- 89 90 template < 91 typename trainer_type 92 > reduced(const trainer_type & trainer,const unsigned long num_bv)93 const reduced_decision_function_trainer<trainer_type> reduced ( 94 const trainer_type& trainer, 95 const unsigned long num_bv 96 ) { return reduced_decision_function_trainer<trainer_type>(trainer, num_bv); } 97 /*! 98 requires 99 - num_bv > 0 100 - trainer_type == some kind of batch trainer object that creates decision_function 101 objects (e.g. svm_nu_trainer) 102 ensures 103 - returns a reduced_decision_function_trainer object that has been 104 instantiated with the given arguments. 105 !*/ 106 107 // ---------------------------------------------------------------------------------------- 108 // ---------------------------------------------------------------------------------------- 109 // ---------------------------------------------------------------------------------------- 110 111 template < 112 typename K, 113 typename stop_strategy_type, 114 typename T 115 > 116 distance_function<K> approximate_distance_function ( 117 stop_strategy_type stop_strategy, 118 const distance_function<K>& target, 119 const T& starting_basis 120 ); 121 /*! 122 requires 123 - stop_strategy == an object that defines a stop strategy such as one of 124 the objects from dlib/optimization/optimization_stop_strategies_abstract.h 125 - requirements on starting_basis 126 - T must be a dlib::matrix type or something convertible to a matrix via mat() 127 (e.g. a std::vector). Additionally, starting_basis must contain K::sample_type 128 objects which can be supplied to the kernel function used by target. 129 - is_vector(starting_basis) == true 130 - starting_basis.size() > 0 131 - target.get_basis_vectors().size() > 0 132 - kernel_derivative<K> is defined 133 (i.e. The analytic derivative for the given kernel must be defined) 134 - K::sample_type must be a dlib::matrix object and the basis_vectors inside target 135 and starting_basis must be column vectors. 136 ensures 137 - This routine attempts to find a distance_function object which is close 138 to the given target. That is, it searches for an X such that target(X) is 139 minimized. The optimization begins with an X in the span of the elements 140 of starting_basis and searches for an X which locally minimizes target(X). 141 Since this problem can have many local minima, the quality of the starting 142 basis can significantly influence the results. 143 - The optimization is over all variables in a distance_function, however, 144 the size of the basis set is constrained to no more than starting_basis.size(). 145 That is, in the returned distance_function DF, we will have: 146 - DF.get_basis_vectors().size() <= starting_basis.size() 147 - The optimization is carried out until the stop_strategy indicates it 148 should stop. 149 !*/ 150 151 // ---------------------------------------------------------------------------------------- 152 153 template < 154 typename trainer_type 155 > 156 class reduced_decision_function_trainer2 157 { 158 /*! 159 REQUIREMENTS ON trainer_type 160 - trainer_type == some kind of batch trainer object (e.g. svm_nu_trainer) 161 - trainer_type::sample_type must be a dlib::matrix object 162 - kernel_derivative<trainer_type::kernel_type> must be defined 163 164 WHAT THIS OBJECT REPRESENTS 165 This object represents an implementation of a reduced set algorithm. 166 This object acts as a post processor for anything that creates 167 decision_function objects. It wraps another trainer object and 168 performs this reduced set post processing with the goal of 169 representing the original decision function in a form that 170 involves fewer basis vectors. 171 172 This object's implementation is the same as that in the above 173 reduced_decision_function_trainer object except it also performs 174 a global gradient based optimization at the end to further 175 improve the approximation to the original decision function 176 object. 177 !*/ 178 179 public: 180 typedef typename trainer_type::kernel_type kernel_type; 181 typedef typename trainer_type::scalar_type scalar_type; 182 typedef typename trainer_type::sample_type sample_type; 183 typedef typename trainer_type::mem_manager_type mem_manager_type; 184 typedef typename trainer_type::trained_function_type trained_function_type; 185 186 reduced_decision_function_trainer2 ( 187 ); 188 /*! 189 ensures 190 - This object is in an uninitialized state. You must 191 construct a real one with the other constructor and assign it 192 to this instance before you use this object. 193 !*/ 194 195 reduced_decision_function_trainer2 ( 196 const trainer_type& trainer, 197 const unsigned long num_bv, 198 double eps = 1e-3 199 ); 200 /*! 201 requires 202 - num_bv > 0 203 - eps > 0 204 ensures 205 - returns a trainer object that applies post processing to the decision_function 206 objects created by the given trainer object with the goal of creating 207 decision_function objects with fewer basis vectors. 208 - The reduced decision functions that are output will have at most 209 num_bv basis vectors. 210 - the gradient based optimization will continue until the change in the 211 objective function is less than eps. So smaller values of eps will 212 give better results but take longer to compute. 213 !*/ 214 215 template < 216 typename in_sample_vector_type, 217 typename in_scalar_vector_type 218 > 219 const decision_function<kernel_type> train ( 220 const in_sample_vector_type& x, 221 const in_scalar_vector_type& y 222 ) const; 223 /*! 224 requires 225 - x must be a list of objects which are each some kind of dlib::matrix 226 which represents column or row vectors. 227 ensures 228 - trains a decision_function using the trainer that was supplied to 229 this object's constructor and then finds a reduced representation 230 for it and returns the reduced version. 231 throws 232 - std::bad_alloc 233 - any exceptions thrown by the trainer_type object 234 !*/ 235 236 }; 237 238 // ---------------------------------------------------------------------------------------- 239 240 template < 241 typename trainer_type 242 > 243 const reduced_decision_function_trainer2<trainer_type> reduced2 ( 244 const trainer_type& trainer, 245 const unsigned long num_bv, 246 double eps = 1e-3 247 ) { return reduced_decision_function_trainer2<trainer_type>(trainer, num_bv, eps); } 248 /*! 249 requires 250 - num_bv > 0 251 - trainer_type == some kind of batch trainer object that creates decision_function 252 objects (e.g. svm_nu_trainer) 253 - kernel_derivative<trainer_type::kernel_type> is defined 254 - eps > 0 255 ensures 256 - returns a reduced_decision_function_trainer2 object that has been 257 instantiated with the given arguments. 258 !*/ 259 260 // ---------------------------------------------------------------------------------------- 261 // ---------------------------------------------------------------------------------------- 262 // ---------------------------------------------------------------------------------------- 263 264 } 265 266 #endif // DLIB_REDUCED_TRAINERs_ABSTRACT_ 267 268