#include <chistogram.h>
Description
Generic histogram class, capable of representing both unweighted and weighted distributions. Histogram data are stored as n+1 bin edges and n bin values, both being double-precision floating point values. Upper and lower outliers (as well as positive and negative infinities) are kept as counts (for unweighted statistics) or as sum of weights (for weighted statistics).
cHistogram is able to generate random numbers from the stored distribution, and also supports save/load of the histogram data in a file.
Bins can be set up directly using methods such as setBinEdges() or createUniformBins(), but it is often more practical to automate it by letting a histogram strategy do it. Histogram strategies are objects that encapsulate the job of setting up and managing histogram bins. For example, histogram strategies may employ a precollection phase to get an estimate of the distribution for laying out the bins. Strategies are also capable of extending the histogram range later by adding new bins as needed, or merging adjacent bins to reduce their count. Strategies that create non-uniform (e.g. equi-probable) bins are also possible to implement. Histogram strategies subclass from cIHistogramStrategy.
The default constructor of cHistogram installs a default histogram strategy which was designed to provide a good quality histogram for arbitrary distributions, without manual configuration. It employs precollection and also auto-extends the histogram at runtime, merging neighbouring groups of bins if there would be too many of them after extension.
Custom behavior can be achieved by setting up and installing an appropriate strategy class, such as cFixedRangeHistogramStrategy or cAutoRangeHistogramStrategy. There are also convenience methods such as setRange() and setNumBins() that internally use cAutoRangeHistogramStrategy.
Examples:
Automatic mode:
Setting up a 50-bin histogram on the range [0,100):
The same effect using convenience methods:
Public Types | |
| enum | Mode |
Public Member Functions | |
Constructors, destructor, assignment. | |
| cHistogram (const char *name=nullptr, bool weighted=false) | |
| cHistogram (const char *name, int numBinsHint, bool weighted=false) | |
| cHistogram (const char *name, cIHistogramStrategy *strategy, bool weighted=false) | |
| cHistogram (const cHistogram &other) | |
| cHistogram & | operator= (const cHistogram &other) |
| virtual | ~cHistogram () |
Redefined cObject member functions. | |
| virtual cHistogram * | dup () const override |
| virtual void | parsimPack (cCommBuffer *buffer) const override |
| virtual void | parsimUnpack (cCommBuffer *buffer) override |
Redefined member functions from cStatistic and its subclasses. | |
| virtual void | collect (double value) override |
| virtual void | collectWeighted (double value, double weight) override |
| virtual void | clear () override |
| virtual void | saveToFile (FILE *f) const override |
| virtual void | loadFromFile (FILE *f) override |
| virtual void | merge (const cStatistic *other) override |
Configuring and querying the histogram. | |
| void | setStrategy (cIHistogramStrategy *strategy) |
| cIHistogramStrategy * | getStrategy () const |
| virtual bool | binsAlreadySetUp () const override |
| virtual void | setUpBins () override |
| virtual void | setBinEdges (const std::vector< double > &edges) |
| virtual void | createUniformBins (double lo, double hi, double step) |
| virtual void | prependBins (const std::vector< double > &edges) |
| virtual void | appendBins (const std::vector< double > &edges) |
| virtual void | extendBinsTo (double value, double step, int maxNumBins=INT_MAX) |
| virtual void | mergeBins (int groupSize) |
| virtual std::vector< double > | getBinEdges () const override |
| virtual std::vector< double > | getBinValues () const override |
| virtual int | getNumBins () const override |
| virtual double | getBinEdge (int k) const override |
| virtual double | getBinValue (int k) const override |
| virtual double | getUnderflowSumWeights () const override |
| virtual double | getOverflowSumWeights () const override |
| virtual int64_t | getNumUnderflows () const override |
| virtual int64_t | getNumOverflows () const override |
| virtual int64_t | getNumNegInfs () const override |
| virtual int64_t | getNumPosInfs () const override |
| virtual double | getNegInfSumWeights () const override |
| virtual double | getPosInfSumWeights () const override |
cAutoRangeHistogramStrategy-based convenience API. | |
| virtual void | setMode (Mode mode) |
| virtual void | setRange (double lower, double upper) |
| virtual void | setNumPrecollectedValues (int numPrecollect) |
| virtual void | setRangeExtensionFactor (double rangeExtensionFactor) |
| virtual void | setAutoExtend (bool autoExtend) |
| virtual void | setNumBinsHint (int numCells) |
| virtual void | setBinSizeHint (double d) |
 Public Member Functions inherited from cAbstractHistogram | |
