Statistics
| Branch: | Revision:

root / include / chistogram.h @ ffa9279f

History | View | Annotate | Download (11.8 KB)

1 01873262 Georg Kunz
//==========================================================================
2
//  CHISTOGRAM.H - part of
3
//
4
//                     OMNeT++/OMNEST
5
//            Discrete System Simulation in C++
6
//
7
//
8
//  Declaration of the following classes:
9
//    cHistogramBase        : common base class for histogram classes
10
//      cHistogram          : equi-distant histogram
11
//        cLongHistogram    : long int distribution
12
//        cDoubleHistogram  : double distribution
13
//
14
//==========================================================================
15
16
/*--------------------------------------------------------------*
17
  Copyright (C) 1992-2008 Andras Varga
18
  Copyright (C) 2006-2008 OpenSim Ltd.
19

20
  This file is distributed WITHOUT ANY WARRANTY. See the file
21
  `license' for details on this and other legal matters.
22
*--------------------------------------------------------------*/
23
24
#ifndef __CHISTOGRAM_H
25
#define __CHISTOGRAM_H
26
27
#include "cdensityestbase.h"
28
29
NAMESPACE_BEGIN
30
31
32
/**
33
 * Base class for histogram classes. It adds a vector of counters to
34
 * cDensityEstBase.
35
 *
36
 * @ingroup Statistics
37
 */
38
class SIM_API cHistogramBase : public cDensityEstBase
39
{
40
  protected:
41
    int num_cells;        // nr. of categories
42
    unsigned *cellv;      // array of counters
43
44
  protected:
45
    // abstract method in cDensityEstBase
46
    virtual void doMergeCellValues(const cDensityEstBase *other);
47
48
  public:
49
    /** @name Constructors, destructor, assignment. */
50
    //@{
51
52
    /**
53
     * Copy constructor.
54
     */
55
    cHistogramBase(const cHistogramBase& r) : cDensityEstBase(r)
56
        {setName(r.getName());cellv=NULL;operator=(r);}
57
58
    /**
59
     * Constructor.
60
     */
61
    cHistogramBase(const char *name, int numcells);
62
63
    /**
64
     * Destructor.
65
     */
66
    virtual ~cHistogramBase();
67
68
    /**
69
     * Assignment operator. The name member is not copied; see cNamedObject's operator=() for more details.
70
     */
71
    cHistogramBase& operator=(const cHistogramBase& res);
72
    //@}
73
74
    /** @name Redefined cObject member functions. */
75
    //@{
76
77
    /* No dup() because this is an abstract class. */
78
79
    /**
80
     * Serializes the object into an MPI send buffer.
81
     * Used by the simulation kernel for parallel execution.
82
     * See cObject for more details.
83
     */
84
    virtual void parsimPack(cCommBuffer *buffer);
85
86
    /**
87
     * Deserializes the object from an MPI receive buffer
88
     * Used by the simulation kernel for parallel execution.
89
     * See cObject for more details.
90
     */
91
    virtual void parsimUnpack(cCommBuffer *buffer);
92
    //@}
93
94
    /** @name Redefined member functions from cStatistic and its subclasses. */
95
    //@{
96
97
    /**
98
     * Clears the results collected so far.
99
     */
100
    virtual void clearResult();
101
102
    /**
103
     * Transforms the table of pre-collected values into an internal
104
     * histogram structure.
105
     */
106
    virtual void transform();
107
108
    /**
109
     * Returns the number of histogram cells used.
110
     */
111
    virtual int getNumCells() const;
112
113
    /**
114
     * Writes the contents of the object into a text file.
115
     */
116
    virtual void saveToFile(FILE *) const;
117
118
    /**
119
     * Reads the object data from a file, in the format written out by saveToFile().
120
     */
121
    virtual void loadFromFile(FILE *);
122
    //@}
123
124
    /** @name New member functions. */
125
    //@{
126
    /**
127
     * Sets the number of cells. Cannot be called when the cells have been
128
     * set up already.
129
     */
130
    virtual void setNumCells(int numcells);
131
    //@}
132
};
133
134
135
/**
136
 * Implements an equidistant histogram that can operate in two modes.
137
 * In INTEGERS mode, cell boundaries are whole numbers; in DOUBLES mode,
138
 * they can be real numbers. The operating mode can be chosen with a
139
 * constructor argument or with the setMode() method; the default behavior
140
 * is to choose the mode automatically, by inspecting precollected
141
 * observations.
142
 *
143
 * By default, the number of cells is chosen automatically, and the histogram
144
 * range is determined by precollecting a number of observations and extending
145
 * their range by a range extension factor.
146
 *
147
 * It is possible to explicitly set any of the following values (and the rest
148
 * will be chosen or computed automatically): number of cells; cell size;
149
 * number of observations to precollect; range extension factor; range lower
150
 * bound; range upper bound. See the setNumCells(), setCellSize(),
151
 * setNumFirstVals(), setRangeAuto(), setRangeAutoUpper(), and
152
 * setRangeAutoLower() methods (many of them are inherited from
153
 * cDensityEstBase and cHistogramBase).
154
 *
155
 * Especially in INTEGERS mode, if the cells cannot be set up to satisfy all
156
 * explicitly given constraints (for example, if the explicitly specified
157
 * range is not an integer multiple of the explicitly specified cell size),
158
 * an error will be thrown.
159
 *
160
 * Informational defaults for the various configuration values (subject to change
161
 * without notice in any release): number of values to precollect: 100;
162
 * range extension factor: 2.0; number of cells: 200 in INTEGERS mode and 30 in
163
 * DOUBLES mode.
164
 *
165
 * Examples:
166
 *
167
 * Automatic mode:
168
 *
169
 * \code
170
 * cHistogram h("histogram");
171
 * \endcode
172
 *
173
 * Setting up a 50-cell histogram on the range [0.0, 5.0) (cell size = 0.1):
174
 *
175
 * \code
176
 * cHistogram h("histogram", 50, cHistogram::MODE_DOUBLES);
177
 * h.setRange(0,5);
178
 * \endcode
179
 *
180
 * If you only know that the numbers will be nonnegative but the exact range
181
 * is unknown:
182
 *
183
 * \code
184
 * cHistogram h("histogram");
185
 * h.setRangeAutoUpper(0);  // sets zero as lower bound
186
 * \endcode
187
 *
188
 * @ingroup Statistics
189
 */
