Statistics
| Branch: | Revision:

root / include / cvarhist.h @ 47c4b975

History | View | Annotate | Download (6.71 KB)

1 01873262 Georg Kunz
//==========================================================================
2
//  CVARHIST.H - part of
3
//
4
//                     OMNeT++/OMNEST
5
//            Discrete System Simulation in C++
6
//
7
//
8
//  Declaration of the following classes:
9
//    cVarHistogram : Variable bin size histogram
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 __CVARHIST_H
22
#define __CVARHIST_H
23
24
#include "chistogram.h"
25
26
NAMESPACE_BEGIN
27
28
29
/**
30
 * Transform types for cVarHistogram
31
 */
32
enum {
33
   HIST_TR_NO_TRANSFORM=1, ///< no transformation; uses bin boundaries previously defined by addBinBound()/appendBinBound()
34
   HIST_TR_AUTO_EPC_DBL=0, ///< automatically creates equi-probable cells
35
   HIST_TR_AUTO_EPC_INT=2  ///< a variation of HIST_TR_AUTO_EPC_DBL
36
};
37
38
/**
39
 * Variable bin size histogram. You may add cell (bin) boundaries
40
 * manually, or let the object create cells with equal number of
41
 * observations in them (or as close to that as possible).
42
 *
43
 * Transform types for cVarHistogram:
44
 * <UL>
45
 *   <LI> HIST_TR_NO_TRANSFORM: no transformation; uses bin boundaries
46
 *        previously defined by addBinBound()/appendBinBound()
47
 *   <LI> HIST_TR_AUTO_EPC_DBL: automatically creates equiprobable cells
48
 *   <LI> HIST_TR_AUTO_EPC_INT: a variation of HIST_TR_AUTO_EPC_DBL
49
 * </Ul>
50
 *
51
 * Layout of the variable bin width histogram:
52
 * <PRE><TT>
53
 *
54
 *        underflow-cell   ordinary cells . . .             overflow-cell
55
 *        ...---------|-----------|- ... -|-----------------|---------...
56
 *                    | ^cellv[0] |      cellv[num_cells-1]^|
57
 *                  n |           |                         |
58
 *                rangemin        |                      rangemax
59
 *                    |    bin_bounds[1]                    |
60
 *              bin_bounds[0]                       bin_bounds[numcells]
61
 * </TT></PRE>
62
 *
63
 * Rangemin and rangemax is chosen after collecting the num_firstvals initial
64
 * observations. It is not possible to add cell boundaries when histogram is
65
 * already transformed.
66
 *
67
 * Now we do support the following 2 uses of cVarHistogram:
68
 * <OL>
69
 *   <LI> add all the boundaries (manually) before collecting observations
70
 *   <LI> collect observations and transform() makes the boundaries
71
 * </OL>
72
 *
73
 * @ingroup Statistics
74
 */
75
class SIM_API cVarHistogram : public cHistogramBase
76
{
77
  protected:
78
    int transform_type;     // one of the HIST_TR_xxx constants
79
    int max_num_cells;      // the length of the allocated cellv
80
    double *bin_bounds;     // bin/cell boundaries
81
82
    // the boundaries of the ordinary cells/bins are:
83
    // rangemin=bin_bounds[0], bin_bounds[1], ... bin_bounds[num_cells]=rangemax
84
    // consequence: sizeof(binbounds)=sizeof(cellv)+1
85
86
  protected:
87
    /**
88
     * Used internally to create equiprobable cells from the precollected
89
     * observations. This cannot be mixed with manually adding cell boundaries
90
     * -- if there are already some, an error is raised.
91
     */
92
    void createEquiprobableCells();
93
94
  public:
95
    /** @name Constructors, destructor, assignment. */
96
    //@{
97
98
    /**
99
     * Copy constructor.
100
     */
101
    cVarHistogram(const cVarHistogram& r) : cHistogramBase(r)
102
       {setName(r.getName());bin_bounds=NULL;operator=(r);}
103
104
    /**
105
     * Constructor. The third argument can be one of HIST_TR_NO_TRANSFORM,
106
     * HIST_TR_AUTO_EPC_DBL, HIST_TR_AUTO_EPC_INT. With HIST_TR_NO_TRANSFORM,
107
     * you can set up cells manually (see addBinBound()), in the other two
108
     * cases it tries to create equiprobably cells.
109
     */
110
    explicit cVarHistogram(const char *name=NULL,
111
                           int numcells=11,
112
                           int transformtype=HIST_TR_AUTO_EPC_DBL);
113
114
    /**
115
     * Destructor.
116
     */
117
    virtual ~cVarHistogram();
118
119
    /**
120
     * Assignment operator. The name member is not copied; see cNamedObject's operator=() for more details.
121
     */
122
    cVarHistogram& operator=(const cVarHistogram& res);
123
    //@}
124
125
    /** @name Redefined cObject member functions. */
126
    //@{
127
128
    /**
129
     * Creates and returns an exact copy of this object.
130
     * See cObject for more details.
131
     */
132
    virtual cVarHistogram *dup() const  {return new cVarHistogram(*this);}
133
134
    /**
135
     * Serializes the object into an MPI send buffer.
136
     * Used by the simulation kernel for parallel execution.
137
     * See cObject for more details.
138
     */
139
    virtual void parsimPack(cCommBuffer *buffer);
140
141
    /**
142
     * Deserializes the object from an MPI receive buffer
143
     * Used by the simulation kernel for parallel execution.
144
     * See cObject for more details.
145
     */
146
    virtual void parsimUnpack(cCommBuffer *buffer);
147
    //@}
148
149
    /** @name Redefined member functions from cStatistic and its subclasses. */
150
    //@{
151
152
    /**
153
     * Clears the results collected so far.
154
     */
155
    virtual void clearResult();
156
157
    /**
158
     * Transforms the table of precollected values into an internal
159
     * histogram structure.
160
     */
161
    virtual void transform();
162
163
    /**
164
     * Called internally by collect(), this method collects a value
165
     * after the histogram has been transformed.
166
     */
167
    virtual void collectTransformed(double val);
168
169
    /**
170
     * Generates a random number based on the collected data. Uses the random number generator set by setGenK().
171
     */
172
    virtual double random() const;
173
174
    /**
175
     * Returns the value of the Probability Density Function at a given x.
176
     */
177
    virtual double getPDF(double x) const;
178
179
    /**
180
     * Returns the value of the Cumulated Density Function at a given x.
181
     */
182
    virtual double getCDF(double x) const;
183
184
    /**
185
     * Returns the kth cell boundary.
186
     */
187
    virtual double getBasepoint(int k) const;
188
189
    /**
190
     * Returns the number of observations that fell into the kth histogram cell.
191
     */
192
    virtual double getCellValue(int k) const;
193
194
    /**
195
     * Writes the contents of the object into a text file.
196
     */
197
    virtual void saveToFile(FILE *) const;
198
199
    /**
200
     * Reads the object data from a file, in the format written out by saveToFile().
201
     */
202
    virtual void loadFromFile(FILE *);
203
    //@}
204
205
    /** @name Setting up the histogram. */
206
    //@{
207
208
    /**
209
     * Adds a new bin (cell) boundary. This method can only be called
210
     * if HIST_TR_NO_TRANSFORM was specified in the constructor call,
211
     * and only when the object is still in the initial data collection phase
212
     * (that is, transform() has been invoked yet).
213
     */
214
    virtual void addBinBound(double x);
215
    //@}
216
};
217
218
NAMESPACE_END
219
220
221
#endif
222