Statistical Result Collection

Description

The primary way of recording statistics from simulations is by means of signals and declared statistics, i.e. using @statistic properties in NED files. However, the simulation library also provides some classes in case programmatic result collection is needed.

Scalar values can be recorded in the output scalar file with the recordScalar() method of the module or channel. To collect statistic summaries (mean, stddev, etc.) or histograms, use the cStdDev and cHistogram classes. Their contents can be recorded into the output scalar file with the recordStatistic() method of the module or channel, or with the record() method of the statistic object itself. To record output vectors (time series data), use the cOutVector class.

Declarative (@statistic-based) result recording is also extensible, via the cResultFilter and cResultRecorder classes; see Result Filters and Recorders.

All result collection methods eventually delegate to "record" methods in cEnvir, i.e. the actual recording is decoupled from the result collection part, and can be changed without affecting the rest of the code.

The central classes are:

• cStdDev computes statistics like (unweighted and weighted) mean, standard deviation, minimum and maximum value.
• cHistogram is a generic histogram class. Bin creation can be customized via various histogram strategy classes like e.g. cAutoRangeHistogramStrategy.
• cPSquare is a class that uses the P² algorithm by Jain and Chlamtac. The algorithm calculates quantiles without storing the observations.
• cOutVector provides a way to record output vectors from the simulation.

Some other classes closely related to the above ones are not listed here explicitly, but you can find them via 'See also' links from their main classes.

Classes
class	cHistogram
	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). More...
class	cIHistogramStrategy
	Interface for histogram strategy classes. Histogram strategies encapsulate the task of setting up and managing the bins in a cHistogram. More...
class	cFixedRangeHistogramStrategy
	Histogram strategy that sets up uniform bins over a predetermined interval. The number of bins and the histogram mode (integers or reals) also need to be configured. This strategy does not use precollection, as all input for setting up the bins must be explicitly provided by the user. More...
class	cPrecollectionBasedHistogramStrategy
	Base class for histogram strategies that employ a precollection phase in order to gather input for setting up the bins. This class provides storage for the precollected values, and also a built-in algorithm for deciding when to stop precollection. More...
class	cDefaultHistogramStrategy
	A strategy class used by the default setup of cHistogram. It is meant to provide a good quality uniform-bin histogram without requiring manual configuration. More...
class	cAutoRangeHistogramStrategy
	A generic, very configurable histogram strategy that is meant to provide a good quality histogram for practical distributions, and creates uniform bins. This strategy uses precollection to gather input information about the distribution before setting up the bins. More...
class	cKSplit
	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. More...
class	cOutVector
	Responsible for recording an "output vector" into the simulation results file. An output vector is a time series where each value is recorded with its own timestamp. Time stamps are monotonically increasing. The vector is registered in the result file with the module (the owner of this object), a vector name, and optional attributes. The first two identify the vector, and the attributes convey additional meta information that may be used by result analysis tools. More...
class	cPrecollectionBasedDensityEst
	Base class for histogram-like density estimation classes. More...
class	cPSquare
	Implements the P2 algorithm, which calculates quantile values without storing the observations. See the seminal paper titled "The P^2 Algorithm for Dynamic Statistical Computing Calculation of Quantiles and Histograms Without Storing Observations" by Raj Jain and Imrich Chlamtac. More...
class	cStatistic
	cStatistic is an abstract class for computing statistical properties of a random variable. More...
class	cStdDev
	Statistics class to collect min, max, mean, and standard deviation. More...

Typedefs
typedef int(*	CritFunc) (const cKSplit &, cKSplit::Grid &, int, const double *)
typedef double(*	DivFunc) (const cKSplit &, cKSplit::Grid &, double, const double *)
typedef void(*	RecordFunc) (void *, simtime_t, double)
	Prototype for callback functions that are used to notify graphical user interfaces when values are recorded to an output vector (see cOutVector). More...

Typedef Documentation

CritFunc

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

Prototype for cell split criterion functions used by cKSplit objects.

DivFunc

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

Prototype for cell division criterion functions used by cKSplit objects.

RecordFunc

typedef void(* RecordFunc) (void *, simtime_t, double)

Prototype for callback functions that are used to notify graphical user interfaces when values are recorded to an output vector (see cOutVector).