| cAbstractHistogram (const cAbstractHistogram &other)=default | |
| cAbstractHistogram (const char *name=nullptr, bool weighted=false) | |
| virtual | ~cAbstractHistogram () |
| cAbstractHistogram & | operator= (const cAbstractHistogram &res) |
| virtual double | getBinPDF (int k) const |
| virtual Bin | getBinInfo (int k) const |
| virtual double | getPDF (double x) const |
| virtual double | getCDF (double x) const |
| virtual double | draw () const override |
| Public Member Functions inherited from cStdDev | |
| cStdDev (const cStdDev &r) | |
| cStdDev (const char *name=nullptr, bool weighted=false) | |
| virtual | ~cStdDev () |
| cStdDev & | operator= (const cStdDev &res) |
| virtual std::string | str () const override |
| virtual bool | isWeighted () const override |
| virtual int64_t | getCount () const override |
| virtual double | getSum () const override |
| virtual double | getSqrSum () const override |
| virtual double | getMin () const override |
| virtual double | getMax () const override |
| virtual double | getMean () const override |
| virtual double | getStddev () const override |
| virtual double | getVariance () const override |
| virtual double | getSumWeights () const override |
| virtual double | getWeightedSum () const override |
| virtual double | getSqrSumWeights () const override |
| virtual double | getWeightedSqrSum () const override |
| virtual void | collect (double value)=0 |
| virtual void | collect (SimTime value) |
| virtual void | collectWeighted (double value, double weight) |
| virtual void | collectWeighted (SimTime value, double weight) |
| virtual void | collectWeighted (double value, SimTime weight) |
| virtual void | collectWeighted (SimTime value, SimTime weight) |
| Public Member Functions inherited from cStatistic | |
| cStatistic (const cStatistic &r) | |
| cStatistic (const char *name=nullptr) | |
| virtual | ~cStatistic () |
| cStatistic & | operator= (const cStatistic &res) |
| virtual void | collect (SimTime value) |
| virtual void | collectWeighted (SimTime value, double weight) |
| virtual void | collectWeighted (double value, SimTime weight) |
| virtual void | collectWeighted (SimTime value, SimTime weight) |
| virtual void | record () |
| virtual void | recordWithUnit (const char *unit) |
| virtual void | recordAs (const char *name, const char *unit=nullptr) |
| Public Member Functions inherited from cRandom | |
| cRandom (cRNG *rng) | |
| cRandom (const char *name=nullptr, cRNG *rng=nullptr) | |
| virtual | ~cRandom () |
| virtual void | setRNG (cRNG *rng) |
| cRNG * | getRNG () const |
| Public Member Functions inherited from cOwnedObject | |
| cOwnedObject () | |
| cOwnedObject (const char *name, bool namepooling=true) | |
| cOwnedObject (const cOwnedObject &obj) | |
| virtual | ~cOwnedObject () |
| cOwnedObject & | operator= (const cOwnedObject &o) |
| virtual cObject * | getOwner () const override |
| virtual bool | isOwnedObject () const override |
| Public Member Functions inherited from cNamedObject | |
| cNamedObject () | |
| cNamedObject (const char *name, bool namepooling=true) | |
| cNamedObject (const cNamedObject &obj) | |
| virtual | ~cNamedObject () |
| cNamedObject & | operator= (const cNamedObject &o) |
| virtual void | setName (const char *s) |
| virtual const char * | getName () const override |
| virtual void | setNamePooling (bool b) |
| virtual bool | getNamePooling () |
| Public Member Functions inherited from cObject | |
| cObject () | |
| cObject (const cObject &other)=default | |
| virtual | ~cObject () |
| virtual const char * | getClassName () const |
| bool | isName (const char *s) const |
| virtual const char * | getFullName () const |
| virtual std::string | getFullPath () const |
| virtual std::string | getClassAndFullName () const |
| virtual std::string | getClassAndFullPath () const |
| const cObject * | getThisPtr () const |
| virtual std::ostream & | printOn (std::ostream &os) const |
| virtual bool | isSoftOwner () const |
| virtual void | forEachChild (cVisitor *v) |
| cObject * | findObject (const char *name, bool deep=true) |
| virtual cClassDescriptor * | getDescriptor () const |
| void | copyNotSupported () const |
Additional Inherited Members | |
| Static Public Member Functions inherited from cOwnedObject | |
| static long | getTotalObjectCount () |
| static long | getLiveObjectCount () |
| static void | resetObjectCounters () |
| static cSoftOwner * | getOwningContext () |
| Protected Member Functions inherited from cObject | |
| virtual void | take (cOwnedObject *obj) |
| virtual void | drop (cOwnedObject *obj) |
| void | dropAndDelete (cOwnedObject *obj) |
Member Enumeration Documentation
◆ Mode
| enum Mode |
Histogram mode. In INTEGERS mode, bin edges are whole numbers; in REALS mode they can be real numbers.
Constructor & Destructor Documentation
◆ cHistogram() [1/4]
|
explicit |
This constructor installs a cDefaultHistogramStrategy on the histogram. To create a histogram without a strategy object, use the constructor that takes a 'strategy' parameter and pass nullptr for it.
◆ cHistogram() [2/4]
|
explicit |
This convenience constructor installs a cDefaultHistogramStrategy with the desired number of bins on the histogram.
◆ cHistogram() [3/4]
|
explicit |
Constructor that allows one to install a histogram strategy on the histogram. It is also legal to pass nullptr as strategy.
◆ cHistogram() [4/4]
|
inline |
Copy constructor.
◆ ~cHistogram()
|
virtual |
Destructor.
Member Function Documentation
◆ operator=()
| cHistogram& operator= | ( | const cHistogram & | other | ) |
Assignment operator. The name member is not copied; see cNamedObject::operator=() for details.
◆ dup()
|
inlineoverridevirtual |
Creates and returns an exact copy of this object. See cObject for more details.
Reimplemented from cAbstractHistogram.
◆ parsimPack()
|
overridevirtual |
◆ parsimUnpack()
|
overridevirtual |
◆ collect()
|
overridevirtual |
Collects one observation. Delegates to the strategy object if there is one installed.
Reimplemented from cStdDev.
◆ collectWeighted()
|
overridevirtual |
Collects one observation with a given weight. The weight must not be negative. (Zero-weight observations are allowed, but will not affect mean and stddev, nor the bin values.) This methods delegates to the strategy object if there is one installed.
Reimplemented from cStdDev.
◆ clear()
|
overridevirtual |
Clears the results collected so far.
Reimplemented from cStdDev.
◆ saveToFile()
|
overridevirtual |
Writes the contents of the object into a text file.
Reimplemented from cStdDev.
◆ loadFromFile()
|
overridevirtual |
Reads the object data from a file, in the format written out by saveToFile().
Reimplemented from cStdDev.
◆ merge()
|
overridevirtual |
Merge another statistics object into this one.
Reimplemented from cStdDev.
◆ setStrategy()
| void setStrategy | ( | cIHistogramStrategy * | strategy | ) |
Installs a new histogram strategy, replacing the current one, taking ownership of 'setupStrategy'. Can only be called while the histogram is empty.
◆ getStrategy()
|
inline |
Returns a pointer to the currently used histogram strategy.
◆ binsAlreadySetUp()
|
overridevirtual |
Returns true if histogram bins are already available. (Bins are not yet available in the precollection phase.) See setUpBins().
Implements cAbstractHistogram.
◆ setUpBins()
|
overridevirtual |
Sets up histogram bins using the installed strategy (see cIHistogramStrategy). The histogram strategy class may use precollection to gather information for laying out the bins.
Implements cAbstractHistogram.
◆ setBinEdges()
|
virtual |
Configures a histogram with bins defined by 'edges'. Can only be called once, and only when there are no bins defined. 'edges' must contain at least two values, and it must be strictly increasing.
◆ createUniformBins()
|
virtual |
Sets the histogram up to have bins covering the range from 'lo' to 'hi', each bin being 'step' wide. Can only be called on a histogram without bins. 'lo' will always be added as an edge, all bins will be 'step' wide, and the last bin edge will be at or above 'hi'.
◆ prependBins()
|
virtual |
Extends the histogram to the left with some bins, as delimited by 'edges'. This can only be used if there is at least one bin already, and there are no underflows. 'edges' must not be empty, it must be strictly increasing, and its last value must be less than the first already existing bin edge.
◆ appendBins()
|
virtual |
Extends the histogram to the right with some bins, as delimited by 'edges'. This can only be used if there is at least one bin already, and there are no overflows. 'edges' must not be empty, it must be strictly increasing, and its first value must be greater than the last already existing bin edge.
◆ extendBinsTo()
|
virtual |
Makes sure that 'value' will fall in the range covered by the bins, by potentially extending the histogram with some bins of width 'step'. Creation of new bins stops when either the total number of bins reaches 'maxNumBins', or 'value' is covered by the histogram. If 'value' is already in the range of the existing bins, the function does nothing. This method may only be called when there are no over- or underflows. 'step' must be positive.
◆ mergeBins()
|
virtual |
Reduces the number of bins by merging each 'groupSize' consecutive bins into one. The number of bins must be a multiple of 'groupSize'. If that is not the case, extendBinsTo() or similar methods may be used to create extra empty bins before calling this function.
◆ getBinEdges()
|
inlineoverridevirtual |
Returns the bin edges of the histogram. There is always one more edge than bin, except when the histogram has not been set up yet, in which case both are zero.
Reimplemented from cAbstractHistogram.
◆ getBinValues()
|
inlineoverridevirtual |
Returns the bin values of the histogram. There is always one less bin than edge, except when the histogram has not been set up yet, in which case both are zero.
Reimplemented from cAbstractHistogram.
◆ getNumBins()
|
inlineoverridevirtual |
Returns the number of bins in the histogram.
Implements cAbstractHistogram.
◆ getBinEdge()
|
inlineoverridevirtual |
Returns the k'th bin edge of the histogram. The k'th bin is delimited by the edge k and k+1.
Implements cAbstractHistogram.
◆ getBinValue()
|
inlineoverridevirtual |
Returns the total weight of the observations in the k'th bin of the histogram. (In the unweighted case, every observation is regarded as having the weight 1.0.)
Implements cAbstractHistogram.
◆ getUnderflowSumWeights()
|
inlineoverridevirtual |
Returns the total weight of the observations that were under the histogram range.
Implements cAbstractHistogram.
◆ getOverflowSumWeights()
|
inlineoverridevirtual |
Returns the total weight of the observations that were above the histogram range.
Implements cAbstractHistogram.
◆ getNumUnderflows()
|
overridevirtual |
Returns the number of observations that were under the histogram range. This value is only collected for unweighted statistics, i.e. it is an error to call this method on a weighted histogram.
Implements cAbstractHistogram.
◆ getNumOverflows()
|
overridevirtual |
Returns the number of observations that were under the histogram range. This value is only collected for unweighted statistics, i.e. it is an error to call this method on a weighted histogram.
Implements cAbstractHistogram.
◆ getNumNegInfs()
|
overridevirtual |
Returns number of observations that were negative infinity, independent of their weights. This value is only collected for unweighted statistics, i.e. it is an error to call this method on a weighted histogram.
Implements cAbstractHistogram.
◆ getNumPosInfs()
|
overridevirtual |
Returns number of observations that were positive infinity, independent of their weights. This value is only collected for unweighted statistics, i.e. it is an error to call this method on a weighted histogram.
Implements cAbstractHistogram.
◆ getNegInfSumWeights()
|
inlineoverridevirtual |
Returns the total weight of the observations that were negative infinity.
Implements cAbstractHistogram.
◆ getPosInfSumWeights()
|
inlineoverridevirtual |
Returns the total weight of the observations that were above the histogram range.
Implements cAbstractHistogram.
◆ setMode()
|
virtual |
Sets the histogram mode: MODE_AUTO, MODE_INTEGERS or MODE_DOUBLES. Cannot be called when the bins have been set up already. This method internally installs (or uses an already installed) cAutoRangeHistogramStrategy on the histogram, and configures it accordingly.
◆ setRange()
|
virtual |
Sets the histogram range explicitly to [lower, upper). Use NAN to leave either or both values unspecified. This method internally installs (or uses an already installed) cAutoRangeHistogramStrategy on the histogram, and configures it accordingly.
◆ setNumPrecollectedValues()
|
virtual |
Sets the number of observations to collect before setting up histogram bins. This method internally installs (or uses an already installed) cAutoRangeHistogramStrategy on the histogram, and configures it accordingly.
◆ setRangeExtensionFactor()
|
virtual |
Sets the factor by which the range of the precollected observations is multiplied for determining the range of the histogram bins. This method internally installs (or uses an already installed) cAutoRangeHistogramStrategy on the histogram, and configures it accordingly.
◆ setAutoExtend()
|
virtual |
When set to true, observations that fall outside of the histogram range will cause the histogram to be extended with new bins, instead of being collected as outliers. This method internally installs (or uses an already installed) cAutoRangeHistogramStrategy on the histogram, and configures it accordingly.
◆ setNumBinsHint()
|
virtual |
Sets the preferred number of bins. Cannot be called when the bins have been set up already. This method internally installs (or uses an already installed) cAutoRangeHistogramStrategy on the histogram, and configures it accordingly.
◆ setBinSizeHint()
|
virtual |
Sets the preferred bin size. Cannot be called when the bins have been set up already. This method internally installs (or uses an already installed) cAutoRangeHistogramStrategy on the histogram, and configures it accordingly.
The documentation for this class was generated from the following file:
