// Copyright (C) 2012  Davis E. King (davis@dlib.net)
// License: Boost Software License   See LICENSE.txt for the full license.

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

namespace dlib

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

    enum active_learning_mode

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

    template <
        typename kernel_type,
        typename in_sample_vector_type,
        typename in_scalar_vector_type,
        typename in_sample_vector_type2
    std::vector<unsigned long> rank_unlabeled_training_samples (
        const svm_c_linear_dcd_trainer<kernel_type>& trainer,
        const in_sample_vector_type& samples,
        const in_scalar_vector_type& labels,
        const in_sample_vector_type2& unlabeled_samples,
        const active_learning_mode mode = max_min_margin
            - if (samples.size() != 0) then
                - it must be legal to call trainer.train(samples, labels)
                - is_learning_problem(samples, labels) == true
            - unlabeled_samples must contain the same kind of vectors as samples.
            - unlabeled_samples, samples, and labels must be matrices or types of 
              objects convertible to a matrix via mat().
            - is_vector(unlabeled_samples) == true
            - Suppose that we wish to learn a binary classifier by calling
              trainer.train(samples, labels) but we are also interested in selecting one of
              the elements of unlabeled_samples to add to our training data.  Since doing
              this requires us to find out the label of the sample, a potentially tedious
              or expensive process, we would like to select the "best" element from
              unlabeled_samples for labeling.  The rank_unlabeled_training_samples()
              attempts to find this "best" element.  In particular, this function returns a
              ranked list of all the elements in unlabeled_samples such that that the
              "best" elements come first.
            - The method used by this function is described in the paper:
                Support Vector Machine Active Learning with Applications to Text Classification
                by Simon Tong and Daphne Koller
              In particular, this function implements the MaxMin Margin and Ratio Margin 
              selection strategies described in the paper.  Moreover, the mode argument
              to this function selects which of these strategies is used.
            - returns a std::vector V such that:
                - V contains a list of all the indices from unlabeled_samples.  Moreover,
                  they are ordered so that the most useful samples come first.
                - V.size() == unlabeled_samples.size()
                - unlabeled_samples[V[0]] == The best sample to add into the training set.
                - unlabeled_samples[V[1]] == The second best sample to add into the training set.
                - unlabeled_samples[V[i]] == The i-th best sample to add into the training set.

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