Added structural_sequence_segmentation_trainer, test_sequence_segmenter(),

and cross_validate_sequence_segmenter()

dlib/svm.h

@@ -38,6 +38,7 @@
 #include "svm/cross_validate_regression_trainer.h"
 #include "svm/cross_validate_object_detection_trainer.h"
 #include "svm/cross_validate_sequence_labeler.h"
+#include "svm/cross_validate_sequence_segmenter.h"
 #include "svm/cross_validate_assignment_trainer.h"
 
 #include "svm/one_vs_all_decision_function.h"
@@ -50,6 +51,7 @@
 #include "svm/active_learning.h"
 #include "svm/svr_linear_trainer.h"
 #include "svm/sequence_segmenter.h"
+#include "svm/structural_sequence_segmentation_trainer.h"
 
 #endif // DLIB_SVm_HEADER
 

dlib/svm/cross_validate_sequence_segmenter.h

+// Copyright (C) 2013  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_CROSS_VALIDATE_SEQUENCE_sEGMENTER_H__
+#define DLIB_CROSS_VALIDATE_SEQUENCE_sEGMENTER_H__
+
+#include "cross_validate_sequence_segmenter_abstract.h"
+#include "sequence_segmenter.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    namespace impl
+    {
+        template <
+            typename sequence_segmenter_type,
+            typename sequence_type 
+            >
+        const matrix<double,1,3> raw_metrics_test_sequence_segmenter (
+            const sequence_segmenter_type& segmenter,
+            const std::vector<sequence_type>& samples,
+            const std::vector<std::vector<std::pair<unsigned long,unsigned long> > >& segments 
+        )
+        {
+            std::vector<std::pair<unsigned long,unsigned long> > truth;
+            std::vector<std::pair<unsigned long,unsigned long> > pred;
+
+            double true_hits = 0;
+            double total_detections = 0;
+            double total_true_segments = 0;
+
+            for (unsigned long i = 0; i < samples.size(); ++i)
+            {
+                segmenter.segment_sequence(samples[i], pred);
+                truth = segments[i];
+                // sort the segments so they will be in the same orders
+                std::sort(truth.begin(), truth.end());
+                std::sort(pred.begin(), pred.end());
+
+                total_true_segments += truth.size();
+                total_detections += pred.size();
+
+                unsigned long j=0,k=0;
+                while (j < pred.size() && k < truth.size())
+                {
+                    if (pred[j].first == truth[k].first && 
+                        pred[j].second == truth[k].second)
+                    {
+                        ++true_hits;
+                        ++j;
+                        ++k;
+                    }
+                    else if (pred[j].first < truth[k].first)
+                    {
+                        ++j;
+                    }
+                    else
+                    {
+                        ++k;
+                    }
+                }
+            }
+
+            matrix<double,1,3> res;
+            res = total_detections, total_true_segments, true_hits;
+            return res;
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename sequence_segmenter_type,
+        typename sequence_type 
+        >
+    const matrix<double,1,3> test_sequence_segmenter (
+        const sequence_segmenter_type& segmenter,
+        const std::vector<sequence_type>& samples,
+        const std::vector<std::vector<std::pair<unsigned long,unsigned long> > >& segments 
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT( is_sequence_segmentation_problem(samples, segments) == true,
+                    "\tmatrix test_sequence_segmenter()"
+                    << "\n\t invalid inputs were given to this function"
+                    << "\n\t is_sequence_segmentation_problem(samples, segments): " 
+                    << is_sequence_segmentation_problem(samples, segments));
+
+        const matrix<double,1,3> metrics = impl::raw_metrics_test_sequence_segmenter(segmenter, samples, segments);
+
+        const double total_detections    = metrics(0);
+        const double total_true_segments = metrics(1);
+        const double true_hits           = metrics(2);
+        
+        const double precision = (total_detections   ==0) ? 1 : true_hits/total_detections;
+        const double recall    = (total_true_segments==0) ? 1 : true_hits/total_true_segments;
+        const double f1        = (precision+recall   ==0) ? 0 : 2*precision*recall/(precision+recall);
+
+        matrix<double,1,3> res;
+        res = precision, recall, f1;
+        return res;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename trainer_type,
+        typename sequence_type 
+        >
+    const matrix<double,1,3> cross_validate_sequence_segmenter (
+        const trainer_type& trainer,
+        const std::vector<sequence_type>& samples,
+        const std::vector<std::vector<std::pair<unsigned long,unsigned long> > >& segments,
+        const long folds
+    )
+    {
+        // make sure requires clause is not broken
+        DLIB_ASSERT( is_sequence_segmentation_problem(samples, segments) == true &&
+                    1 < folds && folds <= static_cast<long>(samples.size()),
+                    "\tmatrix cross_validate_sequence_segmenter()"
+                    << "\n\t invalid inputs were given to this function"
+                    << "\n\t folds:  " << folds 
+                    << "\n\t is_sequence_segmentation_problem(samples, segments): " 
+                    << is_sequence_segmentation_problem(samples, segments));
+
+
+        const long num_in_test = samples.size()/folds;
+        const long num_in_train = samples.size() - num_in_test;
+
+        std::vector<sequence_type> x_test, x_train;
+        std::vector<std::vector<std::pair<unsigned long,unsigned long> > > y_test, y_train;
+
+        long next_test_idx = 0;
+
+        matrix<double,1,3> metrics;
+        metrics = 0;
+
+        for (long i = 0; i < folds; ++i)
+        {
+            x_test.clear();
+            y_test.clear();
+            x_train.clear();
+            y_train.clear();
+
+            // load up the test samples
+            for (long cnt = 0; cnt < num_in_test; ++cnt)
+            {
+                x_test.push_back(samples[next_test_idx]);
+                y_test.push_back(segments[next_test_idx]);
+                next_test_idx = (next_test_idx + 1)%samples.size();
+            }
+
+            // load up the training samples
+            long next = next_test_idx;
+            for (long cnt = 0; cnt < num_in_train; ++cnt)
+            {
+                x_train.push_back(samples[next]);
+                y_train.push_back(segments[next]);
+                next = (next + 1)%samples.size();
+            }
+
+
+            metrics += impl::raw_metrics_test_sequence_segmenter(trainer.train(x_train,y_train), x_test, y_test);
+        } // for (long i = 0; i < folds; ++i)
+
+
+        const double total_detections    = metrics(0);
+        const double total_true_segments = metrics(1);
+        const double true_hits           = metrics(2);
+        
+        const double precision = (total_detections   ==0) ? 1 : true_hits/total_detections;
+        const double recall    = (total_true_segments==0) ? 1 : true_hits/total_true_segments;
+        const double f1        = (precision+recall   ==0) ? 0 : 2*precision*recall/(precision+recall);
+
+        matrix<double,1,3> res;
+        res = precision, recall, f1;
+        return res;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_CROSS_VALIDATE_SEQUENCE_sEGMENTER_H__
+
+

dlib/svm/cross_validate_sequence_segmenter_abstract.h

+// Copyright (C) 2013  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_CROSS_VALIDATE_SEQUENCE_sEGMENTER_ABSTRACT_H__
+#ifdef DLIB_CROSS_VALIDATE_SEQUENCE_sEGMENTER_ABSTRACT_H__
+
+#include "sequence_segmenter_abstract.h"
+#include "../matrix.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename sequence_segmenter_type,
+        typename sequence_type 
+        >
+    const matrix<double,1,3> test_sequence_segmenter (
+        const sequence_segmenter_type& segmenter,
+        const std::vector<sequence_type>& samples,
+        const std::vector<std::vector<std::pair<unsigned long,unsigned long> > >& segments 
+    );
+    /*!
+        requires
+            - is_sequence_segmentation_problem(samples, segments) == true
+            - sequence_segmenter_type == dlib::sequence_segmenter or an object with a
+              compatible interface.
+        ensures
+            - Tests segmenter against the given samples and truth segments and returns the
+              precision, recall, and F1-score obtained by the segmenter.  That is, the goal
+              of the segmenter should be to predict segments[i] given samples[i] as input.
+              The test_sequence_segmenter() routine therefore measures how well the
+              segmenter is able to perform this task.
+            - Returns a row matrix M with the following properties:
+                - M(0) == The precision of the segmenter measured against the task of
+                  detecting the segments of each sample.  This is a number in the range 0
+                  to 1 and represents the fraction of segments output by the segmenter
+                  which correspond to true segments for each sample.
+                - M(1) == The recall of the segmenter measured against the task of
+                  detecting the segments of each sample.  This is a number in the range 0
+                  to 1 and represents the fraction of the true segments found by the
+                  segmenter. 
+                - M(2) == The F1-score for the segmenter.  This is the harmonic mean of
+                  M(0) and M(1).
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename trainer_type,
+        typename sequence_type 
+        >
+    const matrix<double,1,3> cross_validate_sequence_segmenter (
+        const trainer_type& trainer,
+        const std::vector<sequence_type>& samples,
+        const std::vector<std::vector<std::pair<unsigned long,unsigned long> > >& segments,
+        const long folds
+    );
+    /*!
+        requires
+            - is_sequence_segmentation_problem(samples, segments) == true
+            - 1 < folds <= samples.size()
+            - trainer_type == dlib::structural_sequence_segmentation_trainer or an object
+              with a compatible interface.
+        ensures
+            - Performs k-fold cross validation by using the given trainer to solve the
+              given sequence segmentation problem for the given number of folds.  Each fold
+              is tested using the output of the trainer and the results from all folds are
+              summarized and returned. 
+            - This function returns the precision, recall, and F1-score for the trainer.
+              In particular, the output is the same as the output from the
+              test_sequence_segmenter() routine defined above.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_CROSS_VALIDATE_SEQUENCE_sEGMENTER_ABSTRACT_H__
+

dlib/svm/structural_sequence_segmentation_trainer.h

+// Copyright (C) 2013  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_STRUCTURAL_SEQUENCE_sEGMENTATION_TRAINER_H__
+#define DLIB_STRUCTURAL_SEQUENCE_sEGMENTATION_TRAINER_H__
+
+#include "structural_sequence_segmentation_trainer_abstract.h"
+#include "structural_sequence_labeling_trainer.h"
+#include "sequence_segmenter.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    class structural_sequence_segmentation_trainer
+    {
+    public:
+        typedef typename feature_extractor::sequence_type sample_sequence_type;
+        typedef std::vector<std::pair<unsigned long, unsigned long> > segmented_sequence_type;
+
+        typedef sequence_segmenter<feature_extractor> trained_function_type;
+
+        explicit structural_sequence_segmentation_trainer (
+            const feature_extractor& fe_
+        ) : trainer(impl_ss::feature_extractor<feature_extractor>(fe_))
+        {
+        }
+
+        structural_sequence_segmentation_trainer (
+        )
+        {
+        }
+
+        const feature_extractor& get_feature_extractor (
+        ) const { return trainer.get_feature_extractor().fe; }
+
+        void set_num_threads (
+            unsigned long num
+        )
+        {
+            trainer.set_num_threads(num);
+        }
+
+        unsigned long get_num_threads (
+        ) const
+        {
+            return trainer.get_num_threads();
+        }
+
+        void set_epsilon (
+            double eps_
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(eps_ > 0,
+                "\t void structural_sequence_segmentation_trainer::set_epsilon()"
+                << "\n\t eps_ must be greater than 0"
+                << "\n\t eps_: " << eps_ 
+                << "\n\t this: " << this
+                );
+
+            trainer.set_epsilon(eps_);
+        }
+
+        double get_epsilon (
+        ) const { return trainer.get_epsilon(); }
+
+        void set_max_cache_size (
+            unsigned long max_size
+        )
+        {
+            trainer.set_max_cache_size(max_size);
+        }
+
+        unsigned long get_max_cache_size (
+        ) const
+        {
+            return trainer.get_max_cache_size();
+        }
+
+        void be_verbose (
+        )
+        {
+            trainer.be_verbose();
+        }
+
+        void be_quiet (
+        )
+        {
+            trainer.be_quiet();
+        }
+
+        void set_oca (
+            const oca& item
+        )
+        {
+            trainer.set_oca(item);
+        }
+
+        const oca get_oca (
+        ) const
+        {
+            return trainer.get_oca();
+        }
+
+        void set_c (
+            double C_ 
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(C_ > 0,
+                "\t void structural_sequence_segmentation_trainer::set_c()"
+                << "\n\t C_ must be greater than 0"
+                << "\n\t C_:    " << C_ 
+                << "\n\t this: " << this
+                );
+
+            trainer.set_c(C_);
+        }
+
+        double get_c (
+        ) const
+        {
+            return trainer.get_c();
+        }
+
+        const sequence_segmenter<feature_extractor> train(
+            const std::vector<sample_sequence_type>& x,
+            const std::vector<segmented_sequence_type>& y
+        ) const
+        {
+
+            // make sure requires clause is not broken
+            DLIB_ASSERT(is_sequence_segmentation_problem(x,y) == true,
+                        "\t sequence_segmenter structural_sequence_segmentation_trainer::train(x,y)"
+                        << "\n\t invalid inputs were given to this function"
+                        << "\n\t x.size(): " << x.size() 
+                        << "\n\t is_sequence_segmentation_problem(x,y): " << is_sequence_segmentation_problem(x,y)
+                        << "\n\t this: " << this
+            );
+
+            // convert y into tagged BIO labels
+            std::vector<std::vector<unsigned long> > labels(y.size());
+            for (unsigned long i = 0; i < labels.size(); ++i)
+            {
+                labels[i].resize(x[i].size(), impl_ss::OUTSIDE);
+                for (unsigned long j = 0; j < y[i].size(); ++j)
+                {
+                    const unsigned long begin = y[i][j].first;
+                    const unsigned long end = y[i][j].second;
+                    if (begin != end)
+                    {
+                        labels[i][begin] = impl_ss::BEGIN;
+                        for (unsigned long k = begin+1; k < end; ++k)
+                            labels[i][k] = impl_ss::INSIDE;
+                    }
+                }
+            }
+
+            sequence_labeler<impl_ss::feature_extractor<feature_extractor> > temp;
+            temp = trainer.train(x, labels);
+            return sequence_segmenter<feature_extractor>(temp.get_weights(), trainer.get_feature_extractor().fe);
+        }
+
+    private:
+
+        structural_sequence_labeling_trainer<impl_ss::feature_extractor<feature_extractor> > trainer;
+    };
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_STRUCTURAL_SEQUENCE_sEGMENTATION_TRAINER_H__
+

dlib/svm/structural_sequence_segmentation_trainer_abstract.h

+// Copyright (C) 2013  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_STRUCTURAL_SEQUENCE_sEGMENTATION_TRAINER_ABSTRACT_H__
+#ifdef DLIB_STRUCTURAL_SEQUENCE_sEGMENTATION_TRAINER_ABSTRACT_H__
+
+#include "sequence_segmenter_abstract.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename feature_extractor
+        >
+    class structural_sequence_segmentation_trainer
+    {
+        /*!
+            REQUIREMENTS ON feature_extractor
+                It must be an object that implements an interface compatible with 
+                the example_feature_extractor defined in dlib/svm/sequence_segmenter_abstract.h.
+
+            WHAT THIS OBJECT REPRESENTS
+                This object is a tool for learning to do sequence segmentation based on a
+                set of training data.  The training procedure produces a sequence_segmenter
+                object which can be used to identify the sub-segments of new data
+                sequences.
+
+                This object internally uses the structural_sequence_labeling_trainer to
+                solve the learning problem.  
+        !*/
+
+    public:
+
+        typedef typename feature_extractor::sequence_type sample_sequence_type;
+        typedef std::vector<std::pair<unsigned long, unsigned long> > segmented_sequence_type;
+
+        typedef sequence_segmenter<feature_extractor> trained_function_type;
+
+        structural_sequence_segmentation_trainer (
+        );
+        /*!
+            ensures
+                - #get_c() == 100
+                - this object isn't verbose
+                - #get_epsilon() == 0.1
+                - #get_num_threads() == 2
+                - #get_max_cache_size() == 40
+                - #get_feature_extractor() == a default initialized feature_extractor
+        !*/
+
+        explicit structural_sequence_segmentation_trainer (
+            const feature_extractor& fe
+        );
+        /*!
+            ensures
+                - #get_c() == 100
+                - this object isn't verbose
+                - #get_epsilon() == 0.1
+                - #get_num_threads() == 2
+                - #get_max_cache_size() == 40
+                - #get_feature_extractor() == fe 
+        !*/
+
+        const feature_extractor& get_feature_extractor (
+        ) const;
+        /*!
+            ensures
+                - returns the feature extractor used by this object
+        !*/
+
+        void set_num_threads (
+            unsigned long num
+        );
+        /*!
+            ensures
+                - #get_num_threads() == num
+        !*/
+
+        unsigned long get_num_threads (
+        ) const;
+        /*!
+            ensures
+                - returns the number of threads used during training.  You should 
+                  usually set this equal to the number of processing cores on your
+                  machine.
+        !*/
+
+        void set_epsilon (
+            double eps_
+        );
+        /*!
+            requires
+                - eps > 0
+            ensures
+                - #get_epsilon() == eps
+        !*/
+
+        double get_epsilon (
+        ) const; 
+        /*!
+            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 segmentation mistakes
+                  per training sample is within epsilon of its optimal value".
+        !*/
+
+        void set_max_cache_size (
+            unsigned long max_size
+        );
+        /*!
+            ensures
+                - #get_max_cache_size() == max_size
+        !*/
+
+        unsigned long get_max_cache_size (
+        ) const;
+        /*!
+            ensures
+                - During training, this object basically runs the sequence_segmenter on
+                  each training sample, over and over.  To speed this up, it is possible to
+                  cache the results of these segmenter 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.  
+        !*/
+
+        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
+        !*/
+
+        void set_oca (
+            const oca& item
+        );
+        /*!
+            ensures
+                - #get_oca() == item 
+        !*/
+
+        const oca get_oca (
+        ) const;
+        /*!
+            ensures
+                - returns a copy of the optimizer used to solve the structural SVM problem.  
+        !*/
+
+        void set_c (
+            double C
+        );
+        /*!
+            requires
+                - C > 0
+            ensures
+                - #get_c() = C
+        !*/
+
+        double get_c (
+        ) const;
+        /*!
+            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 sequence labeler.  Larger values
+                  encourage exact fitting while smaller values of C may encourage better
+                  generalization. 
+        !*/
+
+        const sequence_segmenter<feature_extractor> train(
+            const std::vector<sample_sequence_type>& x,
+            const std::vector<segmented_sequence_type>& y
+        ) const;
+        /*!
+            requires
+                - is_sequence_segmentation_problem(x, y) == true
+            ensures
+                - Uses the given training data to learn to do sequence segmentation.  That
+                  is, this function will try to find a sequence_segmenter capable of
+                  predicting y[i] when given x[i] as input.  Moreover, it should also be
+                  capable of predicting the segmentation of new input sequences.  Or in
+                  other words, the learned sequence_segmenter should also generalize to new
+                  data outside the training dataset.
+        !*/
+
+    };
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_STRUCTURAL_SEQUENCE_sEGMENTATION_TRAINER_ABSTRACT_H__
+