Project

General

Profile

Statistics
| Branch: | Revision:

root / include / cdensityestbase.h @ b781545c

History | View | Annotate | Download (13.2 KB)

1
//==========================================================================
2
//  CDENSITYESTBASE.H - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//
7
//  Declaration of the following classes:
8
//    cDensityEstBase : common base class for density estimation classes
9
//
10
//==========================================================================
11

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

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

    
20
#ifndef __CDENSITYESTBASE_H
21
#define __CDENSITYESTBASE_H
22

    
23
#include "cstddev.h"
24

    
25
NAMESPACE_BEGIN
26

    
27
/**
28
 * Common base class for density estimation classes. Provides several
29
 * pure virtual functions, so it is an abstract class, no instances
30
 * can be created.
31
 *
32
 * For the histogram classes, you need to specify the number of cells
33
 * and the range. Range can either be set explicitly or you can choose
34
 * automatic range determination.
35
 *
36
 * Automatic range estimation works in the following way:
37
 * <OL>
38
 *   <LI>The first <I>num_firstvals</I> observations are stored.
39
 *   <LI>After having collected a given number of observations, the actual
40
 *   histogram is set up. The range (<I>min</I>, <I>max</I>) of the
41
 *   initial values is expanded <I>range_ext_factor</I> times, and
42
 *   the result will become the histogram's range (<I>rangemin</I>,
43
 *   <I>rangemax</I>). Based on the range, the cells are layed out.
44
 *   Then the initial values that have been stored up to this point
45
 *   will be transferred into the new histogram structure and their
46
 *   store is deleted -- this is done by the transform() function.
47
 * </OL>
48
 *
49
 * You may also explicitly specify the lower or upper limit and have
50
 * the other end of the range estimated automatically. The setRange...()
51
 * member functions of cDensityEstBase deal with setting
52
 * up the histogram range. It also provides pure virtual functions
53
 * transform() etc.
54
 *
55
 * Subsequent observations are placed in the histogram structure.
56
 * If an observation falls out of the histogram range, the <I>underflow</I>
57
 * or the <I>overflow</I> <I>cell</I> is incremented.
58
 *
59
 * layout of the histogram:
60
 * <PRE><TT>
61
 *        underflow-cell   ordinary cells          overflow-cell
62
 *       ...----------|----|----|----|----|----|----|--------- ...
63
 *                    |                             |
64
 *                    |                             |
65
 *                rangemin                       rangemax
66
 * </TT></PRE>
67
 *
68
 * @ingroup Statistics
69
 */
