<html><!-- Created using the cpp_pretty_printer from the dlib C++ library. See http://dlib.net for updates. --><head><title>dlib C++ Library - structural_assignment_trainer_abstract.h</title></head><body bgcolor='white'><pre>
<font color='#009900'>// Copyright (C) 2011 Davis E. King (davis@dlib.net)
</font><font color='#009900'>// License: Boost Software License See LICENSE.txt for the full license.
</font><font color='#0000FF'>#undef</font> DLIB_STRUCTURAL_ASSiGNMENT_TRAINER_ABSTRACT_Hh_
<font color='#0000FF'>#ifdef</font> DLIB_STRUCTURAL_ASSiGNMENT_TRAINER_ABSTRACT_Hh_
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../algs.h.html'>../algs.h</a>"
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='structural_svm_assignment_problem.h.html'>structural_svm_assignment_problem.h</a>"
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='assignment_function_abstract.h.html'>assignment_function_abstract.h</a>"
<font color='#0000FF'>namespace</font> dlib
<b>{</b>
<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<font color='#0000FF'>template</font> <font color='#5555FF'><</font>
<font color='#0000FF'>typename</font> feature_extractor
<font color='#5555FF'>></font>
<font color='#0000FF'>class</font> <b><a name='structural_assignment_trainer'></a>structural_assignment_trainer</b>
<b>{</b>
<font color='#009900'>/*!
REQUIREMENTS ON feature_extractor
It must be an object that implements an interface compatible with
the example_feature_extractor defined in dlib/svm/assignment_function_abstract.h.
WHAT THIS OBJECT REPRESENTS
This object is a tool for learning to solve an assignment problem based
on a training dataset of example assignments. The training procedure produces an
assignment_function object which can be used to predict the assignments of
new data.
Note that this is just a convenience wrapper around the
structural_svm_assignment_problem to make it look
similar to all the other trainers in dlib.
!*/</font>
<font color='#0000FF'>public</font>:
<font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> feature_extractor::lhs_element lhs_element;
<font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> feature_extractor::rhs_element rhs_element;
<font color='#0000FF'>typedef</font> std::pair<font color='#5555FF'><</font>std::vector<font color='#5555FF'><</font>lhs_element<font color='#5555FF'>></font>, std::vector<font color='#5555FF'><</font>rhs_element<font color='#5555FF'>></font> <font color='#5555FF'>></font> sample_type;
<font color='#0000FF'>typedef</font> std::vector<font color='#5555FF'><</font><font color='#0000FF'><u>long</u></font><font color='#5555FF'>></font> label_type;
<font color='#0000FF'>typedef</font> assignment_function<font color='#5555FF'><</font>feature_extractor<font color='#5555FF'>></font> trained_function_type;
<b><a name='structural_assignment_trainer'></a>structural_assignment_trainer</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- #get_c() == 100
- this object isn't verbose
- #get_epsilon() == 0.01
- #get_num_threads() == 2
- #get_max_cache_size() == 5
- #get_feature_extractor() == a default initialized feature_extractor
- #forces_assignment() == false
- #get_loss_per_false_association() == 1
- #get_loss_per_missed_association() == 1
- #forces_last_weight_to_1() == false
!*/</font>
<font color='#0000FF'>explicit</font> <b><a name='structural_assignment_trainer'></a>structural_assignment_trainer</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'>const</font> feature_extractor<font color='#5555FF'>&</font> fe
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- #get_c() == 100
- this object isn't verbose
- #get_epsilon() == 0.01
- #get_num_threads() == 2
- #get_max_cache_size() == 40
- #get_feature_extractor() == fe
- #forces_assignment() == false
- #get_loss_per_false_association() == 1
- #get_loss_per_missed_association() == 1
- #forces_last_weight_to_1() == false
!*/</font>
<font color='#0000FF'>const</font> feature_extractor<font color='#5555FF'>&</font> <b><a name='get_feature_extractor'></a>get_feature_extractor</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns the feature extractor used by this object
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_num_threads'></a>set_num_threads</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> num
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- #get_num_threads() == num
!*/</font>
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> <b><a name='get_num_threads'></a>get_num_threads</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns the number of threads used during training. You should
usually set this equal to the number of processing cores on your
machine.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_epsilon'></a>set_epsilon</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>double</u></font> eps
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
requires
- eps > 0
ensures
- #get_epsilon() == eps
!*/</font>
<font color='#0000FF'><u>double</u></font> <b><a name='get_epsilon'></a>get_epsilon</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns the error epsilon that determines when training should stop.
Smaller values may result in a more accurate solution but take longer
to train. You can think of this epsilon value as saying "solve the
optimization problem until the average number of assignment mistakes per
training sample is within epsilon of its optimal value".
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_max_cache_size'></a>set_max_cache_size</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> max_size
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- #get_max_cache_size() == max_size
!*/</font>
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> <b><a name='get_max_cache_size'></a>get_max_cache_size</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- During training, this object basically runs the assignment_function on
each training sample, over and over. To speed this up, it is possible to
cache the results of these invocations. This function returns the number
of cache elements per training sample kept in the cache. Note that a value
of 0 means caching is not used at all.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_loss_per_false_association'></a>set_loss_per_false_association</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>double</u></font> loss
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
requires
- loss > 0
ensures
- #get_loss_per_false_association() == loss
!*/</font>
<font color='#0000FF'><u>double</u></font> <b><a name='get_loss_per_false_association'></a>get_loss_per_false_association</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns the amount of loss experienced for associating two objects
together that shouldn't be associated. If you care more about avoiding
accidental associations than ensuring all possible associations are
identified then then you can increase this value.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_loss_per_missed_association'></a>set_loss_per_missed_association</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>double</u></font> loss
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
requires
- loss > 0
ensures
- #get_loss_per_missed_association() == loss
!*/</font>
<font color='#0000FF'><u>double</u></font> <b><a name='get_loss_per_missed_association'></a>get_loss_per_missed_association</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns the amount of loss experienced for failing to associate two
objects that are supposed to be associated. If you care more about
getting all the associations than avoiding accidentally associating
objects that shouldn't be associated then you can increase this value.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='be_verbose'></a>be_verbose</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- This object will print status messages to standard out so that a
user can observe the progress of the algorithm.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='be_quiet'></a>be_quiet</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- this object will not print anything to standard out
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_oca'></a>set_oca</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'>const</font> oca<font color='#5555FF'>&</font> item
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- #get_oca() == item
!*/</font>
<font color='#0000FF'>const</font> oca <b><a name='get_oca'></a>get_oca</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns a copy of the optimizer used to solve the structural SVM problem.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_c'></a>set_c</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>double</u></font> C
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
requires
- C > 0
ensures
- #get_c() = C
!*/</font>
<font color='#0000FF'><u>double</u></font> <b><a name='get_c'></a>get_c</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns the SVM regularization parameter. It is the parameter
that determines the trade-off between trying to fit the training
data (i.e. minimize the loss) or allowing more errors but hopefully
improving the generalization of the resulting assignment_function.
Larger values encourage exact fitting while smaller values of C may
encourage better generalization.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='set_forces_assignment'></a>set_forces_assignment</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>bool</u></font> new_value
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- #forces_assignment() == new_value
!*/</font>
<font color='#0000FF'><u>bool</u></font> <b><a name='forces_assignment'></a>forces_assignment</b><font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns the value of the forces_assignment() parameter for the
assignment_functions generated by this object.
!*/</font>
<font color='#0000FF'><u>bool</u></font> <b><a name='forces_last_weight_to_1'></a>forces_last_weight_to_1</b> <font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
ensures
- returns true if this trainer has the constraint that the last weight in
the learned parameter vector must be 1. This is the weight corresponding
to the feature in the training vectors with the highest dimension.
- Forcing the last weight to 1 also disables the bias and therefore the
get_bias() field of the learned assignment_function will be 0 when
forces_last_weight_to_1() == true.
!*/</font>
<font color='#0000FF'><u>void</u></font> <b><a name='force_last_weight_to_1'></a>force_last_weight_to_1</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'><u>bool</u></font> should_last_weight_be_1
<font face='Lucida Console'>)</font>;
<font color='#009900'>/*!
ensures
- #forces_last_weight_to_1() == should_last_weight_be_1
!*/</font>
<font color='#0000FF'>const</font> assignment_function<font color='#5555FF'><</font>feature_extractor<font color='#5555FF'>></font> <b><a name='train'></a>train</b> <font face='Lucida Console'>(</font>
<font color='#0000FF'>const</font> std::vector<font color='#5555FF'><</font>sample_type<font color='#5555FF'>></font><font color='#5555FF'>&</font> samples,
<font color='#0000FF'>const</font> std::vector<font color='#5555FF'><</font>label_type<font color='#5555FF'>></font><font color='#5555FF'>&</font> labels
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
<font color='#009900'>/*!
requires
- is_assignment_problem(samples,labels) == true
- if (forces_assignment()) then
- is_forced_assignment_problem(samples,labels) == true
ensures
- Uses the structural_svm_assignment_problem to train an
assignment_function on the given samples/labels training pairs.
The idea is to learn to predict a label given an input sample.
- returns a function F with the following properties:
- F(new_sample) == A set of assignments indicating how the elements of
new_sample.first match up with the elements of new_sample.second.
- F.forces_assignment() == forces_assignment()
- F.get_feature_extractor() == get_feature_extractor()
- if (forces_last_weight_to_1()) then
- F.get_bias() == 0
- F.get_weights()(F.get_weights().size()-1) == 1
!*/</font>
<b>}</b>;
<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<b>}</b>
<font color='#0000FF'>#endif</font> <font color='#009900'>// DLIB_STRUCTURAL_ASSiGNMENT_TRAINER_ABSTRACT_Hh_
</font>
</pre></body></html>