#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 cObject member functions.
virtual cKSplit *	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	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	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

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

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

	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

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 ()

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

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)

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)

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

virtual bool	isSoftOwner () const

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)

virtual	~cObject ()

virtual const char *	getClassName () const

bool	isName (const char *s) const

virtual const char *	getFullName () const

virtual std::string	getFullPath () const

const cObject *	getThisPtr () const

virtual _OPPDEPRECATED std::string	info () const

virtual _OPPDEPRECATED std::string	detailedInfo () const

virtual void	forEachChild (cVisitor *v)

cObject *	findObject (const char *name, bool deep=true)

void	copyNotSupported () const

Protected Member Functions
virtual void	collectIntoHistogram (double val) override

virtual void	collectWeightedIntoHistogram (double value, double weight) override

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)

Additional Inherited Members
Static Public Member Functions inherited from cOwnedObject
static long	getTotalObjectCount ()

static long	getLiveObjectCount ()

static void	resetObjectCounters ()

static cDefaultList *	getDefaultOwner ()

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's operator=() for more 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

Protected 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()