Teh first one
[mldemos:kalians-mldemos.git] / _AlgorithmsPlugins / KernelMethods / dlib / svm / svm_c_linear_trainer_abstract.h
1 // Copyright (C) 2010  Davis E. King (davis@dlib.net)\r
2 // License: Boost Software License   See LICENSE.txt for the full license.\r
3 #undef DLIB_SVM_C_LiNEAR_TRAINER_ABSTRACT_H__\r
4 #ifdef DLIB_SVM_C_LiNEAR_TRAINER_ABSTRACT_H__\r
5 \r
6 #include "../matrix/matrix_abstract.h"\r
7 #include "../algs.h"\r
8 #include "function_abstract.h"\r
9 #include "kernel_abstract.h"\r
10 #include "sparse_kernel_abstract.h"\r
11 \r
12 namespace dlib\r
13 {\r
14     template <\r
15         typename K \r
16         >\r
17     class svm_c_linear_trainer\r
18     {\r
19         /*!\r
20             REQUIREMENTS ON K \r
21                 Is either linear_kernel or sparse_linear_kernel.  \r
22 \r
23             WHAT THIS OBJECT REPRESENTS\r
24                 This object represents a tool for training the C formulation of \r
25                 a support vector machine.  It is optimized for the case where\r
26                 linear kernels are used.  \r
27 \r
28 \r
29                 In particular, it is implemented using the OCAS algorithm\r
30                 described in the following paper:\r
31                     Optimized Cutting Plane Algorithm for Large-Scale Risk Minimization\r
32                         Vojtech Franc, Soren Sonnenburg; Journal of Machine Learning \r
33                         Research, 10(Oct):2157--2192, 2009. \r
34         !*/\r
35 \r
36     public:\r
37         typedef K kernel_type;\r
38         typedef typename kernel_type::scalar_type scalar_type;\r
39         typedef typename kernel_type::sample_type sample_type;\r
40         typedef typename kernel_type::mem_manager_type mem_manager_type;\r
41         typedef decision_function<kernel_type> trained_function_type;\r
42 \r
43         svm_c_linear_trainer (\r
44         );\r
45         /*!\r
46             ensures\r
47                 - This object is properly initialized and ready to be used\r
48                   to train a support vector machine.\r
49                 - #get_oca() == oca() (i.e. an instance of oca with default parameters) \r
50                 - #get_c_class1() == 1\r
51                 - #get_c_class2() == 1\r
52                 - #get_epsilon() == 0.001\r
53                 - this object will not be verbose unless be_verbose() is called\r
54         !*/\r
55 \r
56         explicit svm_c_linear_trainer (\r
57             const scalar_type& C \r
58         );\r
59         /*!\r
60             requires\r
61                 - C > 0\r
62             ensures\r
63                 - This object is properly initialized and ready to be used\r
64                   to train a support vector machine.\r
65                 - #get_oca() == oca() (i.e. an instance of oca with default parameters) \r
66                 - #get_c_class1() == C\r
67                 - #get_c_class2() == C\r
68                 - #get_epsilon() == 0.001\r
69                 - this object will not be verbose unless be_verbose() is called\r
70         !*/\r
71 \r
72         void set_epsilon (\r
73             scalar_type eps\r
74         );\r
75         /*!\r
76             requires\r
77                 - eps > 0\r
78             ensures\r
79                 - #get_epsilon() == eps \r
80         !*/\r
81 \r
82         const scalar_type get_epsilon (\r
83         ) const;\r
84         /*!\r
85             ensures\r
86                 - returns the error epsilon that determines when training should stop.\r
87                   Smaller values may result in a more accurate solution but take longer \r
88                   to execute.\r
89         !*/\r
90 \r
91         void be_verbose (\r
92         );\r
93         /*!\r
94             ensures\r
95                 - This object will print status messages to standard out so that a \r
96                   user can observe the progress of the algorithm.\r
97         !*/\r
98 \r
99         void be_quiet (\r
100         );\r
101         /*!\r
102             ensures\r
103                 - this object will not print anything to standard out\r
104         !*/\r
105 \r
106         void set_oca (\r
107             const oca& item\r
108         );\r
109         /*!\r
110             ensures\r
111                 - #get_oca() == item \r
112         !*/\r
113 \r
114         const oca get_oca (\r
115         ) const;\r
116         /*!\r
117             ensures\r
118                 - returns a copy of the optimizer used to solve the SVM problem.  \r
119         !*/\r
120 \r
121         const kernel_type get_kernel (\r
122         ) const;\r
123         /*!\r
124             ensures\r
125                 - returns a copy of the kernel function in use by this object.  Since\r
126                   the linear kernels don't have any parameters this function just\r
127                   returns kernel_type()\r
128         !*/\r
129 \r
130         void set_c (\r
131             scalar_type C \r
132         );\r
133         /*!\r
134             requires\r
135                 - C > 0\r
136             ensures\r
137                 - #get_c_class1() == C \r
138                 - #get_c_class2() == C \r
139         !*/\r
140 \r
141         const scalar_type get_c_class1 (\r
142         ) const;\r
143         /*!\r
144             ensures\r
145                 - returns the SVM regularization parameter for the +1 class.  \r
146                   It is the parameter that determines the trade off between\r
147                   trying to fit the +1 training data exactly or allowing more errors \r
148                   but hopefully improving the generalization ability of the \r
149                   resulting classifier.  Larger values encourage exact fitting \r
150                   while smaller values of C may encourage better generalization. \r
151         !*/\r
152 \r
153         const scalar_type get_c_class2 (\r
154         ) const;\r
155         /*!\r
156             ensures\r
157                 - returns the SVM regularization parameter for the -1 class.  \r
158                   It is the parameter that determines the trade off between\r
159                   trying to fit the -1 training data exactly or allowing more errors \r
160                   but hopefully improving the generalization ability of the \r
161                   resulting classifier.  Larger values encourage exact fitting \r
162                   while smaller values of C may encourage better generalization. \r
163         !*/\r
164 \r
165         void set_c_class1 (\r
166             scalar_type C\r
167         );\r
168         /*!\r
169             requires\r
170                 - C > 0\r
171             ensures\r
172                 - #get_c_class1() == C\r
173         !*/\r
174 \r
175         void set_c_class2 (\r
176             scalar_type C\r
177         );\r
178         /*!\r
179             requires\r
180                 - C > 0\r
181             ensures\r
182                 - #get_c_class2() == C\r
183         !*/\r
184 \r
185         template <\r
186             typename in_sample_vector_type,\r
187             typename in_scalar_vector_type\r
188             >\r
189         const decision_function<kernel_type> train (\r
190             const in_sample_vector_type& x,\r
191             const in_scalar_vector_type& y\r
192         ) const;\r
193         /*!\r
194             requires\r
195                 - is_binary_classification_problem(x,y) == true\r
196                 - x == a matrix or something convertible to a matrix via vector_to_matrix().\r
197                   Also, x should contain sample_type objects.\r
198                 - y == a matrix or something convertible to a matrix via vector_to_matrix().\r
199                   Also, y should contain scalar_type objects.\r
200             ensures\r
201                 - trains a C support vector classifier given the training samples in x and \r
202                   labels in y.  \r
203                 - returns a decision function F with the following properties:\r
204                     - F.alpha.size() == 1\r
205                     - F.basis_vectors.size() == 1\r
206                     - F.alpha(0) == 1\r
207                     - if (new_x is a sample predicted have +1 label) then\r
208                         - F(new_x) >= 0\r
209                     - else\r
210                         - F(new_x) < 0\r
211         !*/\r
212 \r
213         template <\r
214             typename in_sample_vector_type,\r
215             typename in_scalar_vector_type\r
216             >\r
217         const decision_function<kernel_type> train (\r
218             const in_sample_vector_type& x,\r
219             const in_scalar_vector_type& y,\r
220             scalar_type& svm_objective\r
221         ) const;\r
222         /*!\r
223             requires\r
224                 - is_binary_classification_problem(x,y) == true\r
225                 - x == a matrix or something convertible to a matrix via vector_to_matrix().\r
226                   Also, x should contain sample_type objects.\r
227                 - y == a matrix or something convertible to a matrix via vector_to_matrix().\r
228                   Also, y should contain scalar_type objects.\r
229             ensures\r
230                 - trains a C support vector classifier given the training samples in x and \r
231                   labels in y.  \r
232                 - #svm_objective == the final value of the SVM objective function\r
233                 - returns a decision function F with the following properties:\r
234                     - F.alpha.size() == 1\r
235                     - F.basis_vectors.size() == 1\r
236                     - F.alpha(0) == 1\r
237                     - if (new_x is a sample predicted have +1 label) then\r
238                         - F(new_x) >= 0\r
239                     - else\r
240                         - F(new_x) < 0\r
241         !*/\r
242 \r
243     }; \r
244 \r
245 }\r
246 \r
247 #endif // DLIB_SVM_C_LiNEAR_TRAINER_ABSTRACT_H__\r
248 \r