#include <cksplit.h>

Description

Implements k-split, an adaptive histogram-like density estimation algorithm. During result collection, k-split will dynamically subdivide "busy" bins (ones that collect a large number of observations), thereby refining the resolution of the histogram where needed.

The histogram produced by k-split will be an approximation, because the algorithm has no information on how to divide up observations collected into a bin before it was split. Nevertheless, for stationary distributions, k-split usually produces a superior estimate of the distribution than uniform-bin histograms. If the distribution changes over time, and especially if it shows a distinct (increasing or decreasing) trend, k-split's estimate often contains artifacts that are not part of the input distribution.

See also: Iterator Grid

Inheritance diagram for cKSplit:

Classes
struct	Grid
	Supporting struct for cKSplit. Represents one grid in the k-split data structure. More...

class	Iterator
	Walks along cells of the distribution stored in a cKSplit object. More...

Public Types
typedef int(*	CritFunc) (const cKSplit &, cKSplit::Grid &, int, double *)

typedef double(*	DivFunc) (const cKSplit &, cKSplit::Grid &, double, double *)

Public Types inherited from cPrecollectionBasedDensityEst
enum	RangeMode
	Constants for histogram range_mode. More...

Public Member Functions
Constructors, destructor, assignment.
	cKSplit (const char *name=nullptr, bool weighted=false)

	cKSplit (const cKSplit &r)

virtual	~cKSplit ()

cKSplit &	operator= (const cKSplit &res)

Redefined member functions from cStatistic and its subclasses.
virtual void	setUpBins () override

virtual int	getNumBins () const override

virtual double	getBinEdge (int k) const override

virtual double	getBinValue (int k) const override

virtual void	merge (const cStatistic *other) override

virtual void	clear () override

virtual void	saveToFile (FILE *) const override

virtual void	loadFromFile (FILE *) override

Configuring the k-split algorithm.
void	setCritFunc (CritFunc _critfunc, double *_critdata)

void	setDivFunc (DivFunc _divfunc, double *_divdata)

void	setRangeExtension (bool enabled)

Querying the k-split data structure.
int	getTreeDepth () const

int	getTreeDepth (Grid &grid) const

double	getRealCellValue (Grid &grid, int cell) const

void	printGrids () const

Grid &	getGrid (int k) const

Grid &	getRootGrid () const

Public Member Functions inherited from cPrecollectionBasedDensityEst
	cPrecollectionBasedDensityEst (const cPrecollectionBasedDensityEst &other)

	cPrecollectionBasedDensityEst (const char *name=nullptr, bool weighted=false)

virtual	~cPrecollectionBasedDensityEst ()

cPrecollectionBasedDensityEst &	operator= (const cPrecollectionBasedDensityEst &res)

virtual void	collect (double value) override

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

virtual bool	binsAlreadySetUp () const override

virtual int64_t	getNumUnderflows () const override

virtual int64_t	getNumOverflows () const override

virtual double	getUnderflowSumWeights () const override

virtual double	getOverflowSumWeights () const override

virtual int64_t	getNumNegInfs () const override

virtual int64_t	getNumPosInfs () const override

virtual double	getNegInfSumWeights () const override

virtual double	getPosInfSumWeights () const override

virtual void	setRange (double lower, double upper)

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

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

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

virtual void	setNumPrecollectedValues (int numPrecollect)

virtual int	getNumPrecollectedValues () const

virtual double	getRangeExtensionFactor () const

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 std::vector< double >	getBinEdges () const

virtual std::vector< double >	getBinValues () const

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

Redefined cObject member functions.
virtual void	collectIntoHistogram (double val) override

virtual void	collectWeightedIntoHistogram (double value, double weight) override

virtual cKSplit *	dup () const override

virtual void	parsimPack (cCommBuffer *buffer) const override

virtual void	parsimUnpack (cCommBuffer *buffer) override

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 cPrecollectionBasedDensityEst
virtual void	setupRange ()

Protected Member Functions inherited from cObject
virtual void	take (cOwnedObject *obj)

virtual void	drop (cOwnedObject *obj)

void	dropAndDelete (cOwnedObject *obj)

Constructor & Destructor Documentation

◆ cKSplit() [1/2]

cKSplit	(	const char *	name = `nullptr`,
		bool	weighted = `false`
	)

explicit

Constructor.

◆ cKSplit() [2/2]

cKSplit ( const cKSplit & r )

Copy constructor.

◆ ~cKSplit()

virtual ~cKSplit ( )

virtual

Destructor.

Member Function Documentation

◆ operator=()

