GroupingAlgorithms.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 GroupingAlgorithms.h

  \brief This file contains functions containing the algorithms for grouping values.
*/

#ifndef __TERRALIB_MAPTOOLS_INTERNAL_GROUPINGALGORITHMS_H
#define __TERRALIB_MAPTOOLS_INTERNAL_GROUPINGALGORITHMS_H

// TerraLib
#include "Config.h"
#include "../core/translator/Translator.h"
#include "../common/StringUtils.h"
#include "../fe/Utils.h"
#include "../se/Description.h"
#include "../se/Rule.h"

// STL
#include <string>
#include <vector>

#include <cmath>
#include <stdlib.h>


#ifndef MIN
#define MIN(a,b) ( (a<b) ? a : b )  //!< Macro that returns min between two values
#endif

#ifndef MAX
#define MAX(a,b) ( (a>b) ? a : b )  //!< Macro that returns max between two values
#endif


namespace te
{
  namespace map
  {
    /*!
      \brief It groups the values using the unique value algorithm.

      \param attrName     The attribute name used do create the group.
      \param inputValues  The data to be grouped by unique values.
      \param dataType     The data type of the values.
      \param rules        The container of rules items where the groups will be placed.
      \precision          The precision to be used in the conversion of the values.

      \output             The groups will be stored in the container of legend items.
    */
    TEMAPEXPORT void GroupingByUniqueValues(std::string attrName, std::vector<std::string>& inputValues, int dataType,
                                            std::vector<te::se::Rule*>& rules, int precision);

    /*!
      \brief It adjusts a value to the precision specified

      \param value        The value to be adjusted.
      \param precision    The precision the given value must be adjusted to.
      \param reduce       Flag indicating if the value must be added or subtracted to the value represented by the precision.

      \output             The value adjusted to the precision specified.
    */
    TEMAPEXPORT double AdjustToPrecision(double val, int precision, bool reduce = false);

    /*!
      \brief It groups the values defined by a range of iterators using the equal steps algorithm.

      \param begin          The iterator associated to the first element value.
      \param end            The iterator associated to the last element value.
      \param nSteps         The number of steps.
      \param rules         The container of rules items.
      \param precision      The precision to be used in the conversion of the values.
      \param countElements  The flag indicating if the counting of elements must be done.

      \output               The groups will be stored in the container of legend items.
    */
    template<class iterator>
    void GroupingByEqualSteps(std::string attrName, iterator begin, iterator end, int nSteps, std::vector<te::se::Rule*>& rules,
                              int precision = 0)
    {
      double min = std::numeric_limits<double>::max();
      double max = -std::numeric_limits<double>::max();

      iterator it = begin;

      while(it < end)
      {
        min = MIN(min, *it);
        max = MAX(max, *it);
        ++it;
      }

      double slice = (max - min)/double(nSteps);
    
      for(int i = 0; i < nSteps; ++i)
      {
        if (i == 0)
          min = te::map::AdjustToPrecision(min, precision, true);
        else
          min = min + double(i) * slice;

        if (i == nSteps - 1)
          max = te::map::AdjustToPrecision(max, precision, false);
        else
          max = min + double(i + 1) * slice;

        te::se::Rule* ruleItem = new te::se::Rule;
        std::string ruleName = "[" + te::common::Convert2String(min, precision) + ", " + te::common::Convert2String(max, precision) + "[";
        std::string* ruleNamePtr = new std::string(ruleName);
        ruleItem->setName(ruleNamePtr);
        ruleItem->setFilter(te::fe::CreateFilterByStep(attrName, te::common::Convert2String(min, precision), te::common::Convert2String(max, precision)));

        rules.push_back(ruleItem);
      }
    }

