model.H

Go to the documentation of this file.

// Copyright 2012, Google Inc.
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
// 
//   * Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
//   * Redistributions in binary form must reproduce the above
//     copyright notice, this list of conditions and the following disclaimer
//     in the documentation and/or other materials provided with the
//     distribution.
//   * Neither the name of Google Inc. nor the names of its
//     contributors may be used to endorse or promote products derived from
//     this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// -----------------------------------------------------------------------------
//
//

#ifndef RERANKER_MODEL_H_
#define RERANKER_MODEL_H_

#include <stdexcept>
#include <memory>
#include <vector>

#include "candidate-set.H"
#include "candidate-set-iterator.H"
#include "kernel-function.H"
#include "symbol-table.H"
#include "training-time.H"
#include "factory.H"

namespace reranker {

using std::vector;
using std::shared_ptr;

class DefaultScoreComparator : public Candidate::Comparator {
 public:
  virtual int Compare(const Model &model,
                      const Candidate &c1, const Candidate &c2) {
    double score_diff = c1.score() - c2.score();
    return score_diff == 0.0 ? 0 : (score_diff < 0.0 ? -1 : 1);
  }
};

class DefaultGoldComparator : public Candidate::Comparator {
 public:
  virtual int Compare(const Model &model,
                      const Candidate &c1, const Candidate &c2) {
    double loss_diff = c1.loss() - c2.loss();
    double score_diff = c1.score() - c2.score();
    // If c1 has "less loss" it is "better", so we return 1.
    if (loss_diff < 0.0) {
      return 1;
    } else if (loss_diff > 0.0) {
      return -1;
    } else {
      // If c1&rsquo;s and c2&rsquo;s losses are equal, we compare
      // them based on score, where a higher score is &ldquo;better&rdquo;
      // (meaning a positive return value).
      return score_diff == 0.0 ? 0 : (score_diff < 0.0 ? -1 : 1);
    }
  }
};

class DefaultCandidateSetScorer : public CandidateSet::Scorer {
 public:
  virtual void Score(Model *model,
                     CandidateSet &candidates, bool training);
};

class RandomPairCandidateSetScorer : public CandidateSet::Scorer {
 public:
  virtual void Init(const Environment *env, const string &arg);
  virtual void Score(Model *model,
                     CandidateSet &candidates, bool training);
 private:
  size_t GetRandomIndex(size_t max);
};

class Model : public FactoryConstructible {
 public:
  Model() : name_(""), time_(), kernel_fn_(NULL),
            symbols_(new LocalSymbolTable()),
            loss_per_epoch_(),
            num_testing_errors_per_epoch_(),
            num_training_errors_per_epoch_(),
            num_training_errors_(0), num_updates_(0),
            min_epochs_(-1), max_epochs_(-1),
            end_of_epoch_hook_(NULL) {  
    SetDefaultObjects();
  }


  Model(const string &name) :
      name_(name), time_(), kernel_fn_(NULL),
      symbols_(new LocalSymbolTable()),
      loss_per_epoch_(),
      num_testing_errors_per_epoch_(),
      num_training_errors_per_epoch_(),
      num_training_errors_(0), num_updates_(0),
      min_epochs_(-1), max_epochs_(-1),
      end_of_epoch_hook_(NULL) {
    SetDefaultObjects();
  }

  Model(const string &name, KernelFunction *kernel_fn) :
      name_(name), time_(), kernel_fn_(kernel_fn),
      symbols_(new LocalSymbolTable()),
      loss_per_epoch_(),
      num_testing_errors_per_epoch_(),
      num_training_errors_per_epoch_(),
      num_training_errors_(0),
      num_updates_(0),
      min_epochs_(-1), max_epochs_(-1),
      end_of_epoch_hook_(NULL) {
    SetDefaultObjects();
  }

  Model(const string &name, KernelFunction *kernel_fn,
        Symbols *symbols) :
      name_(name), time_(), kernel_fn_(kernel_fn),
      symbols_(symbols),
      loss_per_epoch_(),
      num_testing_errors_per_epoch_(),
      num_training_errors_per_epoch_(),
      num_training_errors_(0),
      num_updates_(0),
      min_epochs_(-1), max_epochs_(-1),
      end_of_epoch_hook_(NULL) {
    SetDefaultObjects();
  }

  virtual ~Model() {
    delete kernel_fn_;
    delete symbols_;
    delete end_of_epoch_hook_;
  }

  // inner interfaces

  class Hook {
   public:
    virtual ~Hook() { }
    virtual void Do(Model *model) = 0;
  };

  class UpdatePredicate : public FactoryConstructible {
   public:
    virtual bool NeedToUpdate(Model *model, CandidateSet &example) = 0;
  };

  class Updater : public FactoryConstructible {
   public:
    virtual void Update(Model *model, CandidateSet &example) = 0;
  };

  // accessors

  const string &name() const { return name_; }

  Symbols *symbols() const { return symbols_; }

  const Time &time() const { return time_; }

  virtual int best_model_epoch() const = 0;

  int num_updates() const { return num_updates_; }
  const vector<int> &num_training_errors_per_epoch() {
    return num_training_errors_per_epoch_;
  }
  int num_training_errors() const { return num_training_errors_; }

  int min_epochs() const { return min_epochs_; }

  int max_epochs() const { return max_epochs_; }

  const vector<double> &loss_per_epoch() { return loss_per_epoch_; }

  virtual const string &model_spec() const = 0;