190
class SIM_API cHistogram : public cHistogramBase
191
{
192
  public:
193
    enum Mode {MODE_AUTO, MODE_INTEGERS, MODE_DOUBLES};
194
195
  protected:
196
    Mode mode;
197
    double cellsize;  // cell/category sizes; <=0 if unset
198
199
  protected:
200
    virtual void setupRangeInteger();
201
    virtual void setupRangeDouble();
202
    virtual void getAttributesToRecord(opp_string_map& attributes);
203
204
  public:
205
    /** @name Constructors, destructor, assignment. */
206
    //@{
207
208
    /**
209
     * Copy constructor.
210
     */
211
    cHistogram(const cHistogram& r) : cHistogramBase(r)
212
        {setName(r.getName());operator=(r);}
213
214
    /**
215
     * Constructor.
216
     */
217
    explicit cHistogram(const char *name=NULL, int numcells=-1, Mode mode=MODE_AUTO);
218
219
    /**
220
     * Assignment operator. The name member is not copied; see cNamedObject's operator=() for more details.
221
     */
222
    cHistogram& operator=(const cHistogram& res);
223
    //@}
224
225
    /** @name Redefined cObject member functions. */
226
    //@{
227
228
    /* No dup() because this is an abstract class. */
229
230
    /**
231
     * Serializes the object into an MPI send buffer.
232
     * Used by the simulation kernel for parallel execution.
233
     * See cObject for more details.
234
     */
235
    virtual void parsimPack(cCommBuffer *buffer);
236
237
    /**
238
     * Deserializes the object from an MPI receive buffer
239
     * Used by the simulation kernel for parallel execution.
240
     * See cObject for more details.
241
     */
242
    virtual void parsimUnpack(cCommBuffer *buffer);
243
    //@}
244
245
  protected:
246
    /**
247
     * Called internally by collect(), this method collects a value
248
     * after the histogram has been transformed.
249
     */
250
    virtual void collectTransformed(double value);
251
252
    /**
253
     * Called internally by transform(), this method should determine and set up
254
     * the histogram range. It also calculates the cell size.
255
     */
256
    virtual void setupRange();
257
258
  public:
259
    /** @name Redefined member functions from cStatistic and its subclasses. */
260
    //@{
261
262
    /**
263
     * Returns the kth cell boundary.
264
     */
265
    virtual double getBasepoint(int k) const;
266
267
    /**
268
     * Returns the number of observations that fell into the kth histogram cell.
269
     */
270
    virtual double getCellValue(int k) const;
271
272
    /**
273
     * Returns the value of the Probability Density Function at a given x.
274
     */
275
    virtual double getPDF(double x) const;
276
277
    /**
278
     * Returns the value of the Cumulated Density Function at a given x.
279
     */
280
    virtual double getCDF(double x) const;
281
282
    /**
283
     * Returns a random number based on the distribution collected. If
284
     * no values have been collected, it returns 0; when in initial collection
285
     * phase, it returns one of the stored observations; after the histogram
286
     * has been set up, a random integer or double is returned, depending on
287
     * mode.
288
     */
289
    virtual double random() const;
290
291
    /**
292
     * Writes the contents of the object into a text file.
293
     */
294
    virtual void saveToFile(FILE *) const;
295
296
    /**
297
     * Reads the object data from a file, in the format written out by saveToFile().
298
     */
299
    virtual void loadFromFile(FILE *);
300
    //@}
301
302
    /** @name Misc. */
303
    //@{
304
    /**
305
     * Sets the histogram mode: MODE_AUTO, MODE_INTEGERS or MODE_DOUBLES.
306
     * Cannot be called when the cells have been set up already.
307
     */
308
    virtual void setMode(Mode mode);
309
310
    /**
311
     * Returns the histogram mode, which is MODE_AUTO, MODE_INTEGERS or
312
     * MODE_DOUBLES.
313
     */
314
    virtual Mode getMode() const {return mode;}
315
316
    /**
317
     * Sets the cell size. Cannot be called when the cells have been
318
     * set up already.
319
     */
320
    virtual void setCellSize(double d);
321
322
    /**
323
     * Returns the cell size, or 0 when unknow (i.e. the cells have not
324
     * been set up yet, and setCellSize() has not been called).
325
     */
326
    virtual double getCellSize() const {return cellsize;}
327
    //@}
328
329
};
330
331
332
/**
333
 * Equidistant histogram for integers. This class is just a cHistogram
334
 * preconfigured for collecting integers (MODE_INTEGERS).
335
 *
336
 * @ingroup Statistics
337
 */
