contrib/psg/src/peersim/util/IncrementalStats.java

   1 /*
   2  * Copyright (c) 2003-2005 The BISON Project
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License version 2 as
   6  * published by the Free Software Foundation.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this program; if not, write to the Free Software
  15  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16  *
  17  */
  18
  19 package peersim.util;
  20
  21 /**
  22 * A class that can keep track of some statistics like variance, average, min,
  23 * max incrementally. That is, when adding a new data item, it updates the
  24 * statistics.
  25 */
  26 public class IncrementalStats {
  27
  28
  29 // ===================== fields ========================================
  30 // =====================================================================
  31
  32
  33 private double min;
  34
  35 private double max;
  36
  37 private double sum;
  38
  39 private double sqrsum;
  40
  41 private int n;
  42
  43 private int countmin;
  44
  45 private int countmax;
  46
  47 // ====================== initialization ==============================
  48 // ====================================================================
  49
  50
  51 /** Calls {@link #reset}. */
  52 public IncrementalStats() { reset(); }
  53
  54 // --------------------------------------------------------------------
  55
  56 /** Resets the statistics to reflect the zero elements set.
  57 * Min and max are set to positive and negative infinity, respectively.
  58 */
  59 public void reset() {
  60
  61         countmin=0;
  62         countmax=0;
  63         min = Double.POSITIVE_INFINITY;
  64         max = Double.NEGATIVE_INFINITY;
  65         sum = 0.0;
  66         sqrsum = 0.0;
  67         n = 0;
  68 }
  69
  70
  71 // ======================== methods ===================================
  72 // ====================================================================
  73
  74
  75 /** Updates the statistics according to this element. It calls
  76 * <code>add(item,1)</code>.
  77 * @see #add(double,int) */
  78 public final void add( double item ) { add(item,1); }
  79
  80 // --------------------------------------------------------------------
  81
  82 /** Updates the statistics assuming element <code>item</code> is added
  83 * <code>k</code> times.*/
  84 public void add( double item, int k ) {
  85
  86         if( item < min )
  87         {
  88                 min = item;
  89                 countmin = 0;
  90         }
  91         if( item == min ) countmin+=k;
  92         if( item > max )
  93         {
  94                 max = item;
  95                 countmax = 0;
  96         }
  97         if(item == max) countmax+=k;
  98         n+=k;
  99         if( k == 1 )
 100         {
 101                 sum += item;
 102                 sqrsum += item*item;
 103         }
 104         else
 105         {
 106                 sum += item*k;
 107                 sqrsum += item*item*k;
 108         }
 109 }
 110
 111 // --------------------------------------------------------------------
 112
 113 /** The number of data items processed so far */
 114 public int getN() { return n; }
 115
 116 // --------------------------------------------------------------------
 117
 118 /** The maximum of the data items */
 119 public double getMax() { return max; }
 120
 121 // --------------------------------------------------------------------
 122
 123 /** The minimum of the data items */
 124 public double getMin() { return min; }
 125
 126 // --------------------------------------------------------------------
 127
 128 /** Returns the number of data items whose value equals the maximum. */
 129 public int getMaxCount() { return countmax; }
 130
 131 // --------------------------------------------------------------------
 132
 133 /** Returns the number of data items whose value equals the minimum. */
 134 public int getMinCount() { return countmin; }
 135
 136 // --------------------------------------------------------------------
 137
 138 /** The sum of the data items */
 139 public double getSum() { return sum; }
 140
 141 // --------------------------------------------------------------------
 142
 143 /** The sum of the squares of the data items */
 144 public double getSqrSum() { return sqrsum; }
 145
 146 // --------------------------------------------------------------------
 147
 148 /** The average of the data items */
 149 public double getAverage() { return sum/n; }
 150
 151 // --------------------------------------------------------------------
 152
 153 /** The empirical variance of the data items. Guaranteed to be larger or
 154 equal to 0.0. If due to rounding errors the value becomes negative,
 155 it returns 0.0.*/
 156 public double getVar() {
 157
 158         double var=
 159                 (((double)n) / (n-1)) * (sqrsum/n - getAverage()*getAverage());
 160         return (var>=0.0?var:0.0);
 161         // XXX note that we have very little possibility to increase numeric
 162         // stability if this class is "greedy", ie, if it has no memory
 163         // In a more precise implementation we could delay the calculation of
 164         // statistics and store the data in some intelligent structure
 165 }
 166
 167 // --------------------------------------------------------------------
 168
 169 /** the empirical standard deviation of the data items */
 170 public double getStD() { return Math.sqrt(getVar()); }
 171
 172 // --------------------------------------------------------------------
 173
 174 /**
 175 * Prints the following quantities separated by spaces in a single line
 176 * in this order.
 177 * Minimum, maximum, number of items, average, variance, number of minimal
 178 * items, number of maximal items.
 179 */
 180 public String toString() {
 181
 182         return min+" "+max+" "+n+" "+sum/n+" "+getVar()+" "+
 183                 countmin+" "+countmax;
 184 }
 185
 186 }
 187