include/anna/statistics/Accumulator.hpp

   1 // ANNA - Anna is Not Nothingness Anymore                                                         //
   2 //                                                                                                //
   3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
   4 //                                                                                                //
   5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
   6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
   7
   8
   9 #ifndef anna_statistics_Accumulator_hpp
  10 #define anna_statistics_Accumulator_hpp
  11
  12 #include <anna/core/RuntimeException.hpp>
  13 #include <anna/core/functions.hpp>
  14
  15 // Standard
  16 #include <string>
  17
  18 namespace anna {
  19 namespace xml {
  20 class Node;
  21 }
  22 }
  23
  24
  25 namespace anna {
  26
  27 namespace statistics {
  28
  29
  30 class Operation {
  31 public:
  32
  33   enum Type {
  34     //Sum = 0, // is not very useful
  35     Average,
  36     StandardDeviation,
  37     BesselStandardDeviation, //This correction (the use of N - 1 instead of N) is known as Bessel's correction
  38     Minimum,
  39     Maximum
  40   };
  41 };
  42
  43 typedef struct {
  44
  45   unsigned long long Size;                           // Sample size
  46   double Sum;                                        // Accumulated sum
  47   double SquareSum;                                  // Accumulated sum of square values
  48   double Average;                                    // Current average
  49   //double SquareSumSampleDeviation;                   // Current total sum for square deviation items;
  50   double MinimumProcessed;                           // Minimum value processed
  51   double MaximumProcessed;                           // Maximum value processed
  52   anna::Millisecond MinimumEventTimestampMs;       // Timestamp (ms) for minimum event
  53   anna::Millisecond MaximumEventTimestampMs;       // Timestamp (ms) for maximum event
  54   anna::Millisecond LastResetEventTimestampMs;     // Timestamp (ms) for last statistics reset
  55
  56
  57   void reset() {
  58     Size = (unsigned long long)0;
  59     Sum = (double)0;
  60     SquareSum = (double)0;
  61     Average = (double)0;
  62     //SquareSumSampleDeviation = (double)0;
  63     MinimumProcessed = (double)0;
  64     MaximumProcessed = (double)0;
  65     MinimumEventTimestampMs = (anna::Millisecond)0;
  66     MaximumEventTimestampMs = (anna::Millisecond)0;
  67     LastResetEventTimestampMs = anna::Millisecond::getTime();
  68   }
  69
  70 } _concept_data_t;
  71
  72 typedef std::map <int, _concept_data_t> _concept_data_map_t;
  73 typedef std::map <int, _concept_data_t>::const_iterator _concept_data_map_iter;
  74
  75
  76
  77
  78 //------------------------------------------------------------------------------
  79 //------------------------------------------------------------ class Accumulator
  80 //------------------------------------------------------------------------------
  81 /**
  82  * Accumulated data information for statistic sample.
  83  * It can manage a set of concepts at the same time.
  84  *
  85  * @short Contains statistical sample information
  86  */
  87 class Accumulator {
  88 public:
  89
  90   /**
  91   * Constructor.
  92   *
  93   * @param name Accumulator name
  94   */
  95   Accumulator(const std::string &name) : a_name(name) {};
  96
  97   /**
  98   * Destructor.
  99   */
 100   ~Accumulator();
 101
 102   /**
 103   * Adds a new statistic concept through the accumulator, to ease the concept name creation,
 104   * which will be a string defined by: concept name + ': ' + accumulator name.
 105   *
 106   * @param description Concept description; e.g.: processing time, messages size, etc.
 107   * @param unit Concept unit description
 108   * @param integerNatureSample Most of cases we will measure 'time' with the unit which force integer values
 109   *                            (is more intuitive 850 msecs than 0,850 secs). Then, it is @em true by default.
 110   *                            This is useful to advice better representation for some indicators like minimum/maximum
 111   *                             within integer samples.
 112   *
 113   * @return Assigned concept identification number (sequence)
 114   */
 115   int addConcept(const std::string & description, const std::string & unit, const bool & integerNatureSample = true) throw();
 116
 117
 118   /**
 119   * Process new value for the sample.
 120   *
 121   * @param conceptId statistical concept processed
 122   * @param value Value for processed item
 123   *
 124   * @see reset()
 125   */
 126   void process(const int & conceptId, const double & value) throw(anna::RuntimeException);
 127
 128
 129   /**
 130   * Reset sample for all concepts
 131   *
 132   * @see process()
 133   */
 134   void reset(void) throw();
 135
 136
 137   /**
 138   * Reset sample for provided concept
 139   *
 140   * @param conceptId Concept identification to be reset
 141   *
 142   * @see process()
 143   */
 144   void reset(const int & conceptId) throw(anna::RuntimeException);
 145
 146
 147   /**
 148   * Copy operator
 149   *
 150   * @param accumulator Class instance source of data
 151   *
 152   * @return Returns copied reference
 153   */
 154   const Accumulator & operator = (const Accumulator & accumulator);
 155
 156
 157
 158   // Gets
 159
 160   /**
 161   * Gets current sample size for any concept id
 162   *
 163   * @param conceptId Concept identification
 164   *
 165   * @return Sample size
 166   *
 167   * @see getValue()
 168   * @see asXML()
 169   */
 170   unsigned long long int sampleSize(const int & conceptId) const throw(anna::RuntimeException);
 171
 172
 173   /**
 174   * Get statistical information
 175   *
 176   * @param conceptId Statistical concept
 177   * @param operation Solicited operation
 178   *
 179   * @return Value for solicited conceptId/operation
 180   *
 181   * @see sampleSize()
 182   * @see asXML()
 183   */
 184   double getValue(const int & conceptId, const Operation::Type & operation) const throw(anna::RuntimeException);
 185
 186
 187   /**
 188   * Class string representation
 189   *
 190   * @param numberOfDecimals Number of float decimals at representation string. Default is 2.
 191   *
 192   * @return String with class content
 193   */
 194   std::string asString(const int & numberOfDecimals = 2) const throw();
 195
 196
 197   /**
 198   * Class XML representation
 199   *
 200   * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
 201   *
 202   * @return XML with class content
 203   */
 204   anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const throw();
 205
 206
 207 private:
 208
 209   std::string a_name;
 210
 211   void initialize(const int & conceptId) throw();
 212   _concept_data_t * getConcept(const int & conceptId) const throw(anna::RuntimeException);
 213   // Return NULL if no data is found for the concept Id
 214   // Launch exception if concept id is not a valid concept registered at Engine
 215
 216   /*mutable */_concept_data_map_t a_concept_data_map;
 217
 218   std::string floatFormat(const int & numberOfDecimals) const throw();
 219
 220   double getStandardDeviation(const _concept_data_t * conceptData) const throw(anna::RuntimeException);
 221   double getBesselStandardDeviation(const _concept_data_t * conceptData) const throw(anna::RuntimeException);
 222 };
 223
 224 }
 225 }
 226
 227 #endif