338
class SIM_API cLongHistogram : public cHistogram
339
{
340
  public:
341
    /** @name Constructors, destructor, assignment. */
342
    //@{
343
    /**
344
     * Copy constructor.
345
     */
346
    cLongHistogram(const cLongHistogram& r) : cHistogram(r)
347
        {setName(r.getName());operator=(r);}
348
349
    /**
350
     * Constructor.
351
     */
352
    explicit cLongHistogram(const char *name=NULL, int numcells=-1) :
353
        cHistogram(name, numcells, MODE_INTEGERS) {}
354
355
    /**
356
     * Destructor.
357
     */
358
    virtual ~cLongHistogram() {}
359
360
    /**
361
     * Assignment operator.
362
     */
363
    cLongHistogram& operator=(const cLongHistogram& other)  {return (cLongHistogram&)cHistogram::operator=(other);}
364
    //@}
365
366
    /** @name Redefined cObject member functions. */
367
    //@{
368
369
    /**
370
     * Creates and returns an exact copy of this object.
371
     * See cObject for more details.
372
     */
373
    virtual cLongHistogram *dup() const  {return new cLongHistogram(*this);}
374
    //@}
375
376
  public:
377
    /** @name Redefined member functions from cStatistic and its subclasses. */
378
    //@{
379
380
    /**
381
     * Collects one value. Internally, the double value is converted to an
382
     * integer using floor() before any processing.
383
     */
384
    virtual void collect(double value) {cHistogram::collect(floor(value));}
385
386
    /**
387
     * Convenience method, delegates to collect(double).
388
     */
389
    virtual void collect(SimTime value) {collect(value.dbl());}
390
};
391
392
393
/**
394
 * Equidistant histogram for doubles. This class is just a cHistogram
395
 * preconfigured for collecting doubles (MODE_DOUBLES).
396
 *
397
 * @ingroup Statistics
398
 */
399
class SIM_API cDoubleHistogram : public cHistogram
400
{
401
  public:
402
    /** @name Constructors, destructor, assignment. */
403
    //@{
404
405
    /**
406
     * Copy constructor
407
     */
408
    cDoubleHistogram(const cDoubleHistogram& r) : cHistogram(r)
409
        {setName(r.getName());operator=(r);}
410
411
    /**
412
     * Constructor.
413
     */
414
    explicit cDoubleHistogram(const char *name=NULL, int numcells=-1) :
415
        cHistogram(name, numcells, MODE_DOUBLES) {}
416
417
    /**
418
     * Destructor.
419
     */
420
    virtual ~cDoubleHistogram() {}
421
422
    /**
423
     * Assignment operator.
424
     */
425
    cDoubleHistogram& operator=(const cDoubleHistogram& other)  {return (cDoubleHistogram&)cHistogram::operator=(other);}
426
    //@}
427
428
    /** @name Redefined cObject member functions. */
429
    //@{
430
431
    /**
432
     * Creates and returns an exact copy of this object.
433
     * See cObject for more details.
434
     */
435
    virtual cDoubleHistogram *dup() const  {return new cDoubleHistogram(*this);}
436
    //@}
437
};
438
439
NAMESPACE_END
440
441
442
#endif