70
class SIM_API cDensityEstBase : public cStdDev
71
{
72
  public:
73
    /**
74
     * Constants for histogram range_mode
75
     */
76
    enum {
77
        RANGE_AUTO,      // automatic range setup, using precollected values and range extension (the default)
78
        RANGE_AUTOLOWER, // like RANGE_AUTO, but upper limit is fixed
79
        RANGE_AUTOUPPER, // like RANGE_AUTO, but lower limit is fixed
80
        RANGE_FIXED,     // fixed range (lower, upper)
81
        RANGE_NOTSET     // not set, but it is OK (cVarHistogram only)
82
    };
83

    
84
    /**
85
     * Information about a cell. This struct is not used internally by
86
     * histogram and histogram-like classes, only to return information
87
     * to the user.
88
     */
89
    struct Cell
90
    {
91
        double lower;  // lower cell bound (inclusive)
92
        double upper;  // lower cell bound (exclusive)
93
        double value;  // counter (or its estimate)
94
        double relativeFreq;  // value / total
95
        Cell() {lower=upper=value=relativeFreq=0;}
96
    };
97

    
98
  protected:
99
    double rangemin, rangemax;   // range for distribution density collection
100
    int num_firstvals;         // number of "pre-collected" observations
101
                                // before transform() is performed.
102
    unsigned long cell_under;
103
    unsigned long cell_over;    // for counting observations that fall out of range
104

    
105
    double range_ext_factor;    // the range of histogram is: [min_vals, max_vals] made
106
                                // range_ext_factor times larger
107
    int range_mode;             // one of RANGE_xxx constants
108

    
109
    bool transfd;
110
    double *firstvals;         // pointer to array of "pre-collected" observations
111

    
112
  protected:
113
    static void plotline (std::ostream& os, const char *pref, double xval, double count, double a);
114

    
115
    // part of merge(); to be implemented in subclasses
116
    virtual void doMergeCellValues(const cDensityEstBase *other) = 0;
117
  public:
118
    // internal, for use in sim_std.msg; note: each call overwrites the previous value!
119
    const Cell& internalGetCellInfo(int k) const;
120

    
121
  public:
122
    /** @name Constructors, destructor, assignment. */
123
    //@{
124

    
125
    /**
126
     * Copy constructor.
127
     */
128
    cDensityEstBase(const cDensityEstBase& r) : cStdDev()
129
            {setName(r.getName());firstvals=NULL;operator=(r);}
130

    
131
    /**
132
     * Constructor.
133
     */
134
    explicit cDensityEstBase(const char *name=NULL);
135

    
136
    /**
137
     * Destructor.
138
     */
139
    virtual ~cDensityEstBase();
140

    
141
    /**
142
     * Assignment operator. The name member is not copied; see cNamedObject's operator=() for more details.
143
     */
144
    cDensityEstBase& operator=(const cDensityEstBase& res);
145
    //@}
146

    
147
    /** @name Redefined cObject member functions. */
148
    //@{
149

    
150
    /* No dup() because this is an abstract class. */
151

    
152
    /**
153
     * Produces a multi-line description of the object's contents.
154
     */
155
    virtual std::string detailedInfo() const;
156

    
157
    /**
158
     * Serializes the object into an MPI send buffer.
159
     * Used by the simulation kernel for parallel execution.
160
     * See cObject for more details.
161
     */
162
    virtual void parsimPack(cCommBuffer *buffer);
163

    
164
    /**
165
     * Deserializes the object from an MPI receive buffer
166
     * Used by the simulation kernel for parallel execution.
167
     * See cObject for more details.
168
     */
169
    virtual void parsimUnpack(cCommBuffer *buffer);
170
    //@}
171

    
172
    /** @name Redefined cStatistic member functions. */
173
    //@{
174

    
175
    /**
176
     * Collects one value. Before the histogram was transformed, this method
177
     * simply adds the value to the table of pre-collected values.
178
     * When the number of pre-collected observations reaches a limit, the transform()
179
     * method is called. After transformation, it calls collectTransformed()
180
     * to update the stored statistics with this value.
181
     */
182
    virtual void collect(double value);
183

    
184
    /**
185
     * Convenience method, delegates to collect(double).
186
     */
187
    virtual void collect(SimTime value) {collect(value.dbl());}
188

    
189
    /**
190
     * Updates this object with data coming from another statistics
191
     * object -- as if this object had collected observations fed
192
     * into the other object as well. Throws an error if the other
193
     * object is not a cDensityEstBase.
194
     */
195
    virtual void merge(const cStatistic *other);
196

    
197
    /**
198
     * Clears the results collected so far.
199
     */
200
    virtual void clearResult();
201

    
202
    /**
203
     * Writes the contents of the object into a text file.
204
     */
205
    virtual void saveToFile(FILE *) const;
206

    
207
    /**
208
     * Reads the object data from a file, in the format written out by saveToFile().
209
     */
210
    virtual void loadFromFile(FILE *);
211
    //@}
212

    
213
    /** @name Selecting the method of setting up the histogram range. */
214
    //@{
215

    
216
    /**
217
     * Sets the histogram range explicitly to [lower, upper]. When this method is
218
     * used, setNumFirstVals() is not needed.
219
     */
220
    virtual void setRange(double lower, double upper);
221

    
222
    /**
223
     * Selects a histogram range setup method where the range will be determined
224
     * entirely from a set of pre-collected values.
225
     *
226
     * When called, the histogram range will be determined from the first
227
     * num_firstvals values, extending their range symmetrically by
228
     * range_ext_fact. For example, after a call to setRangeAuto(100, 1.3),
229
     * the histogram will be set up after pre-collecting 100 values, the range
230
     * being the range of the 100 pre-collected values extended 1.3 times
231
     * symmetrically.
232
     */
233
    virtual void setRangeAuto(int num_firstvals=100, double range_ext_fact=2.0);
234

    
235
    /**
236
     * Selects a histogram range setup method where the upper bound of the range
237
     * is fixed and the lower bound is determined from a set of pre-collected values.
238
     *
239
     * The lower bound is calculated by extending the range (minimum of observations, upper)
240
     * range_ext_fact times.
241
     */
242
    virtual void setRangeAutoLower(double upper, int num_firstvals=100, double range_ext_fact=2.0);
243

    
244
    /**
245
     * Selects a histogram range setup method where the lower bound of the range
246
     * is fixed and the upper bound is determined from a set of pre-collected values.
247
     *
248
     * The upper bound is calculated by extending the range (lower, maximum of observations)
249
     * range_ext_fact times.
250
     */
251
    virtual void setRangeAutoUpper(double lower, int num_firstvals=100, double range_ext_fact=2.0);
252

    
253
    /**
254
     * Sets the number of values to be pre-collected before transformation takes
255
     * place. See transform().
256
     */
257
    virtual void setNumFirstVals(int num_firstvals);
258

    
259
    /**
260
     * Returns the number of values to be pre-collected before transformation
261
     * takes place. See transform().
262
     */
263
    virtual int getNumFirstVals() const {return num_firstvals;}
264

    
265
    /**
266
     * Returns the range extension factor, used with histogram range setup.
267
     * See setRangeAuto() and transform().
268
     */
269
    virtual double getRangeExtensionFactor() const {return range_ext_factor;}
270
    //@}
271

    
272
  protected:
273
    /**
274
     * Called internally by transform(), this method should determine and set up
275
     * the histogram range, based on the pre-collected data and the range setup
276
     * method selected by calls to the setRange(), setRangeAuto(), setRangeAutoLower(),
277
     * setRangeAutoUpper() methods.
278
     */
279
    virtual void setupRange();
280

    
281
    /**
282
     * Called internally by collect(), this method collects a value
283
     * after the histogram has been transformed.
284
     * Updating the underflow/overflow cells must be handled within this function.
285
     * This is a pure virtual function; it must be redefined in subclasses.
286
     */
287
    virtual void collectTransformed(double value) = 0;
288

    
289
  public:
290

    
291
    /** @name Transformation. */
292
    //@{
293

    
294
    /**
295
     * Returns whether the object is transformed. See transform().
296
     */
297
    virtual bool isTransformed() const   {return transfd;}
298

    
299
    /**
300
     * Transforms the table of pre-collected values into an internal
301
     * histogram structure. This is a pure virtual function. Implementations
302
     * of transform() are expected to call setupRange(), and set the
303
     * transfd flag when transformation was successfully done.
304
     */
305
    virtual void transform() = 0;
306
    //@}
307

    
308
    /** @name Accessing histogram cells. */
309
    //@{
310

    
311
    /**
312
     * Returns the number of histogram cells used.
313
     * This method is pure virtual, implementation is provided in subclasses.
314
     */
315
    virtual int getNumCells() const = 0;
316

    
317
    /**
318
     * Returns the kth cell boundary. Legal values for k are 0 through getNumCells(),
319
     * that is, there' one more basepoint than the number of cells.
320
     * Basepoint(0) returns the low end of the first cell, and getBasepoint(getNumCells())
321
     * returns the high end of the last histogram cell.
322
     * This method is pure virtual, implementation is provided in subclasses.
323
     */
324
    virtual double getBasepoint(int k) const = 0;
325

    
326
    /**
327
     * Returns the number of observations that fell into the kth histogram cell.
328
     * Before transformation, this method may return zero. See transform().
329
     * This method is pure virtual, implementation is provided in subclasses.
330
     */
331
    virtual double getCellValue(int k) const = 0;
332

    
333
    /**
334
     * Returns the estimated value of the Probability Density Function
335
     * within the kth cell. This method simply divides the number of observations
336
     * in cell k with the cell size and the number of total observations collected.
337
     * Note that before transformation, getCellValue() and also this method may return zero.
338
     * See transform().
339
     */
340
    virtual double getCellPDF(int k) const;
341

    
342
    /**
343
     * Returns number of observations that, being too small, fell out of the histogram
344
     * range.
345
     */
346
    virtual unsigned long getUnderflowCell() const {return cell_under;}
347

    
348
    /**
349
     * Returns number of observations that, being too large, fell out of the histogram
350
     * range.
351
     */
352
    virtual unsigned long getOverflowCell() const {return cell_over;}
353

    
354
    /**
355
     * Combines the functionality of getBasepoint(), getCellValue() and getCellPDF() into a
356
     * single call.
357
     */
358
    virtual Cell getCellInfo(int k) const;
359
    //@}
360

    
361
    /** @name Density and cumulated density approximation functions. */
362
    //@{
363

    
364
    /**
365
     * Returns the estimated value of the Probability Density Function at a given x.
366
     * This is a pure virtual function, implementation is provided
367
     * in subclasses implementing concrete histogram types.
368
     */
369
    virtual double getPDF(double x) const = 0;
370

    
371
    /**
372
     * Returns the estimated value of the Cumulated Density Function at a given x.
373
     * This is a pure virtual function, implementation is provided
374
     * in subclasses implementing concrete histogram types.
375
     */
376
    virtual double getCDF(double x) const = 0;
377
    //@}
378
};
379

    
380
NAMESPACE_END
381

    
382

    
383
#endif
384

    
385

    
386