OMNeT++ Simulation Library  5.6.1
cHistogram Class Reference

#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:

cHistogram histogram("histogram");

Setting up a 50-bin histogram on the range [0,100):

cAutoRangeHistogramStrategy *strategy = new cAutoRangeHistogramStrategy();
strategy->setRange(0, 100);
strategy->setNumBins(50);
strategy->setMode(cHistogram::MODE_INTEGERS);
cHistogram histogram("histogram", strategy);

The same effect using convenience methods:

cHistogram histogram("histogram");
histogram.setRange(0, 100);
histogram.setNumBins(50);
histogram.setMode(cHistogram::MODE_INTEGERS);
Inheritance diagram for cHistogram:
cAbstractHistogram cStdDev cStatistic cRandom cOwnedObject cNamedObject cObject

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)
 
cHistogramoperator= (const cHistogram &other)
 
virtual ~cHistogram ()
 
Redefined cObject member functions.
virtual cHistogramdup () 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)
 
cIHistogramStrategygetStrategy () 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)
 
const std::vector< double > & getBinEdges () const
 
const std::vector< double > & getBinValues () const
 
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)
 
virtual _OPPDEPRECATED void setRangeAuto (int numPrecollect=100, double rangeExtensionFactor=2.0)
 
virtual _OPPDEPRECATED void setRangeAutoLower (double upper, int numPrecollect=100, double rangeExtensionFactor=2.0)
 
virtual _OPPDEPRECATED void setRangeAutoUpper (double lower, int numPrecollect=100, double rangeExtensionFactor=2.0)
 
virtual _OPPDEPRECATED void setNumCells (int numCells) final
 
virtual _OPPDEPRECATED void setCellSize (double d) final
 
- Public Member Functions inherited from cAbstractHistogram
 cAbstractHistogram (const cAbstractHistogram &other)
 
 cAbstractHistogram (const char *name=nullptr, bool weighted=false)
 
virtual ~cAbstractHistogram ()
 
cAbstractHistogramoperator= (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
 
virtual _OPPDEPRECATED bool isTransformed () const final
 
virtual _OPPDEPRECATED void transform () final
 
virtual _OPPDEPRECATED int getNumCells () const final
 
virtual _OPPDEPRECATED double getBasepoint (int k) const final
 
virtual _OPPDEPRECATED double getCellValue (int k) const final
 
virtual _OPPDEPRECATED double getCellPDF (int k) const final
 
virtual _OPPDEPRECATED int64_t getUnderflowCell () const final
 
virtual _OPPDEPRECATED int64_t getOverflowCell () const final
 
virtual _OPPDEPRECATED Bin getCellInfo (int k) const final
 
- Public Member Functions inherited from cStdDev
 cStdDev (const cStdDev &r)
 
 cStdDev (const char *name=nullptr, bool weighted=false)
 
virtual ~cStdDev ()
 
cStdDevoperator= (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
 
- Public Member Functions inherited from cStatistic
 cStatistic (const cStatistic &r)
 
 cStatistic (const char *name=nullptr)
 
virtual ~cStatistic ()
 
cStatisticoperator= (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)
 
virtual _OPPDEPRECATED double getWeights () const final
 
virtual _OPPDEPRECATED void collect2 (double value, double weight) final
 
virtual _OPPDEPRECATED void collect2 (SimTime value, double weight) final
 
virtual _OPPDEPRECATED void collect2 (double value, SimTime weight) final
 
virtual _OPPDEPRECATED void collect2 (SimTime value, SimTime weight) final
 
virtual _OPPDEPRECATED double random () const final
 
virtual _OPPDEPRECATED void clearResult () final
 
- Public Member Functions inherited from cRandom
 cRandom (cRNG *rng)
 
 cRandom (const char *name=nullptr, cRNG *rng=nullptr)
 
virtual ~cRandom ()
 
virtual void setRNG (cRNG *rng)
 
cRNGgetRNG () const
 
- Public Member Functions inherited from cOwnedObject
 cOwnedObject ()
 
 cOwnedObject (const char *name, bool namepooling=true)
 
 cOwnedObject (const cOwnedObject &obj)
 
virtual ~cOwnedObject ()
 
cOwnedObjectoperator= (const cOwnedObject &o)
 
virtual cObjectgetOwner () const override
 
virtual bool isOwnedObject () const override
 
virtual bool isSoftOwner () const
 
- Public Member Functions inherited from cNamedObject
 cNamedObject ()
 
 cNamedObject (const char *name, bool namepooling=true)
 
 cNamedObject (const cNamedObject &obj)
 
virtual ~cNamedObject ()
 
cNamedObjectoperator= (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)
 
virtual ~cObject ()
 
virtual const char * getClassName () const
 
bool isName (const char *s) const
 
virtual const char * getFullName () const
 
virtual std::string getFullPath () const
 
const cObjectgetThisPtr () const
 
virtual _OPPDEPRECATED std::string info () const
 
virtual _OPPDEPRECATED std::string detailedInfo () const
 
virtual void forEachChild (cVisitor *v)
 
cObjectfindObject (const char *name, bool deep=true)
 
void copyNotSupported () const
 

Additional Inherited Members

- Static Public Member Functions inherited from cOwnedObject
static long getTotalObjectCount ()
 
static long getLiveObjectCount ()
 
static void resetObjectCounters ()
 
static cDefaultListgetDefaultOwner ()
 
- 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]

cHistogram ( const char *  name = nullptr,
bool  weighted = false 
)
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]

