NICE_VisLearning/classifier/fpclassifier/FPCGPHIK.h

/** 
* @file FPCGPHIK.h
* @author Alexander Freytag, Erik Rodner
* @date 02/01/2012

*/
#ifndef _NICE_FPCGPHIKCLASSIFIERNICEINCLUDE
#define _NICE_FPCGPHIKCLASSIFIERNICEINCLUDE

// STL includes
#include <string>

// NICE-core includes
#include <core/basics/Config.h>

// NICE-gp-hik-core includes
#include <gp-hik-core/GPHIKClassifier.h>
#include <gp-hik-core/FMKGPHyperparameterOptimization.h>
#include <gp-hik-core/parameterizedFunctions/ParameterizedFunction.h>

// NICE-vislearning includes
#include "vislearning/classifier/classifierbase/FeaturePoolClassifier.h"

namespace OBJREC {
  
/** @class FPCGPHIK
 * Wrapper class (feature pool interface) for our GP HIK classifier 
 *
 * @author Alexander Freytag, Erik Rodner
 */
class FPCGPHIK : public FeaturePoolClassifier
{

  protected:
    
    NICE::GPHIKClassifier * classifier;
    
    /** verbose flag for useful output*/
    bool verbose;
    
    /** a simple balancing strategy: use only that many examples of each class, as the smallest class provides*/
    bool useSimpleBalancing; 
    int minSamples;
    
    /** When adding new examples, do we want to run a whole optimization of all involved hyperparameters? default: true*/
    bool performOptimizationAfterIncrement;

  public:

    /** simple constructor */
    FPCGPHIK( const NICE::Config *conf, const std::string & confSection = "GPHIKClassifier" );
      
    /** simple destructor */
    virtual ~FPCGPHIK();
   
    /** 
    * @brief classify a given example with the previously learnt model
    * @param pe example to be classified given in a sparse representation
    */
    virtual ClassificationResult classify ( OBJREC::Example & pe );
    /** 
     * @brief classify a given example with the previously learnt model
     * @date 19-06-2012 (dd-mm-yyyy)
     * @author Alexander Freytag
     * @param examples example to be classified given in a sparse representation
     */    
    ClassificationResult classify ( const NICE::SparseVector * example );

    /** training process */
    virtual void train ( OBJREC::FeaturePool & fp, OBJREC::Examples & examples );
    /** 
     * @brief train this classifier using a given set of examples and a given set of binary label vectors 
     * @date 19-06-2012 (dd-mm-yyyy)
     * @author Alexander Freytag
     * @param examples examples to use given in a sparse data structure
     * @param binLabels corresponding binary labels with class no. There is no need here that every examples has only on positive entry in this set (1,-1)
     */
    void train ( const std::vector< const NICE::SparseVector *> & examples, std::map<int, NICE::Vector> & binLabels );
    
    ///////////////////// INTERFACE PERSISTENT /////////////////////
    // interface specific methods for store and restore
    ///////////////////// INTERFACE PERSISTENT ///////////////////// 
    virtual void restore ( std::istream & is, int format = 0 );
    virtual void store ( std::ostream & os, int format = 0 ) const;
    virtual void clear ();

    virtual FeaturePoolClassifier *clone () const;
    
    /** prediction of classification uncertainty */
    void predictUncertainty( OBJREC::Example & pe, double & uncertainty );
    /** 
     * @brief prediction of classification uncertainty
     * @date 19-06-2012 (dd-mm-yyyy)
     * @author Alexander Freytag
     * @param examples example for which the classification uncertainty shall be predicted, given in a sparse representation
     * @param uncertainties contains the resulting classification uncertainties (1 entry for standard setting, m entries for binary-balanced setting)
     */       
    void predictUncertainty( const NICE::SparseVector * example, double & uncertainty );
    
    ///////////////////// INTERFACE ONLINE LEARNABLE (SIMILAR) /////////////////////
    // interface specific methods for incremental extensions
    ///////////////////// INTERFACE ONLINE LEARNABLE (SIMILAR) /////////////////////       
    
    void addExample( const OBJREC::Example & pe, const double & label);
    virtual void addMultipleExamples( OBJREC::Examples & newExamples);
    
};

}

#endif