  virtual const string &proto_reader_spec() const = 0;

  virtual const string &proto_writer_spec() const = 0;

  virtual shared_ptr<Candidate::Comparator> score_comparator() {
    return score_comparator_;
  }

  virtual shared_ptr<Candidate::Comparator> gold_comparator() {
    return gold_comparator_;
  }

  // training methods

  virtual bool NeedToKeepTraining()  = 0;

  // TODO(dbikel,kbhall): Add Train method that takes MapInput (or
  //                      Hadoop equivalent) for streaming input of
  //                      CandidateSet instances.

  virtual void Train(CandidateSetIterator &examples,
                     CandidateSetIterator &development_test) = 0;

  virtual void NewEpoch() = 0;

  virtual void EndOfEpoch() = 0;

  virtual void TrainOneEpoch(CandidateSetIterator &examples) = 0;

  virtual void TrainOnExample(CandidateSet &example) = 0;

  virtual bool NeedToUpdate(CandidateSet &example) = 0;

  virtual void Update(CandidateSet &example) = 0;

  virtual double Evaluate(CandidateSetIterator &development_test)
  = 0;

  virtual void ScoreCandidates(CandidateSet &candidates, bool training) = 0;

  virtual double ScoreCandidate(Candidate &candidate, bool training) = 0;

  // mutators

  virtual void set_min_epochs(int min_epochs) { min_epochs_ = min_epochs; }

  virtual void set_max_epochs(int max_epochs) { max_epochs_ = max_epochs; }

  virtual void CompactifyFeatureUids() = 0;

  virtual void set_end_of_epoch_hook(Hook *end_of_epoch_hook) {
    if (end_of_epoch_hook_ != NULL) {
      delete end_of_epoch_hook_;
    }
    end_of_epoch_hook_ = end_of_epoch_hook;
  }

  virtual bool use_weighted_loss() { return use_weighted_loss_; }

  virtual void set_use_weighted_loss(bool use_weighted_loss) {
    use_weighted_loss_ = use_weighted_loss;
  }

  virtual void set_symbols(Symbols *symbols) {
    delete symbols_;
    symbols_ = symbols;
  }

 protected:
  // more mutators (protected, because they should only be used by subclasses)

  void set_name(const string &name) { name_ = name; }

  void set_kernel_fn(KernelFunction *kernel_fn) {
    delete kernel_fn_;
    kernel_fn_ = kernel_fn;
  }

  void set_score_comparator(shared_ptr<Candidate::Comparator> score_comparator)
  {
    score_comparator_ = score_comparator;
  }

  void set_gold_comparator(shared_ptr<Candidate::Comparator> gold_comparator) {
    gold_comparator_ =  gold_comparator;
  }

  void SetDefaultObjects() {
    SetDefaultComparators();
    SetDefaultCandidateSetScorer();
  }

  void SetDefaultComparators() {
    score_comparator_ = GetComparator("DefaultScoreComparator()");
    gold_comparator_ = GetComparator("DefaultGoldComparator()");
  }

  void SetDefaultCandidateSetScorer() {
    candidate_set_scorer_ =
        GetCandidateSetScorer("DefaultCandidateSetScorer()");
  }

  shared_ptr<Candidate::Comparator> GetComparator(const string &spec) const;

  shared_ptr<CandidateSet::Scorer> GetCandidateSetScorer(const string &spec)
      const;

  shared_ptr<UpdatePredicate> GetUpdatePredicate(const string &spec) const;

  shared_ptr<Updater> GetUpdater(const string &spec) const;

  virtual void CheckNumberOfTokens(const string &arg,
                                   const vector<string> &tokens,
                                   size_t min_expected_number,
                                   size_t max_expected_number,
                                   const string &class_name) const;

  string name_;
  Time time_;
  KernelFunction *kernel_fn_;
  Symbols *symbols_;
  shared_ptr<Candidate::Comparator> score_comparator_;
  shared_ptr<Candidate::Comparator> gold_comparator_;
  shared_ptr<CandidateSet::Scorer> candidate_set_scorer_;
  shared_ptr<UpdatePredicate> update_predicate_;
  shared_ptr<Updater> updater_;
  vector<double> loss_per_epoch_;
  vector<int> num_testing_errors_per_epoch_;
  vector<int> num_training_errors_per_epoch_;
  int num_training_errors_;
  int num_updates_;
  int min_epochs_;
  int max_epochs_;
  Hook *end_of_epoch_hook_;
  bool use_weighted_loss_;
};

#define REGISTER_NAMED_MODEL(TYPE,NAME) REGISTER_NAMED(TYPE,NAME,Model)

#define REGISTER_MODEL(TYPE) REGISTER_NAMED_MODEL(TYPE,TYPE)

#define REGISTER_NAMED_MODEL_UPDATE_PREDICATE(TYPE,NAME) \
  REGISTER_NAMED(TYPE,NAME,Model::UpdatePredicate)

#define REGISTER_MODEL_UPDATE_PREDICATE(TYPE) \
  REGISTER_NAMED_MODEL_UPDATE_PREDICATE(TYPE,TYPE)

#define REGISTER_NAMED_MODEL_UPDATER(TYPE,NAME) \
  REGISTER_NAMED(TYPE,NAME,Model::Updater)

#define REGISTER_MODEL_UPDATER(TYPE) \
  REGISTER_NAMED_MODEL_UPDATER(TYPE,TYPE)

}  // namespace reranker

#endif