cHistogram ( const char *  name,
int  numBinsHint,
bool  weighted = false 
)
explicit

This convenience constructor installs a cDefaultHistogramStrategy with the desired number of bins on the histogram.

◆ cHistogram() [3/4]

cHistogram ( const char *  name,
cIHistogramStrategy strategy,
bool  weighted = false 
)
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]

cHistogram ( const cHistogram other)
inline

Copy constructor.

◆ ~cHistogram()

virtual ~cHistogram ( )
virtual

Destructor.

Member Function Documentation

◆ operator=()

cHistogram& operator= ( const cHistogram other)

Assignment operator. The name member is not copied; see cNamedObject's operator=() for more details.

◆ dup()

virtual cHistogram* dup ( ) const
inlineoverridevirtual

Creates and returns an exact copy of this object. See cObject for more details.

Reimplemented from cAbstractHistogram.

References cStdDev::collect(), and cStdDev::collectWeighted().

◆ parsimPack()

virtual void parsimPack ( cCommBuffer buffer) const
overridevirtual

Serializes the object into an MPI send buffer. Used by the simulation kernel for parallel execution. See cObject for more details.

Reimplemented from cStdDev.

◆ parsimUnpack()

virtual void parsimUnpack ( cCommBuffer buffer)
overridevirtual

Deserializes the object from an MPI receive buffer Used by the simulation kernel for parallel execution. See cObject for more details.

Reimplemented from cStdDev.

◆ collect()

virtual void collect ( double  value)
overridevirtual

Collects one observation. Delegates to the strategy object if there is one installed.

Reimplemented from cStdDev.

◆ collectWeighted()

virtual void collectWeighted ( double  value,
double  weight 
)
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()

virtual void clear ( )
overridevirtual

Clears the results collected so far.

Reimplemented from cStdDev.

◆ saveToFile()

virtual void saveToFile ( FILE *  f) const
overridevirtual

Writes the contents of the object into a text file.

Reimplemented from cStdDev.

◆ loadFromFile()

virtual void loadFromFile ( FILE *  f)
overridevirtual

Reads the object data from a file, in the format written out by saveToFile().

Reimplemented from cStdDev.

◆ merge()

virtual void merge ( const cStatistic other)
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()

cIHistogramStrategy* getStrategy ( ) const
inline

Returns a pointer to the currently used histogram strategy.

