Statistics
| Branch: | Revision:

root / include / cstddev.h @ master

History | View | Annotate | Download (10 KB)

1
//==========================================================================
2
//  CSTDDEV.H - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//
7
//  Declaration of the following classes:
8
//    cStdDev: basic statistics (mean, stddev, min, max, etc)
9
//    cWeightedStdDev: weighted version
10
//
11
//==========================================================================
12

    
13
/*--------------------------------------------------------------*
14
  Copyright (C) 1992-2008 Andras Varga
15
  Copyright (C) 2006-2008 OpenSim Ltd.
16

17
  This file is distributed WITHOUT ANY WARRANTY. See the file
18
  `license' for details on this and other legal matters.
19
*--------------------------------------------------------------*/
20

    
21
#ifndef __CSTDDEV_H
22
#define __CSTDDEV_H
23

    
24
#include <stdio.h>
25
#include "cstatistic.h"
26

    
27
NAMESPACE_BEGIN
28

    
29
/**
30
 * Statistics class to collect min, max, mean, and standard deviation.
31
 *
32
 * @ingroup Statistics
33
 */
34
class SIM_API cStdDev : public cStatistic
35
{
36
  protected:
37
    long num_vals;
38
    double min_vals, max_vals;
39
    double sum_vals, sqrsum_vals;
40

    
41
  protected:
42
    void doMerge(const cStatistic *other);
43

    
44
  public:
45
    /** @name Constructors, destructor, assignment. */
46
    //@{
47

    
48
    /**
49
     * Copy constructor.
50
     */
51
    cStdDev(const cStdDev& r) : cStatistic() {setName(r.getName());operator=(r);}
52

    
53
    /**
54
     * Constructor.
55
     */
56
    explicit cStdDev(const char *name=NULL);
57

    
58
    /**
59
     * Destructor.
60
     */
61
    virtual ~cStdDev() {}
62

    
63
    /**
64
     * Assignment operator. The name member is not copied; see cNamedObject's operator=() for more details.
65
     */
66
    cStdDev& operator=(const cStdDev& res);
67
    //@}
68

    
69
    /** @name Redefined cObject member functions. */
70
    //@{
71

    
72
    /**
73
     * Creates and returns an exact copy of this object.
74
     * See cObject for more details.
75
     */
76
    virtual cStdDev *dup() const  {return new cStdDev(*this);}
77

    
78
    /**
79
     * Produces a one-line description of the object's contents.
80
     * See cObject for more details.
81
     */
82
    virtual std::string info() const;
83

    
84
    /**
85
     * Produces a multi-line description of the object.
86
     * See cObject for more details.
87
     */
88
    virtual std::string detailedInfo() const;
89

    
90
    /**
91
     * Serializes the object into an MPI send buffer.
92
     * Used by the simulation kernel for parallel execution.
93
     * See cObject for more details.
94
     */
95
    virtual void parsimPack(cCommBuffer *buffer);
96

    
97
    /**
98
     * Deserializes the object from an MPI receive buffer
99
     * Used by the simulation kernel for parallel execution.
100
     * See cObject for more details.
101
     */
102
    virtual void parsimUnpack(cCommBuffer *buffer);
103
    //@}
104

    
105
    /** @name Redefined cStatistic functions. */
106
    //@{
107

    
108
    /**
109
     * Collects one value.
110
     */
111
    virtual void collect(double value);
112

    
113
    /**
114
     * Convenience method, delegates to collect(double).
115
     */
116
    virtual void collect(SimTime value) {collect(value.dbl());}
117

    
118
    /**
119
     * Updates this object with data coming from another statistics
120
     * object -- as if this object had collected observations fed
121
     * into the other object as well. Throws an error if the other
122
     * object is weighted statistics (see isWeighted()).
123
     */
124
    virtual void merge(const cStatistic *other);
125

    
126
    /**
127
     * Returns false, because this class does not collect weighted statistics.
128
     */
129
    virtual bool isWeighted() const  {return false;}
130

    
131
    /**
132
     * Returns the number of observations collected.
133
     */
134
    virtual long getCount() const  {return num_vals;}
135

    
136
    /**
137
     * Returns the sum of the values.
138
     */
139
    virtual double getSum() const  {return sum_vals;}
140

    
141
    /**
142
     * Returns the squared sum of the collected values.
143
     */
144
    virtual double getSqrSum() const  {return sqrsum_vals;}
145

    
146
    /**
147
     * Returns the minimum of the collected values.
148
     */
149
    virtual double getMin() const  {return min_vals;}
150

    
151
    /**
152
     * Returns the maximum of the collected values.
153
     */
154
    virtual double getMax() const  {return max_vals;}
155

    
156
    /**
157
     * Returns the mean of the observations.
158
     * Returns 0.0 if nothing was collected yet.
159
     */
160
    virtual double getMean() const  {return num_vals==0 ? 0 : sum_vals/num_vals;}
161

    
162
    /**
163
     * Returns the standard deviation of the observations.
164
     */
165
    virtual double getStddev() const;
166

    
167
    /**
168
     * Returns the variance of the observations collected.
169
     */
170
    virtual double getVariance() const;
171

    
172
    /**
173
     * Since this is unweighted statistics, the sum of weights is getCount().
174
     */
175
    virtual double getWeights() const  {return getCount();}
176

    
177
    /**
178
     * Since this is unweighted statistics, the sum of weight*value products
179
     * is getSum().
180
     */
181
    virtual double getWeightedSum() const  {return getSum();}
182

    
183
    /**
184
     * Since this is unweighted statistics, the sum of squared weights
185
     * is getCount().
186
     */
187
    virtual double getSqrSumWeights() const  {return getCount();}
188

    
189
    /**
190
     * Since this is unweighted statistics, the sum of weight*value*value
191
     * products is getSqrSum().
192
     */
193
    virtual double getWeightedSqrSum() const  {return getSqrSum();}
194

    
195
    /**
196
     * Returns numbers from a normal distribution with the current mean and
197
     * standard deviation.
198
     */
199
    virtual double random() const;
200

    
201
    /**
202
     * Clears the results collected so far.
203
     */
204
    virtual void clearResult();
205

    
206
    /**
207
     * Writes the contents of the object into a text file.
208
     */
209
    virtual void saveToFile(FILE *) const;
210

    
211
    /**
212
     * Reads the object data from a file written out by saveToFile()
213
     * (or written by hand)
214
     */
215
    virtual void loadFromFile(FILE *);
216
    //@}
217
};
218

    
219

    
220

    
221
/**
222
 * Statistics class to collect doubles and calculate weighted statistics
223
 * of them. It can be used for example to calculate time average.
224
 *
225
 * @ingroup Statistics
226
 */
