better doxygen docu for main classes

FMKGPHyperparameterOptimization.h

@@ -1,9 +1,8 @@
 /** 
 * @file FMKGPHyperparameterOptimization.h
 * @brief Heart of the framework to set up everything, perform optimization, classification, and variance prediction (Interface)
-* @author Erik Rodner, Alexander Freytag
-* @date 01/02/2012
-
+* @author Alexander Freytag, Erik Rodner
+* @date 01-02-2012 (dd-mm-yyyy)
 */
 #ifndef _NICE_FMKGPHYPERPARAMETEROPTIMIZATIONINCLUDE
 #define _NICE_FMKGPHYPERPARAMETEROPTIMIZATIONINCLUDE
@@ -39,122 +38,203 @@ namespace NICE {
   /** 
  * @class FMKGPHyperparameterOptimization
  * @brief Heart of the framework to set up everything, perform optimization, classification, and variance prediction
- * @author Erik Rodner, Alexander Freytag
+ * @author Alexander Freytag, Erik Rodner
  */
   
 class FMKGPHyperparameterOptimization : public NICE::Persistent, public NICE::OnlineLearnable
 {
   protected:
-    enum {
-      OPT_GREEDY = 0,
-      OPT_DOWNHILLSIMPLEX,
-      OPT_NONE,
-      OPT_NUMBEROFMETHODS
-    };
-
-    /** optimization method used */
-    int optimizationMethod;
-
-    /** the parameterized function we use within the minimum kernel */
-    ParameterizedFunction *pf;
-
-    /** method computing eigenvalues */
-    EigValues *eig;
-
-    /** method for solving linear equation systems */
-    IterativeLinearSolver *linsolver;
-
-    /** object which stores our sorted data and provides fast hik functions */
-    FastMinKernel *fmk;
-
-    /** object which stores our quantization object */
-    Quantization *q;
-
+    
+    /////////////////////////
+    /////////////////////////
+    // PROTECTED VARIABLES //
+    /////////////////////////
+    ///////////////////////// 
+    
+    ///////////////////////////////////
+    // output/debug related settings //   
+    ///////////////////////////////////
+    
     /** verbose flag */
     bool verbose;    
     /** verbose flag for time measurement outputs */
     bool verboseTime;        
     /** debug flag for several outputs useful for debugging*/
     bool debug;    
+    
+    //////////////////////////////////////
+    // classification related variables //
+    //////////////////////////////////////
+    
+    /** object storing sorted data and providing fast hik methods */
+    NICE::FastMinKernel *fmk;
+
+    /** object performing feature quantization */
+    NICE::Quantization *q;
+    
+    /** the parameterized function we use within the minimum kernel */
+    NICE::ParameterizedFunction *pf;
 
-    /** optimization parameters */
+    /** method for solving linear equation systems - needed to compute K^-1 \times y */
+    IterativeLinearSolver *linsolver;
+    
+    /** Max. number of iterations the iterative linear solver is allowed to run */
+    int ils_max_iterations;    
+    
+    /** Simple type definition for precomputation matrices used for fast classification */
+    typedef VVector PrecomputedType;
+
+    /** precomputed arrays A (1 per class) needed for classification without quantization  */
+    std::map< int, PrecomputedType > precomputedA;    
+    /** precomputed arrays B (1 per class) needed for classification without quantization  */
+    std::map< int, PrecomputedType > precomputedB;
+    
+    /** precomputed LUTs (1 per class) needed for classification with quantization  */
+    std::map< int, double * > precomputedT;  
+    
+    //! storing the labels is needed for Incremental Learning (re-optimization)
+    NICE::Vector labels; 
+    
+    //! store the class number of the positive class (i.e., larger class no), only used in binary settings
+    int binaryLabelPositive;
+    //! store the class number of the negative class (i.e., smaller class no), only used in binary settings
+    int binaryLabelNegative;
+    
+    //! contains all class numbers of the currently known classes
+    std::set<int> knownClasses;
+    
+    //! container for multiple kernel matrices (e.g., a data-containing kernel matrix (GMHIKernel) and a noise matrix (IKMNoise) )
+    NICE::IKMLinearCombination * ikmsum;    
+    
+  
+    /////////////////////////////////////
+    // optimization related parameters //
+    /////////////////////////////////////
+    
+    enum {
+      OPT_GREEDY = 0,
+      OPT_DOWNHILLSIMPLEX,
+      OPT_NONE
+    };
+
+    /** specify the optimization method used (see corresponding enum) */
+    int optimizationMethod;
+    
+    //! whether or not to optimize noise with the GP likelihood
+    bool optimizeNoise;     
+    
+    /** upper bound for hyper parameters to optimize */
     double parameterUpperBound;
+    
+    /** lower bound for hyper parameters to optimize */
     double parameterLowerBound;
+    
+        // specific to greedy optimization
+    /** step size used in grid based greedy optimization technique */
     double parameterStepSize;
-    int ils_max_iterations;
-
+    
+        // specific to downhill simplex optimization
+    /** Max. number of iterations the downhill simplex optimizer is allowed to run */
     int downhillSimplexMaxIterations;
+    
+    /** Max. time the downhill simplex optimizer is allowed to run */
     double downhillSimplexTimeLimit;
+    
+    /** Max. number of iterations the iterative linear solver is allowed to run */
     double downhillSimplexParamTol;
+    
+    
+      // likelihood computation related variables
 
-    /** whether to compute the likelihood with the usual method */
+    /** whether to compute the exact likelihood by computing the exact kernel matrix (not recommended - only for debugging/comparison purpose) */
     bool verifyApproximation;
+
+    /** method computing eigenvalues and eigenvectors*/
+    NICE::EigValues *eig;
     
-    /** number of Eigenvalues to consider in the approximation of |K|_F */
+    /** number of Eigenvalues to consider in the approximation of |K|_F used for approximating the likelihood */
     int nrOfEigenvaluesToConsider;
     
-    /** number of Eigenvalues to consider in the fine approximation of the predictive variance */
-    int nrOfEigenvaluesToConsiderForVarApprox;
-
-    typedef VVector PrecomputedType;
-
-    /** precomputed arrays and lookup tables */
-    std::map< int, PrecomputedType > precomputedA;
-    std::map< int, PrecomputedType > precomputedB;
-    std::map< int, double * > precomputedT;
-
-    PrecomputedType precomputedAForVarEst;
-    double * precomputedTForVarEst;
-
-    //! optimize noise with the GP likelihood
-    bool optimizeNoise;     
-       
     //! k largest eigenvalues of the kernel matrix (k == nrOfEigenvaluesToConsider)
     NICE::Vector eigenMax;
 
     //! eigenvectors corresponding to k largest eigenvalues (k == nrOfEigenvaluesToConsider) -- format: nxk
     NICE::Matrix eigenMaxVectors;
     
-    //! needed for optimization and variance approximation
-    IKMLinearCombination * ikmsum;
+
+    ////////////////////////////////////////////
+    // variance computation related variables //
+    ////////////////////////////////////////////
     
-    //! storing the labels is needed for Incremental Learning (re-optimization)
-    NICE::Vector labels;
+    /** number of Eigenvalues to consider in the fine approximation of the predictive variance (fine approximation only) */
+    int nrOfEigenvaluesToConsiderForVarApprox;
+    
+    /** precomputed array needed for rough variance approximation without quantization */ 
+    PrecomputedType precomputedAForVarEst;
+    
+    /** precomputed LUT needed for rough variance approximation with quantization  */
+    double * precomputedTForVarEst;    
     
+    /////////////////////////////////////////////////////
+    // online / incremental learning related variables //
+    /////////////////////////////////////////////////////
 
-    //! calculate binary label vectors using a multi-class label vector
+    /** whether or not to use previous alpha solutions as initialization after adding new examples*/
+    bool b_usePreviousAlphas;
+    
+    //! store alpha vectors for good initializations in the IL setting, if activated
+    std::map<int, NICE::Vector> previousAlphas;     
+
+    
+    /////////////////////////
+    /////////////////////////
+    //  PROTECTED METHODS  //
+    /////////////////////////
+    /////////////////////////
+    
+
+    /**
+    * @brief calculate binary label vectors using a multi-class label vector
+    * @author Alexander Freytag
+    */    
     int prepareBinaryLabels ( std::map<int, NICE::Vector> & binaryLabels, const NICE::Vector & y , std::set<int> & myClasses);     
     
-    //! prepare the GPLike object for given binary labels and already given ikmsum-object
+    /**
+    * @brief prepare the GPLike object for given binary labels and already given ikmsum-object
+    * @author Alexander Freytag
+    */
     inline void setupGPLikelihoodApprox( GPLikelihoodApprox * & gplike, const std::map<int, NICE::Vector> & binaryLabels, uint & parameterVectorSize);    
     
-    //! update eigenvectors and eigenvalues for given ikmsum-objects and a method to compute eigenvalues
+    /**
+    * @brief update eigenvectors and eigenvalues for given ikmsum-objects and a method to compute eigenvalues
+    * @author Alexander Freytag
+    */
     inline void updateEigenDecomposition( const int & i_noEigenValues );
     
-    //! core of the optimize-functions
+    /**
+    * @brief core of the optimize-functions
+    * @author Alexander Freytag
+    */
     inline void performOptimization( GPLikelihoodApprox & gplike, const uint & parameterVectorSize);
     
-    //! apply the optimized transformation values to the underlying features
+    /**
+    * @brief apply the optimized transformation values to the underlying features
+    * @author Alexander Freytag
+    */    
     inline void transformFeaturesWithOptimalParameters(const GPLikelihoodApprox & gplike, const uint & parameterVectorSize);
     
-    //! build the resulting matrices A and B as well as lookup tables T for fast evaluations using the optimized parameter settings
+    /**
+    * @brief build the resulting matrices A and B as well as lookup tables T for fast evaluations using the optimized parameter settings
+    * @author Alexander Freytag
+    */
     inline void computeMatricesAndLUTs( const GPLikelihoodApprox & gplike);
     
      
-    //! store the class number of the positive class (i.e., larger class no), only used in binary settings
-    int binaryLabelPositive;
-    //! store the class number of the negative class (i.e., smaller class no), only used in binary settings
-    int binaryLabelNegative;
-    
-    //! contains all class numbers of the currently known classes
-    std::set<int> knownClasses;
-    
-    bool b_usePreviousAlphas;
-    
-    //! we store the alpha vectors for good initializations in the IL setting
-    std::map<int, NICE::Vector> previousAlphas;  
 
-    //! Update matrices (A, B, LUTs) and optionally find optimal parameters after adding (a) new example(s).  
+    /**
+    * @brief Update matrices (A, B, LUTs) and optionally find optimal parameters after adding (a) new example(s).  
+    * @author Alexander Freytag
+    */           
     void updateAfterIncrement (
       const std::set<int> newClasses,
       const bool & performOptimizationAfterIncrement = false
@@ -164,7 +244,10 @@ class FMKGPHyperparameterOptimization : public NICE::Persistent, public NICE::On
     
   public:  
     
-
+    /**
+    * @brief simple constructor
+    * @author Alexander Freytag
+    */
     FMKGPHyperparameterOptimization();
     
     /**
@@ -176,21 +259,41 @@ class FMKGPHyperparameterOptimization : public NICE::Persistent, public NICE::On
     */
     FMKGPHyperparameterOptimization( const Config *conf, ParameterizedFunction *pf, FastMinKernel *fmk = NULL, const std::string & confSection = "GPHIKClassifier" );
       
-    /** simple destructor */
+    /**
+    * @brief standard destructor
+    * @author Alexander Freytag
+    */
     virtual ~FMKGPHyperparameterOptimization();
     
     ///////////////////// ///////////////////// /////////////////////
     //                         GET / SET
-    ///////////////////// ///////////////////// ///////////////////// 
+    ///////////////////// ///////////////////// /////////////////////
+    
+    /**
+    * @brief Set lower bound for hyper parameters to optimize
+    * @author Alexander Freytag
+    */    
     void setParameterUpperBound(const double & _parameterUpperBound);
+    /**
+    * @brief Set upper bound for hyper parameters to optimize
+    * @author Alexander Freytag
+    */    
     void setParameterLowerBound(const double & _parameterLowerBound);  
     
+    /**
+    * @brief Get the currently known class numbers
+    * @author Alexander Freytag
+    */    
     std::set<int> getKnownClassNumbers ( ) const;
     
     ///////////////////// ///////////////////// /////////////////////
     //                      CLASSIFIER STUFF
     ///////////////////// ///////////////////// /////////////////////  
     
+    /**
+    * @brief Set variables and parameters to default or config-specified values
+    * @author Alexander Freytag
+    */       
     void initialize( const Config *conf, ParameterizedFunction *pf, FastMinKernel *fmk = NULL, const std::string & confSection = "GPHIKClassifier" );
        
 #ifdef NICE_USELIB_MATIO
@@ -347,19 +450,41 @@ class FMKGPHyperparameterOptimization : public NICE::Persistent, public NICE::On
     // interface specific methods for store and restore
     ///////////////////// INTERFACE PERSISTENT ///////////////////// 
     
+    /** 
+     * @brief Load current object from external file (stream)
+     * @author Alexander Freytag
+     */     
     void restore ( std::istream & is, int format = 0 );
+    
+    /** 
+     * @brief Save current object to external file (stream)
+     * @author Alexander Freytag
+     */      
     void store ( std::ostream & os, int format = 0 ) const;
+    
+    /** 
+     * @brief Clear current object
+     * @author Alexander Freytag
+     */      
     void clear ( ) ;
     
     ///////////////////// INTERFACE ONLINE LEARNABLE /////////////////////
     // interface specific methods for incremental extensions
     ///////////////////// INTERFACE ONLINE LEARNABLE /////////////////////    
     
+    /** 
+     * @brief add a new example
+     * @author Alexander Freytag
+     */       
     virtual void addExample( const NICE::SparseVector * example, 
                              const double & label, 
                              const bool & performOptimizationAfterIncrement = true
                            );
-                          
+
+    /** 
+     * @brief add several new examples
+     * @author Alexander Freytag
+     */    
     virtual void addMultipleExamples( const std::vector< const NICE::SparseVector * > & newExamples,
                                       const NICE::Vector & newLabels,
                                       const bool & performOptimizationAfterIncrement = true

GPHIKClassifier.h

@@ -1,9 +1,8 @@
 /** 
 * @file GPHIKClassifier.h
-* @author Erik Rodner, Alexander Freytag
 * @brief Main interface for our GP HIK classifier (similar to the feature pool classifier interface in vislearning) (Interface)
-* @date 02/01/2012
-
+* @author Alexander Freytag, Erik Rodner
+* @date 01-02-2012 (dd-mm-yyyy)
 */
 #ifndef _NICE_GPHIKCLASSIFIERINCLUDE
 #define _NICE_GPHIKCLASSIFIERINCLUDE
@@ -28,14 +27,46 @@ namespace NICE {
  /** 
  * @class GPHIKClassifier
  * @brief Main interface for our GP HIK classifier (similar to the feature pool classifier interface in vislearning)
- * @author Erik Rodner, Alexander Freytag
+ * @author Alexander Freytag, Erik Rodner
  */
  
 class GPHIKClassifier : public NICE::Persistent, public NICE::OnlineLearnable
 {
 
   protected:
+    
+    /////////////////////////
+    /////////////////////////
+    // PROTECTED VARIABLES //
+    /////////////////////////
+    /////////////////////////
+    
+    // output/debug related settings
+    
+    /** verbose flag for useful output*/
+    bool verbose;
+    /** debug flag for several outputs useful for debugging*/
+    bool debug;
+    
+    // general specifications
+    
+    /** Header in configfile where variable settings are stored */
     std::string confSection;
+    /** Configuration file specifying variable settings */
+    NICE::Config *confCopy; 
+    
+    // internal objects 
+    
+    /** Main object doing all the jobs: training, classification, optimization, ... */
+    NICE::FMKGPHyperparameterOptimization *gphyper;    
+    
+    /** Possibility for transforming feature values, parameters can be optimized */
+    NICE::ParameterizedFunction *pf;    
+    
+    
+    
+    
+    /** Gaussian label noise for model regularization */
     double noise;
 
     enum VarianceApproximation{
@@ -45,39 +76,49 @@ class GPHIKClassifier : public NICE::Persistent, public NICE::OnlineLearnable
       NONE
     };
     
+    /** Which technique for variance approximations shall be used */
     VarianceApproximation varianceApproximation;
     
     /**compute the uncertainty prediction during classification?*/
     bool uncertaintyPredictionForClassification;
     
-    NICE::Config *confCopy;
-    NICE::ParameterizedFunction *pf;
-    NICE::FMKGPHyperparameterOptimization *gphyper;
-    
-    /** verbose flag for useful output*/
-    bool verbose;
-    /** debug flag for several outputs useful for debugging*/
-    bool debug;
+    /////////////////////////
+    /////////////////////////
+    //  PROTECTED METHODS  //
+    /////////////////////////
+    /////////////////////////
     
     /** 
-    * @brief classify a given example with the previously learnt model
-    * @param pe example to be classified given in a sparse representation
+    * @brief Setup internal variables and objects used
+    * @author Alexander Freytag
+    * @param conf Config file to specify variable settings
+    * @param s_confSection
     */    
     void init(const NICE::Config *conf, const std::string & s_confSection);
        
 
   public:
 
-    /** simple constructor */
+    /** 
+     * @brief standard constructor
+     * @author Alexander Freytag
+     */
     GPHIKClassifier( const NICE::Config *conf = NULL, const std::string & s_confSection = "GPHIKClassifier" );
       
-    /** simple destructor */
+    /**
+     * @brief simple destructor
+     * @author Alexander Freytag
+     */
     ~GPHIKClassifier();
     
     ///////////////////// ///////////////////// /////////////////////
     //                         GET / SET
     ///////////////////// ///////////////////// /////////////////////      
     
+    /**
+     * @brief Return currently known class numbers
+     * @author Alexander Freytag
+     */    
     std::set<int> getKnownClassNumbers ( ) const;    
    
     ///////////////////// ///////////////////// /////////////////////
@@ -146,6 +187,10 @@ class GPHIKClassifier : public NICE::Persistent, public NICE::OnlineLearnable
      */
     void train ( const std::vector< const NICE::SparseVector *> & examples, std::map<int, NICE::Vector> & binLabels );
     
+    /**
+     * @brief Clone classifier object
+     * @author Alexander Freytag
+     */    
     GPHIKClassifier *clone () const;
 
     /** 
@@ -172,8 +217,22 @@ class GPHIKClassifier : public NICE::Persistent, public NICE::OnlineLearnable
     // interface specific methods for store and restore
     ///////////////////// INTERFACE PERSISTENT /////////////////////   
     
+    /** 
+     * @brief Load classifier from external file (stream)
+     * @author Alexander Freytag
+     */     
     void restore ( std::istream & is, int format = 0 );
+    
+    /** 
+     * @brief Save classifier to external file (stream)
+     * @author Alexander Freytag
+     */     
     void store ( std::ostream & os, int format = 0 ) const;
+    
+    /** 
+     * @brief Clear classifier object
+     * @author Alexander Freytag
+     */     
     void clear ();
     
     
@@ -181,15 +240,23 @@ class GPHIKClassifier : public NICE::Persistent, public NICE::OnlineLearnable
     // interface specific methods for incremental extensions
     ///////////////////// INTERFACE ONLINE LEARNABLE /////////////////////
     
+    /** 
+     * @brief add a new example
+     * @author Alexander Freytag
+     */    
     virtual void addExample( const NICE::SparseVector * example, 
-			     const double & label, 
-			     const bool & performOptimizationAfterIncrement = true
-			   );
-			   
+                              const double & label, 
+                              const bool & performOptimizationAfterIncrement = true
+                            );
+                          
+    /** 
+     * @brief add several new examples
+     * @author Alexander Freytag
+     */    
     virtual void addMultipleExamples( const std::vector< const NICE::SparseVector * > & newExamples,
-				      const NICE::Vector & newLabels,
-				      const bool & performOptimizationAfterIncrement = true
-				    );       
+                                      const NICE::Vector & newLabels,
+                                      const bool & performOptimizationAfterIncrement = true
+                                    );       
 
 
 

OnlineLearnable.h

@@ -21,20 +21,44 @@ class OnlineLearnable {
  
   public:
     // Interface specifications
-    virtual void addExample( const NICE::SparseVector * example, 
-			     const double & label, 
-			     const bool & performOptimizationAfterIncrement = true
-			   ) = 0;
-			   
+    
+    /** 
+     * @brief Interface method to add a single example to the current object
+     * @author Alexander Freytag
+     * @param newExample example to be added
+     * @param newLabel corresponding class labels
+     * @param performOptimizationAfterIncrement (optional) whether or not to run a hyper parameter optimization after adding new examples
+     */    
+    virtual void addExample( const NICE::SparseVector * newExample, 
+                              const double & newLabel, 
+                              const bool & performOptimizationAfterIncrement = true
+                            ) = 0;
+
+    /** 
+     * @brief Interface method to add multiple example to the current object
+     * @author Alexander Freytag
+     * @param newExamples vector of example to be added
+     * @param newLabels vector of corresponding class labels
+     * @param performOptimizationAfterIncrement (optional) whether or not to run a hyper parameter optimization after adding new examples
+     */                                       
+                            
     virtual void addMultipleExamples( const std::vector< const NICE::SparseVector * > & newExamples,
-				      const NICE::Vector & newLabels,
-				      const bool & performOptimizationAfterIncrement = true
-				    ) = 0;    
+                                      const NICE::Vector & newLabels,
+                                      const bool & performOptimizationAfterIncrement = true
+                                    ) = 0;    
 
 
-    // Provided functions and overloaded stream operators
+    /** 
+     * @brief simple destructor
+     * @author Alexander Freytag
+     */                                       
     virtual ~OnlineLearnable () {};
     
+    
+    /** 
+     * @brief simple destructor
+     * @author Alexander Freytag
+     */    
     // just to prevent senseless compiler warnings
     OnlineLearnable() {};