cKSplit& operator= ( const cKSplit & res )

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

◆ dup()

virtual cKSplit* dup ( ) const

inlineoverridevirtual

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

Reimplemented from cAbstractHistogram.

◆ 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 cPrecollectionBasedDensityEst.

◆ 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 cPrecollectionBasedDensityEst.

◆ collectIntoHistogram()

virtual void collectIntoHistogram ( double val )

overrideprotectedvirtual

Called internally by collect(), this method updates the k-split data structure with the new value.

Implements cPrecollectionBasedDensityEst.

◆ collectWeightedIntoHistogram()

virtual void collectWeightedIntoHistogram	(	double	value,
		double	weight
	)

overrideprotectedvirtual

Called internally by collect().

Implements cPrecollectionBasedDensityEst.

◆ setUpBins()

virtual void setUpBins ( )

overridevirtual

Transforms the table of pre-collected values into the k-split data structure.

Implements cAbstractHistogram.

◆ getNumBins()

virtual int getNumBins ( ) const

overridevirtual

Returns the number of histogram cells used.

Implements cAbstractHistogram.

◆ getBinEdge()

virtual double getBinEdge ( int k ) const

overridevirtual

Returns the kth cell boundary.

Implements cAbstractHistogram.

◆ getBinValue()

virtual double getBinValue ( int k ) const

overridevirtual

Returns the number of observations that fell into the kth histogram cell.

Implements cAbstractHistogram.

◆ merge()

virtual void merge ( const cStatistic * other )

overridevirtual

Merging is not supported by this class. This method throws an error.

Reimplemented from cPrecollectionBasedDensityEst.

◆ clear()

virtual void clear ( )

overridevirtual

Clears the results collected so far.

Reimplemented from cPrecollectionBasedDensityEst.

◆ saveToFile()

virtual void saveToFile ( FILE * ) const

overridevirtual

Writes the contents of the object into a text file.

Reimplemented from cPrecollectionBasedDensityEst.

◆ loadFromFile()

virtual void loadFromFile ( FILE * )

overridevirtual

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

Reimplemented from cPrecollectionBasedDensityEst.

◆ setCritFunc()

void setCritFunc	(	CritFunc	_critfunc,
		double *	_critdata
	)

Configures the k-split algorithm by supplying a custom split criterion function.

◆ setDivFunc()

void setDivFunc	(	DivFunc	_divfunc,
		double *	_divdata
	)

Configures the k-split algorithm by supplying a custom cell division function.

◆ setRangeExtension()

void setRangeExtension ( bool enabled )

Enables/disables range extension. If range extension is enabled, a new observation that falls outside the k-split range (i.e. outside the root grid) will cause the range to be expanded (i.e. new root getGrid(s) to be placed above the current root grid). If range extension is disabled, such observations will simply be counted as underflows or overflows.

◆ getTreeDepth() [1/2]

int getTreeDepth ( ) const

Returns the depth of the k-split tree.

◆ getTreeDepth() [2/2]

int getTreeDepth ( Grid & grid ) const

Returns the depth of the k-split tree measured from the specified grid.

◆ getRealCellValue()

double getRealCellValue	(	Grid &	grid,
		int	cell
	)		const

Returns the actual amount of observations in cell 'cell' of 'grid'. This is not necessarily an integer value because of previous cell splits.

◆ printGrids()

void printGrids ( ) const

Dumps the contents of the k-split data structure to EV.

◆ getGrid()

Grid& getGrid ( int k ) const

inline

Returns the kth grid in the k-split data structure.

◆ getRootGrid()

Grid& getRootGrid ( ) const

inline

Returns the root grid of the k-split data structure.

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

cksplit.h

Description

Classes

Public Types

Public Member Functions

Redefined cObject member functions.

Additional Inherited Members

Constructor & Destructor Documentation

◆ cKSplit() [1/2]

◆ cKSplit() [2/2]

◆ ~cKSplit()

Member Function Documentation

◆ operator=()

◆ dup()

◆ parsimPack()

◆ parsimUnpack()

◆ collectIntoHistogram()

◆ collectWeightedIntoHistogram()

◆ setUpBins()

◆ getNumBins()

◆ getBinEdge()

◆ getBinValue()

◆ merge()

◆ clear()

◆ saveToFile()

◆ loadFromFile()

◆ setCritFunc()

◆ setDivFunc()

◆ setRangeExtension()

◆ getTreeDepth() [1/2]

◆ getTreeDepth() [2/2]

◆ getRealCellValue()

◆ printGrids()

◆ getGrid()

◆ getRootGrid()