227
class SIM_API cWeightedStdDev : public cStdDev
228
{
229
  protected:
230
    double sum_weights;
231
    double sum_weighted_vals;
232
    double sum_squared_weights;
233
    double sum_weights_squared_vals;
234

    
235
  public:
236
    /** @name Constructors, destructor, assignment. */
237
    //@{
238

    
239
    /**
240
     * Constructors, destructor, duplication and assignment.
241
     */
242
    cWeightedStdDev(const cWeightedStdDev& r) : cStdDev() {setName(r.getName());operator=(r);}
243

    
244
    /**
245
     * Constructors, destructor, duplication and assignment.
246
     */
247
    explicit cWeightedStdDev(const char *name=NULL) : cStdDev(name)  {sum_weights=sum_weighted_vals=sum_squared_weights=sum_weights_squared_vals=0.0;}
248

    
249
    /**
250
     * Constructors, destructor, duplication and assignment.
251
     */
252
    virtual ~cWeightedStdDev() {}
253

    
254
    /**
255
     * Assignment operator. The name member is not copied; see cNamedObject's operator=() for more details.
256
     */
257
    cWeightedStdDev& operator=(const cWeightedStdDev& res);
258
    //@}
259

    
260
    /** @name Redefined cObject member functions. */
261
    //@{
262

    
263
    /**
264
     * Creates and returns an exact copy of this object.
265
     * See cObject for more details.
266
     */
267
    virtual cWeightedStdDev *dup() const  {return new cWeightedStdDev(*this);}
268

    
269
    /**
270
     * Produces a one-line description of the object's contents.
271
     * See cObject for more details.
272
     */
273
    virtual std::string info() const;
274

    
275
    /**
276
     * Serializes the object into an MPI send buffer.
277
     * Used by the simulation kernel for parallel execution.
278
     * See cObject for more details.
279
     */
280
    virtual void parsimPack(cCommBuffer *buffer);
281

    
282
    /**
283
     * Deserializes the object from an MPI receive buffer
284
     * Used by the simulation kernel for parallel execution.
285
     * See cObject for more details.
286
     */
287
    virtual void parsimUnpack(cCommBuffer *buffer);
288
    //@}
289

    
290
    /** @name Redefined cStatistic functions. */
291
    //@{
292

    
293
    /**
294
     * Collects one value.
295
     */
296
    virtual void collect(double value)  {collect2(value,1.0);}
297

    
298
    /**
299
     * Convenience method, delegates to collect(double).
300
     */
301
    virtual void collect(SimTime value) {collect(value.dbl());}
302

    
303
    /**
304
     * Returns true, because this class collects weighted statistics.
305
     */
306
    virtual bool isWeighted() const  {return true;}
307

    
308
    /**
309
     * Collects one value with a given weight.
310
     */
311
    virtual void collect2(double value, double weight);
312

    
313
    /**
314
     * Convenience method, delegates to collect2(double, double).
315
     */
316
    virtual void collect2(SimTime value, double weight) {collect2(value.dbl(), weight);}
317

    
318
    /**
319
     * Convenience method, delegates to collect2(double, double).
320
     */
321
    virtual void collect2(double value, SimTime weight) {collect2(value, weight.dbl());}
322

    
323
    /**
324
     * Convenience method, delegates to collect2(double, double).
325
     */
326
    virtual void collect2(SimTime value, SimTime weight) {collect2(value.dbl(), weight.dbl());}
327

    
328
    /**
329
     * Updates this object with data coming from another statistics
330
     * object -- as if this object had collected observations fed
331
     * into the other object as well.
332
     */
333
    virtual void merge(const cStatistic *other);
334

    
335
    /**
336
     * Clears the results collected so far.
337
     */
338
    virtual void clearResult();
339

    
340
    /**
341
     * Returns the mean of the observations collected.
342
     * Returns 0.0 if nothing was collected yet.
343
     */
344
    virtual double getMean() const  {return sum_weights==0 ? 0 : sum_weighted_vals / sum_weights;}
345

    
346
    /**
347
     * Returns the variance of the observations collected.
348
     */
349
    virtual double getVariance() const;
350

    
351
    /**
352
     * Returns the sum of weights.
353
     */
354
    virtual double getWeights() const  {return sum_weights;}
355

    
356
    /**
357
     * Returns the sum of weight*value products.
358
     */
359
    virtual double getWeightedSum() const  {return sum_weighted_vals;}
360

    
361
    /**
362
     * Returns the sum of squared weights.
363
     */
364
    virtual double getSqrSumWeights() const  {return sum_squared_weights;}
365

    
366
    /**
367
     * Returns the sum of weight*value*value products.
368
     */
369
    virtual double getWeightedSqrSum() const  {return sum_weights_squared_vals;}
370

    
371
    /**
372
     * Writes the contents of the object into a text file.
373
     */
374
    virtual void saveToFile(FILE *) const;
375

    
376
    /**
377
     * Reads the object data from a file, in the format written out by saveToFile().
378
     */
379
    virtual void loadFromFile(FILE *);
380
    //@}
381
};
382

    
383
NAMESPACE_END
384

    
385
#endif
386