include/anna/statistics/Accumulator.hpp

   1 // ANNA - Anna is Not Nothingness Anymore
   2 //
   3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
   4 //
   5 // https://bitbucket.org/testillano/anna
   6 //
   7 // Redistribution and use in source and binary forms, with or without
   8 // modification, are permitted provided that the following conditions
   9 // are met:
  10 //
  11 //     * Redistributions of source code must retain the above copyright
  12 // notice, this list of conditions and the following disclaimer.
  13 //     * Redistributions in binary form must reproduce the above
  14 // copyright notice, this list of conditions and the following disclaimer
  15 // in the documentation and/or other materials provided with the
  16 // distribution.
  17 //     * Neither the name of Google Inc. nor the names of its
  18 // contributors may be used to endorse or promote products derived from
  19 // this software without specific prior written permission.
  20 //
  21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 //
  33 // Authors: eduardo.ramos.testillano@gmail.com
  34 //          cisco.tierra@gmail.com
  35
  36
  37 #ifndef anna_statistics_Accumulator_hpp
  38 #define anna_statistics_Accumulator_hpp
  39
  40 #include <anna/core/RuntimeException.hpp>
  41 #include <anna/core/functions.hpp>
  42
  43 // Standard
  44 #include <string>
  45
  46 namespace anna {
  47 namespace xml {
  48 class Node;
  49 }
  50 }
  51
  52
  53 namespace anna {
  54
  55 namespace statistics {
  56
  57
  58 class Operation {
  59 public:
  60
  61   enum Type {
  62     //Sum = 0, // is not very useful
  63     Average,
  64     StandardDeviation,
  65     BesselStandardDeviation, //This correction (the use of N - 1 instead of N) is known as Bessel's correction
  66     Minimum,
  67     Maximum
  68   };
  69 };
  70
  71 typedef struct {
  72
  73   unsigned long long Size;                           // Sample size
  74   double Sum;                                        // Accumulated sum
  75   double SquareSum;                                  // Accumulated sum of square values
  76   double Average;                                    // Current average
  77   //double SquareSumSampleDeviation;                   // Current total sum for square deviation items;
  78   double MinimumProcessed;                           // Minimum value processed
  79   double MaximumProcessed;                           // Maximum value processed
  80   anna::Millisecond MinimumEventTimestampMs;       // Timestamp (ms) for minimum event
  81   anna::Millisecond MaximumEventTimestampMs;       // Timestamp (ms) for maximum event
  82   anna::Millisecond LastResetEventTimestampMs;     // Timestamp (ms) for last statistics reset
  83
  84
  85   void reset() {
  86     Size = (unsigned long long)0;
  87     Sum = (double)0;
  88     SquareSum = (double)0;
  89     Average = (double)0;
  90     //SquareSumSampleDeviation = (double)0;
  91     MinimumProcessed = (double)0;
  92     MaximumProcessed = (double)0;
  93     MinimumEventTimestampMs = (anna::Millisecond)0;
  94     MaximumEventTimestampMs = (anna::Millisecond)0;
  95     LastResetEventTimestampMs = anna::Millisecond::getTime();
  96   }
  97
  98 } _concept_data_t;
  99
 100 typedef std::map <int, _concept_data_t> _concept_data_map_t;
 101 typedef std::map <int, _concept_data_t>::const_iterator _concept_data_map_iter;
 102
 103
 104
 105
 106 //------------------------------------------------------------------------------
 107 //------------------------------------------------------------ class Accumulator
 108 //------------------------------------------------------------------------------
 109 /**
 110  * Accumulated data information for statistic sample.
 111  * It can manage a set of concepts at the same time.
 112  *
 113  * @short Contains statistical sample information
 114  */
 115 class Accumulator {
 116 public:
 117
 118   /**
 119   * Constructor.
 120   */
 121   Accumulator();
 122
 123   /**
 124   * Destructor.
 125   */
 126   ~Accumulator();
 127
 128
 129   /**
 130   * Process new value for the sample.
 131   *
 132   * @param conceptId statistical concept processed
 133   * @param value Value for processed item
 134   *
 135   * @see reset()
 136   */
 137   void process(const int & conceptId, const double & value) throw(anna::RuntimeException);
 138
 139
 140   /**
 141   * Reset sample for all concepts
 142   *
 143   * @see process()
 144   */
 145   void reset(void) throw();
 146
 147
 148   /**
 149   * Reset sample for provided concept
 150   *
 151   * @param conceptId Concept identification to be reset
 152   *
 153   * @see process()
 154   */
 155   void reset(const int & conceptId) throw(anna::RuntimeException);
 156
 157
 158   /**
 159   * Copy operator
 160   *
 161   * @param accumulator Class instance source of data
 162   *
 163   * @return Returns copied reference
 164   */
 165   const Accumulator & operator = (const Accumulator & accumulator);
 166
 167
 168
 169   // Gets
 170
 171   /**
 172   * Gets current sample size for any concept id
 173   *
 174   * @param conceptId Concept identification
 175   *
 176   * @return Sample size
 177   *
 178   * @see getValue()
 179   * @see asXML()
 180   */
 181   unsigned long long int sampleSize(const int & conceptId) const throw(anna::RuntimeException);
 182
 183
 184   /**
 185   * Get statistical information
 186   *
 187   * @param conceptId Statistical concept
 188   * @param operation Solicited operation
 189   *
 190   * @return Value for solicited conceptId/operation
 191   *
 192   * @see sampleSize()
 193   * @see asXML()
 194   */
 195   double getValue(const int & conceptId, const Operation::Type & operation) const throw(anna::RuntimeException);
 196
 197
 198   /**
 199   * Class string representation
 200   *
 201   * @param numberOfDecimals Number of float decimals at representation string. Default is 2.
 202   *
 203   * @return String with class content
 204   */
 205   std::string asString(const int & numberOfDecimals = 2) const throw();
 206
 207
 208   /**
 209   * Class XML representation
 210   *
 211   * @param numberOfDecimals Number of float decimals at XML representation. Default is 2.
 212   *
 213   * @return XML with class content
 214   */
 215   anna::xml::Node* asXML(anna::xml::Node* parent, const int & numberOfDecimals = 2) const throw();
 216
 217
 218 private:
 219
 220   void initialize(const int & conceptId) throw();
 221   _concept_data_t * getConcept(const int & conceptId) const throw(anna::RuntimeException);
 222   // Return NULL if no data is found for the concept Id
 223   // Launch exception if concept id is not a valid concept registered at Engine
 224
 225   /*mutable */_concept_data_map_t a_concept_data_map;
 226
 227   std::string floatFormat(const int & numberOfDecimals) const throw();
 228
 229   double getStandardDeviation(const _concept_data_t * conceptData) const throw(anna::RuntimeException);
 230   double getBesselStandardDeviation(const _concept_data_t * conceptData) const throw(anna::RuntimeException);
 231 };
 232
 233 }
 234 }
 235
 236 #endif