MAP.h

Go to the documentation of this file.

/*  Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
 
    This file is part of the TerraLib - a Framework for building GIS enabled applications.
 
    TerraLib 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 3 of the License,
    or (at your option) any later version.
 
    TerraLib 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 TerraLib. See COPYING. If not, write to
    TerraLib Team at <terralib-team@terralib.org>.
 */
 
/*!
  \file terralib/classification/MAP.h
 
  \brief MAP (Maximum a Posteriori) strategy for classification.
*/
 
#ifndef __TERRALIB_CLASSIFICATION_INTERNAL_MAP_H
#define __TERRALIB_CLASSIFICATION_INTERNAL_MAP_H
 
// TerraLib
#include "../common/AbstractParameters.h"
#include "../common/MatrixUtils.h"
#include "../common/progress/TaskProgress.h"
#include "Adaptors.h"
#include "Config.h"
#include "Exception.h"
 
// STL
#include <vector>
#include <memory>
 
// boost
#include <boost/numeric/ublas/matrix.hpp>
 
namespace te
{
  namespace cl
  {
    /*!
      \class MAP
      \brief MAP strategy for classification.
 
    */
 
    class TECLEXPORT MAP
    {
      public:
 
        /*!
          \class Parameters
          \brief Classifier Parameters
        */
        class TECLEXPORT Parameters : public te::common::AbstractParameters
        {
          public:
 
            std::vector< double > m_prioriProbs; //!< Priori probabilities, one for each class. Values from 0 to 1 (use an empty vector to allow internal calcule of priori probabilities).
            unsigned int m_prioriCalcSampleStep; //!< A positive non-zero sample step used when calculating piori probabilities (default:5 - 1/5 of samples will be used);
 
            Parameters();
 
            ~Parameters();
 
            //overload
            const Parameters& operator=(const Parameters& params);
 
            //overload
            void reset() ;
 
            //overload
            AbstractParameters* clone() const;
        };
        
        /*!
          \class Trained model parameters
          \brief Trained model parameters
        */
        class TECLEXPORT ModelParameters : public te::common::AbstractParameters
        {
          public:
 
            std::vector<unsigned int> m_classLabels; //!< class labels
            std::vector< std::vector< double > > m_classesMeans; //!< Classes means;
            std::vector< boost::numeric::ublas::matrix< double > > m_classesCovarianceMatrixes; //!< Classes covariance matrixes.
 
            ModelParameters();
 
            ~ModelParameters();
 
            //overload
            const ModelParameters& operator=(const ModelParameters& params);
 
            //overload
            void reset() ;
 
            //overload
            AbstractParameters* clone() const;
        };        
 
      public:
 
        MAP();
 
        ~MAP();
 
        /*!
          \brief Initialize this classifier instance with new parameters (further training is required).
          \param params New initialization parameters.
        */
        bool initialize(const Parameters& params) ;
        
        /*!
          \brief Initialize this classifier instance with new model parameters (further training not required).
          \param params New initialization parameters.
          \param modelParams New model parameters.
        */
        bool initialize(const Parameters& params, const ModelParameters& modelParams) ;        
 
        /*!
          \brief Train this classifier instance using the initialization parameters and the suppied train data.
          \param samples Train data samples.
          \param attributesIndices The attributes indexes to processe from the iterated train data.
          \param sampleLabels The sample lables for each iterated train data element.
          \param enableProgressInterface Enable/disable the use of a proress interfece.
        */
        bool train( const InputAdaptor< double >& samples,
                   const std::vector<unsigned int>& attributesIndices,
                   const std::vector<unsigned int>& sampleLabels,
                   const bool enableProgressInterface) ;
 
        /*!
          \brief Classify an input iterated data and save the result on the output iterated data.
          \param input Input data to be classified.
          \param attributesIndices The attributes indexes to processe from the iterated train data.
          \param inputNoDataValues A vector of no-data values for each attribute dimension or an empty vector if no-data values are not used.
          \param output Output classified data.
          \param outputIndex The output attribute index.
          \param outputNoDataValue A output label value to use when dealing with input no-data.
          \param enableProgressInterface Enable/disable the use of a proress interfece.
        */
        bool classify( const InputAdaptor< double >& input,
                      const std::vector<unsigned int>& attributesIndices,
                      const std::vector< double >& inputNoDataValues,
                      OutputAdaptor< unsigned int >& output,
                      const unsigned int outputIndex,
                      const double outputNoDataValue,
                      const bool enableProgressInterface) ;
               
        /*!
          \brief Returns the current model parameters.
          \return Returns the current model parameters.
        */
        const ModelParameters& getModelParams();
 
      protected:
 
        bool m_isInitialized;                              //!< True if this instance is initialized.
        Parameters m_parameters;                           //!< Internal execution parameters.
        ModelParameters m_modelParameters;                 //!< Trained model parameters
        std::vector< boost::numeric::ublas::matrix< double > > m_classesCovarianceInvMatrixes; //!< Classes covariance inverse matrixes.
        std::vector< double > m_classesOptizedMAPDiscriminantTerm;  //!< An optimized portion of the MAP discriminant function.
 
        /*! \brief Reset this instance to its initial state */
        void reset();
 
        /*!
          \brief Calculate priori probabilities by pre-classifying the input data.
          \param input Input data to be classified.
          \param attributesIndices The attributes indexes to processe from the iterated train data.
          \param prioriProbs Calculated priori-probabilities.
        */
        bool getPrioriProbabilities( const InputAdaptor< double >& input,
          const std::vector<unsigned int>& attributesIndices,
          std::vector< double >& prioriProbs ) const;
    };
  } // end namespace cl
}  // end namespace te
 
#endif // __TERRALIB_CLASSIFICATION_INTERNAL_MAP_H