File: one_vs_all_trainer_abstract.h

package info (click to toggle)
mldemos 0.5.1-3
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 32,224 kB
  • ctags: 46,525
  • sloc: cpp: 306,887; ansic: 167,718; ml: 126; sh: 109; makefile: 2
file content (145 lines) | stat: -rw-r--r-- 5,350 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
// Copyright (C) 2010  Davis E. King (davis@dlib.net)
// License: Boost Software License   See LICENSE.txt for the full license.
#undef DLIB_ONE_VS_ALL_TRAiNER_ABSTRACT_H__
#ifdef DLIB_ONE_VS_ALL_TRAiNER_ABSTRACT_H__


#include "one_vs_all_decision_function_abstract.h"
#include <vector>

#include "../any/any_trainer_abstract.h"

namespace dlib
{

// ----------------------------------------------------------------------------------------

    template <
        typename any_trainer,
        typename label_type_ = double
        >
    class one_vs_all_trainer
    {
        /*!
            REQUIREMENTS ON any_trainer
                must be an instantiation of the dlib::any_trainer template.   

            REQUIREMENTS ON label_type_
                label_type_ must be default constructable, copyable, and comparable using
                operator < and ==.  It must also be possible to write it to an std::ostream
                using operator<<.

            WHAT THIS OBJECT REPRESENTS
                This object is a tool for turning a bunch of binary classifiers into a 
                multiclass classifier.  It does this by training the binary classifiers 
                in a one vs. all fashion.  That is, if you have N possible classes then 
                it trains N binary classifiers which are then used to vote on the identity 
                of a test sample.

                This object works with any kind of binary classification trainer object
                capable of being assigned to an any_trainer object.  (e.g. the svm_nu_trainer) 
        !*/

    public:


        typedef label_type_ label_type;

        typedef typename any_trainer::sample_type sample_type;
        typedef typename any_trainer::scalar_type scalar_type;
        typedef typename any_trainer::mem_manager_type mem_manager_type;

        typedef one_vs_all_decision_function<one_vs_all_trainer> trained_function_type;

        one_vs_all_trainer (
        );
        /*!
            ensures
                - this object is properly initialized
                - this object will not be verbose unless be_verbose() is called
                - no binary trainers are associated with *this.  I.e. you have to
                  call set_trainer() before calling train()
        !*/

        void set_trainer (
            const any_trainer& trainer
        );
        /*!
            ensures
                - sets the trainer used for all binary subproblems.  Any previous 
                  calls to set_trainer() are overridden by this function.  Even the
                  more specific set_trainer(trainer, l) form. 
        !*/

        void set_trainer (
            const any_trainer& trainer,
            const label_type& l
        );
        /*!
            ensures
                - Sets the trainer object used to create a binary classifier to
                  distinguish l labeled samples from all other samples.
        !*/

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

        struct invalid_label : public dlib::error 
        { 
            /*!
                This is the exception thrown by the train() function below.
            !*/
            label_type l;
        };

        trained_function_type train (
            const std::vector<sample_type>& all_samples,
            const std::vector<label_type>& all_labels
        ) const;
        /*!
            requires
                - is_learning_problem(all_samples, all_labels)
            ensures
                - trains a bunch of binary classifiers in a one vs all fashion to solve the given 
                  multiclass classification problem.  
                - returns a one_vs_all_decision_function F with the following properties:
                    - F contains all the learned binary classifiers and can be used to predict
                      the labels of new samples.
                    - if (new_x is a sample predicted to have a label of L) then
                        - F(new_x) == L
                    - F.get_labels() == select_all_distinct_labels(all_labels)
                    - F.number_of_classes() == select_all_distinct_labels(all_labels).size()
            throws
                - invalid_label
                  This exception is thrown if there are labels in all_labels which don't have
                  any corresponding trainer object.  This will never happen if set_trainer(trainer)
                  has been called.  However, if only the set_trainer(trainer,l) form has been
                  used then this exception is thrown if not all labels have been given a trainer.

                  invalid_label::l will contain the label which is missing a trainer object.  
                  Additionally, the exception will contain an informative error message available 
                  via invalid_label::what().
        !*/

    };

// ----------------------------------------------------------------------------------------

}

#endif // DLIB_ONE_VS_ALL_TRAiNER_ABSTRACT_H__