◆ binsAlreadySetUp()

virtual bool binsAlreadySetUp ( ) const
overridevirtual

Returns true if histogram bins are already available. (Bins are not yet available in the precollection phase.) See setUpBins().

Implements cAbstractHistogram.

◆ setUpBins()

virtual void 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 void setBinEdges ( const std::vector< double > &  edges)
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 void createUniformBins ( double  lo,
double  hi,
double  step 
)
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 void prependBins ( const std::vector< double > &  edges)
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 void appendBins ( const std::vector< double > &  edges)
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 void extendBinsTo ( double  value,
double  step,
int  maxNumBins = INT_MAX 
)
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 void mergeBins ( int  groupSize)
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()

const std::vector<double>& getBinEdges ( ) const
inline

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.

◆ getBinValues()

const std::vector<double>& getBinValues ( ) const
inline

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.

◆ getNumBins()

virtual int getNumBins ( ) const
inlineoverridevirtual

Returns the number of bins in the histogram.

Implements cAbstractHistogram.

◆ getBinEdge()

virtual double getBinEdge ( int  k) const
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()

virtual double getBinValue ( int  k) const
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()

virtual double getUnderflowSumWeights ( ) const
inlineoverridevirtual

Returns the total weight of the observations that were under the histogram range.

Implements cAbstractHistogram.

◆ getOverflowSumWeights()

virtual double getOverflowSumWeights ( ) const
inlineoverridevirtual

Returns the total weight of the observations that were above the histogram range.

Implements cAbstractHistogram.

◆ getNumUnderflows()

virtual int64_t getNumUnderflows ( ) const
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()

virtual int64_t getNumOverflows ( ) const
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()

virtual int64_t getNumNegInfs ( ) const
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()

virtual int64_t getNumPosInfs ( ) const
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()

virtual double getNegInfSumWeights ( ) const
inlineoverridevirtual

Returns the total weight of the observations that were negative infinity.

Implements cAbstractHistogram.

◆ getPosInfSumWeights()

virtual double getPosInfSumWeights ( ) const
inlineoverridevirtual

Returns the total weight of the observations that were above the histogram range.

Implements cAbstractHistogram.

◆ setMode()

virtual void setMode ( Mode  mode)
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 void setRange ( double  lower,
double  upper 
)
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 void setNumPrecollectedValues ( int  numPrecollect)
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 void setRangeExtensionFactor ( double  rangeExtensionFactor)
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 void setAutoExtend ( bool  autoExtend)
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 void setNumBinsHint ( int  numCells)
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 void setBinSizeHint ( double  d)
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.

◆ setRangeAuto()

virtual _OPPDEPRECATED void setRangeAuto ( int  numPrecollect = 100,
double  rangeExtensionFactor = 2.0 
)
virtual

Deprecated method. Use the combination of setNumPrecollectedValues() and setRangeExtensionFactor() instead.

◆ setRangeAutoLower()

virtual _OPPDEPRECATED void setRangeAutoLower ( double  upper,
int  numPrecollect = 100,
double  rangeExtensionFactor = 2.0 
)
virtual

Deprecated method. Use the combination of setRange(NAN, upper), setNumPrecollectedValues() and setRangeExtensionFactor() instead.

◆ setRangeAutoUpper()

virtual _OPPDEPRECATED void setRangeAutoUpper ( double  lower,
int  numPrecollect = 100,
double  rangeExtensionFactor = 2.0 
)
virtual

Deprecated method. Use the combination of setRange(lower, NAN), setNumPrecollectedValues() and setRangeExtensionFactor() instead.

◆ setNumCells()

virtual _OPPDEPRECATED void setNumCells ( int  numCells)
inlinefinalvirtual

Deprecated method, use setNumBins() instead.

◆ setCellSize()

virtual _OPPDEPRECATED void setCellSize ( double  d)
inlinefinalvirtual

Deprecated method, use setBinSize() instead.


The documentation for this class was generated from the following file: