baselearner.h

MultiBoost 是c++实现的多类adaboost酸法。与传统的adaboost算法主要解决二类分类问题不同

/*
* This file is part of MultiBoost, a multi-class 
* AdaBoost learner/classifier
*
* Copyright (C) 2005-2006 Norman Casagrande
* For informations write to [e-mail]
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*
*/

/**
* \file BaseLearner.h The abstract basic (weak) learner.
*/

#ifndef __BASE_LEARNER_H
#define __BASE_LEARNER_H

#include <algorithm>
#include <vector>

#include "IO/InputData.h"
#include "Utils/Args.h"

#include "Utils/StreamTokenizer.h"

using namespace std;

//////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////////

namespace MultiBoost {

/**
* Generic base learner. 
* All the weak learners used by AdaBoost should inherit from this one.
* \todo Add a getAlpha for non-binary (ternary) base-classifiers, using line-search.
*/
class BaseLearner
{

private:

   //////////////////////////////////////////////////////////////////////////

   /**
   * Holds the information about the registered learners. Works pretty
   * much like a class factory.
   * @see REGISTER_LEARNER
   * @see RegisteredLearners()
   * @see create()
   * @date 21/11/2005
   */
   class LearnersRegs
   {
   public:

      /**
      * Register a weak learner.
      * @param learnerName The name of the learner
      * @param pLearnerToRegister The allocated learner to register.
      * @warning To be used only with macro REGISTER_LEARNER()!
      * @date 21/11/2005
      */
      void addLearner(const string& learnerName, BaseLearner* pLearnerToRegister)
      { _learners[learnerName] = pLearnerToRegister; }

      /**
      * Check if a given learner has been registered.
      * @param learnerName The name of the learner.
      * @date 21/11/2005
      */
      bool hasLearner(const string& learnerName)
      { return ( _learners.find(learnerName) != _learners.end() ); }

      /**
      * Return the allocated learner object.
      * @param learnerName The name of the learner.
      * @date 21/11/2005
      */
      BaseLearner* getLearner(const string& learnerName)
      { return _learners[learnerName]; }

      /**
      * Return the list of the learners currently registered.
      * @param learnersList The list of the learners that will be filled.
      * @date 21/11/2005
      */
      void getList(vector<string>& learnersList)
      {
         learnersList.clear();
         learnersList.reserve(_learners.size());
         map<string, BaseLearner*>::const_iterator it;
         for (it = _learners.begin(); it != _learners.end(); ++it)
            learnersList.push_back( it->first );
      }

   private:
      map<string, BaseLearner*> _learners; //!< The map of the registered learners. 
   };

   //////////////////////////////////////////////////////////////////////////

public:

   /**
   * Map of the registered basic learners.
   * This data is updated statically just by adding the macro
   * REGISTER_LEARNER(X) where X is the name of the learner
   * (which \b must match the class name) in the .cpp
   * file. Example (in file StumpLearner.cpp):
   * \code
   * REGISTER_LEARNER(SingleStumpLearner)
   * \endcode
   * It is possible to register a class with a different name of 
   * its class name using REGISTER_LEARNER_NAME(X, Y), where Y
   * is the custom name. For instance:
   * \code
   * REGISTER_LEARNER_NAME(SingleStumpLearner, SStump)
   * \endcode
   * @remark Only non-abstract classes must be registered!
   * @remark To prevent the "static initialization order fiasco"
   * I am using the trick described in http://www.parashift.com/c++-faq-lite/ctors.html#faq-10.13
   * @see create()
   * @see LearnersRegs
   * @date 14/11/2005
   */
   static LearnersRegs& RegisteredLearners()
   {
      // Construct On First Use Idiom:
      // Since static local objects are constructed the first time control flows 
      // over their declaration (only), the new LearnersRegs() statement will only 
      // happen once: the first time RegisteredLearners() is called. Every subsequent 
      // call will return the same LearnersRegs object (the one pointed to by ans). 
      static LearnersRegs* regLerners = new LearnersRegs();
      return *regLerners;
   }

   /**
   * The constructor. It initializes _smallVal to 1E-10, and _alpha to 0
   * @see _alpha
   * @date 11/11/2005
   */
   BaseLearner() : _smallVal(1E-10), _alpha(0) { _smoothingVal = _smallVal; }

   /**
   * The destructor. Must be declared (virtual) for the proper destruction of 
   * the object.
   */
   virtual ~BaseLearner() {}

   /**
   * Declare weak-learner-specific arguments.
   * These arguments will be added to the list of arguments under 
   * the group specific of the weak learner. It is called
   * automatically in main, when the list of arguments is built up.
   * Use this method to declare the arguments that belongs to
   * the weak learner only.
   * @param args The Args class reference which can be used to declare
   * additional arguments.
   * @date 28/11/2005
   */
   virtual void declareArguments(nor_utils::Args& args) = 0;

   /**
   * Declare arguments that belongs to all weak-learners. 
   * @remarks This method belongs only to this base class and must not
   * be extended.
   * @remarks I cannot use the standard declareArguments method, as it
   * is called only to instantiated objects, and as this class is abstract
   * I cannot do it.
   * @param args The Args class reference which can be used to declare
   * additional arguments.
   * @date 10/2/2006
   */
   static void declareBaseArguments(nor_utils::Args& args);

   /**
   * Set the arguments of the algorithm using the standard interface
   * of the arguments. Call this to set the arguments asked by the user.
   * @remark At this level the method does nothing. It is overridden (if necessary)
   * in the derived classes.
   * @date 14/11/2005
   */
   virtual void initOptions(nor_utils::Args& /*args*/) {}

   /**
   * Returns a new object of the derived type.
   * For instance the overriding of this method in SingleStumpLearner
   * will be:
   * \code
   * return new SingleStumpLearner();
   * \endcode
   * For that reason every learner must have an empty constructor. Use
   * setArguments() if you must define some parameters of the learner.
   * @remark It uses the trick described in http://www.parashift.com/c++-faq-lite/serialization.html#faq-36.8
   * for the auto-registering classes.
   * @see SingleStumpLearner::create()
   * @date 14/11/2005
   */
   virtual BaseLearner* create() = 0;

   /**
   * Creates an InputData object that it is good for the
   * weak learner. Override it if the weak learner
   * requires another type of data to be loaded
   * (which must be an extension of InputData).
   * @warning The object \b must be destroyed by the caller.
   * @see InputData
   * @date 21/11/2005
   */
   virtual InputData* createInputData();

   /**