    /*!
      \brief It groups the values defined by a range of iterators using the quantil algorithm.

      \param begin          The iterator associated to the first element value.
      \param end            The iterator associated to the last element value.
      \param nSteps         The number of steps.
      \param rules          The container of rules items.
      \param precision      The precision to be used in the conversion of the values.
      \param countElements  The flag indicating if the counting of elements must be done.

      \output               The groups will be stored in the container of legend items.
    */
    template<class iterator>
    void GroupingByQuantil(std::string attrName, iterator begin, iterator end, int nSteps, std::vector<te::se::Rule*>& rules,
                          int precision = 0)
    {
      sort(begin, end);

      int size = static_cast<int>(end - begin);
      double steps = (double)size / (double)nSteps;

      std::vector< std::pair<std::string, std::string> > pairMinMax;

      int  n = 0;
      iterator it = begin;
      while(it < end)
      {
        std::string minValue = te::common::Convert2String(*it, precision);
        std::string maxValue = "";
        
        int p = (int)(steps * (double)++n + .5);

        it = begin + p;
        if(it < end)
          maxValue = te::common::Convert2String(*it, precision);
        else
          maxValue = te::common::Convert2String(*(it - 1), precision);

        std::pair<std::string, std::string> pair(minValue, maxValue);

        pairMinMax.push_back(pair);
      }

      if(end-begin > 1)
      {
        double min = (*begin);
        double max = (*(end-1));

        min = te::map::AdjustToPrecision(min, precision, true);
        pairMinMax[0].first = te::common::Convert2String(min, precision);
        
        max = te::map::AdjustToPrecision(max, precision, false);
        pairMinMax[pairMinMax.size() - 1].second = te::common::Convert2String(max, precision);
      }

      for (std::size_t t = 0; t < pairMinMax.size(); ++t)
      {
        te::se::Rule* ruleItem = new te::se::Rule;
        std::string ruleName = "[" + pairMinMax[t].first + ", " + pairMinMax[t].second + "[";
        std::string* ruleNamePtr = new std::string(ruleName);
        ruleItem->setName(ruleNamePtr);
        ruleItem->setFilter(te::fe::CreateFilterByStep(attrName, pairMinMax[t].first, pairMinMax[t].second));

        rules.push_back(ruleItem);
      }
    }

    /*!
      \brief It groups the values defined by a range of iterators using the standard deviation algorithm.

      \param begin          The iterator associated to the first element value.
      \param end            The iterator associated to the last element value.
      \param nDevs          The number of deviations.
      \param rules         The container of rules items.
      \param rmean          The mean value.
      \param precision      The precision to be used in the conversion of the values.
      \param countElements  The flag indicating if the counting of elements must be done.

      \output               The groups will be stored in the container of legend items.
    */
    template<class iterator>
    void GroupingByStdDeviation(std::string attrName, iterator begin, iterator end, double nDevs, std::vector<te::se::Rule*>& rules,
      std::string& meanTitle, int precision = 0)
    {
      // Compute min, max and mean
      double min = std::numeric_limits<double>::max();
      double max = -std::numeric_limits<double>::max();
      long double  sum = 0.;
      long double  sm2 = 0.;

      iterator it = begin;
      while (it < end)
      {
        min = MIN(min, *it);
        max = MAX(max, *it);
        sum += (*it);
        sm2 += ((*it) * (*it));
        ++it;
      }

      double count = (double)(end - begin);
      double mean = (double)(sum / count);
      long double var = (sm2 / count) - (mean * mean);
      double stdDev = sqrt(var);

      double slice = stdDev * nDevs;

      std::vector<te::se::Rule*> aux;

      std::string strMean = te::common::Convert2String(mean, precision);

      double val = mean;
      while (val - slice > min - slice)
      {
        te::se::Rule* ruleItem = new te::se::Rule;

        double v = val - slice;
        std::string ruleName = "[" + te::common::Convert2String(v, precision) + ", " + te::common::Convert2String(val, precision) + "[";
        std::string* ruleNamePtr = new std::string(ruleName);
        ruleItem->setName(ruleNamePtr);
        ruleItem->setFilter(te::fe::CreateFilterByStep(attrName, te::common::Convert2String(v, precision), te::common::Convert2String(val, precision)));

        aux.push_back(ruleItem);

        val = v;
      }

      std::vector<te::se::Rule*>::reverse_iterator sit;
      for (sit = aux.rbegin(); sit != aux.rend(); ++sit)
        rules.push_back(*sit);

      meanTitle = TE_TR("Mean - ") + strMean;

      te::se::Rule* ruleItemMean = new te::se::Rule;
      std::string* ruleNamePtr = new std::string(meanTitle);
      ruleItemMean->setName(ruleNamePtr);
      ruleItemMean->setFilter(te::fe::CreateFilterByStep(attrName, te::common::Convert2String(mean, precision), te::common::Convert2String(mean, precision)));
      rules.push_back(ruleItemMean);

      val = mean;
      while (val + slice < max + slice)
      {
        te::se::Rule* ruleItem = new te::se::Rule;

        double v = val + slice;
        std::string ruleName = "[" + te::common::Convert2String(v, precision) + ", " + te::common::Convert2String(val, precision) + "[";
        std::string* ruleNamePtr = new std::string(ruleName);
        ruleItem->setName(ruleNamePtr);
        ruleItem->setFilter(te::fe::CreateFilterByStep(attrName, te::common::Convert2String(v, precision), te::common::Convert2String(val, precision)));

        aux.push_back(ruleItem);

        val = v;
      }
    }
  }      // end namespace map
}        // end namespace te

#endif   //__TERRALIB_MAPTOOLS_INTERNAL_GROUPINGALGORITHMS_H