NICE_VisLearning/math/cluster/KMeans.h

/** 
* @file KMeans.h
* @brief K-Means
* @author Erik Rodner, Alexander Freytag
* @date 29-10-2007 (dd-mm-yyyy)
*/
#ifndef KMEANSINCLUDE
#define KMEANSINCLUDE

// nice-core includes
#include <core/basics/Exception.h>
#include <core/basics/Config.h>
// 
#include <core/vector/Distance.h>
#include "core/vector/VectorT.h"
#include "core/vector/MatrixT.h"
#include <core/vector/Distance.h>

#include "ClusterAlgorithm.h"


namespace OBJREC {

/** K-Means */
  /**
   * @class K-Means
   * @brief K-Means
   * @author Erik Rodner, Alexander Freytag
   * @date 29-10-2007 (dd-mm-yyyy)
  */  
  class KMeans : public ClusterAlgorithm
  {

    protected:
          
        /************************
        * 
        *   protected variables
        * 
        **************************/         
          
          //! desired number of clusters
          int noClusters;
          
          //! specify which distance to use for calculating assignments
          std::string distanceType;
          
          //! the actual distance metric
          NICE::VectorDistance<double> *distancefunction;
          
          //! maximum difference between prototype-solutions of two iterations for convergence
          double d_minDelta;
          
          //! maximum number of iterations until convergence
          int i_maxIterations;          
          
        /************************
        * 
        *   protected methods
        * 
        **************************/          
          
        //! compute the distance between two features using the specified distance metric
          double vectorDistance(const NICE::Vector &vector1, const NICE::Vector &vector2, uint distancetype);
          
        //! compute assignments of all given features wrt to the currently known prototypes (cluster centroids) == ~ E-step
          double compute_assignments ( const NICE::VVector & features,
                                      const NICE::VVector & prototypes,
                                      std::vector<int> & assignment );

        //! compute number of assignments for every currently found cluster
          double compute_weights ( const NICE::VVector & features,
                                  std::vector<double> & weights,
                                  std::vector<int>    & assignment );

        //! compute the difference between prototypes of previous iteration and those currently found
          double compute_delta ( const NICE::VVector & oldprototypes,
                                const NICE::VVector & prototypes );

        //! compute (update) prototypes given the current assignments == ~ M-step
          int compute_prototypes ( const NICE::VVector & features,
                                  NICE::VVector & prototypes,
                                  std::vector<double> & weights,
                                  const std::vector<int>    & assignment );
          
        //! have an initial guess, i.e., randomly pick some features as initial cluster centroids
          void initial_guess ( const NICE::VVector & features,
                              NICE::VVector & prototypes );
        //! give additional information for the current iteration
          void print_iteration ( int iterations,
                                NICE::VVector & prototypes,
                                double delta );

      public:

        /**
        * @brief simple constructor
        * @param _noClusters the number of clusters to be computed
        * @param _distanceMode a string specifying the distance function to be used (default: euclidean)
        */
        KMeans( const int & _noClusters , const std::string & _distanceMode="euclidean");
      
        /**
        * @brief standard constructor
        * @param conf config file specifying all relevant variable settings
        * @param _section name of the section within the configfile where the settings can be found (default: KMeans)
        */
        KMeans( const NICE::Config *conf, const std::string & _section = "KMeans");      

        /** simple destructor */
        virtual ~KMeans();

        
          /**
          *@brief this is the actual method that performs the clustering for a given set of features
          *@author Erik Rodner, Alexander Freytag
          *@date 29-10-2007 (dd-mm-yyyy)
          *@param   features input features to be clustered
          *@param   prototypes computed prototypes (cluster medoids) for the given samples
          *@param   weights number of assignments for every cluster
          *@param   assignment explicite assignments of features to computed cluster medoids
          */            
        void cluster ( const NICE::VVector & features,
                      NICE::VVector & prototypes,
                      std::vector<double> & weights,
                      std::vector<int>    & assignment );

  };


} // namespace

#endif