The DiscreteDistribution class
Abstract class for all discrete distributions. More...

#include <discrete.hpp>

Inheritance diagram for randlib::DiscreteDistribution< IntType >:

[legend]

Collaboration diagram for randlib::DiscreteDistribution< IntType >:

[legend]

Public Member Functions
virtual	~DiscreteDistribution ()

virtual double	P (const IntType &k) const

virtual double	logP (const IntType &x) const =0

void	ProbabilityMassFunction (std::span< const IntType > x, std::span< double > y) const
	fill vector y with P(x)

void	LogProbabilityMassFunction (std::span< const IntType > x, std::span< double > y) const
	fill vector y with logP(x)

IntType	Mode () const override
	Mode is the value, which has the largest probability to happen, or, in the case of continuous distribution, has the largest value of density function.

double	Hazard (const IntType &x) const override

double	LikelihoodFunction (std::span< const IntType > sample) const override

double	LogLikelihoodFunction (std::span< const IntType > sample) const override

bool	PearsonChiSquaredTest (std::span< const IntType > orderStatistic, double alpha, int lowerBoundary, int upperBoundary, size_t numberOfEstimatedParameters=0) const

bool	PearsonChiSquaredTest (std::span< const IntType > orderStatistic, double alpha, size_t numberOfEstimatedParameters=0) const

Public Member Functions inherited from randlib::UnivariateDistribution< IntType >
virtual	~UnivariateDistribution ()

virtual Support	SupportType () const=0

bool	isLeftBounded () const

bool	isRightBounded () const

virtual long double	Mean () const=0

virtual long double	Variance () const=0

IntType	Quantile (double p) const

IntType	Quantile1m (double p) const

void	QuantileFunction (std::span< const double > p, std::span< IntType > y) const

void	QuantileFunction1m (std::span< const double > p, std::span< IntType > y) const

std::complex< double >	CF (double t) const

void	CharacteristicFunction (std::span< const double > t, std::span< std::complex< double > > y) const

void	HazardFunction (std::span< const IntType > x, std::span< double > y) const

virtual IntType	Median () const

virtual long double	Skewness () const

virtual long double	Kurtosis () const

virtual long double	ExcessKurtosis () const

virtual long double	SecondMoment () const

virtual long double	ThirdMoment () const

virtual long double	FourthMoment () const

Public Member Functions inherited from randlib::ProbabilityDistribution< T >
virtual	~ProbabilityDistribution ()=default

virtual std::string	Name () const =0

virtual T	MinValue () const =0

virtual T	MaxValue () const =0

virtual double	F (const T &x) const =0

void	CumulativeDistributionFunction (std::span< const T > x, std::span< double > y) const

virtual double	S (const T &x) const

void	SurvivalFunction (std::span< const T > x, std::span< double > y) const

template<std::uniform_random_bit_generator G>
T	operator() (G &g) const
	Draws a variate with the given engine through the virtual interface.

T	Variate () const
	Uses the engine of this object, so it is not thread-safe for one object; use operator() with one engine per thread instead.

void	Sample (std::span< T > outputData) const
	Fills the output with variates drawn with the engine of this object.

template<std::uniform_random_bit_generator G>
void	Sample (G &g, std::span< T > outputData) const
	Fills the output with variates drawn with the given engine.

void	Reseed (std::uint64_t seed)

Protected Member Functions
	DiscreteDistribution ()

IntType	quantileImpl (double p, IntType initValue) const override

IntType	quantileImpl (double p) const override

IntType	quantileImpl1m (double p, IntType initValue) const override

IntType	quantileImpl1m (double p) const override

long double	ExpectedValue (const std::function< double(IntType)> &funPtr, IntType minPoint, IntType maxPoint) const override

std::complex< double >	CFImpl (double t) const override

Protected Member Functions inherited from randlib::UnivariateDistribution< IntType >
	UnivariateDistribution ()

Protected Member Functions inherited from randlib::ProbabilityDistribution< T >
std::string	toStringWithPrecision (const double a_value, const int n=6) const

	ProbabilityDistribution ()=default

DefaultEngine &	engine () const

virtual T	variate (detail::EngineRef g) const =0
	Every concrete distribution implements this by calling its templated operator()

virtual void	sample (detail::EngineRef g, std::span< T > outputData) const
	Fills the output with variate(g); distributions with a faster bulk algorithm override it.

fit_error	fitError (FitErrorCode code, const std::string &explanation) const

Additional Inherited Members
Public Types inherited from randlib::ProbabilityDistribution< T >
using	value_type = T

Static Public Member Functions inherited from randlib::UnivariateDistribution< IntType >
static long double	GetSampleSum (std::span< const IntType > sample)

static long double	GetSampleMean (std::span< const IntType > sample)

static long double	GetSampleLogMean (std::span< const IntType > sample)

static long double	GetSampleVariance (std::span< const IntType > sample, double mean)

static long double	GetSampleLogVariance (std::span< const IntType > sample, double logMean)

static LongDoublePair	GetSampleMeanAndVariance (std::span< const IntType > sample)

static LongDoublePair	GetSampleLogMeanAndVariance (std::span< const IntType > sample)

static std::tuple< long double, long double, long double, long double >	GetSampleStatistics (std::span< const IntType > sample)

Static Protected Member Functions inherited from randlib::UnivariateDistribution< IntType >
static bool	allElementsAreNotGreaterThan (IntType value, std::span< const IntType > sample)

static bool	allElementsAreNotSmallerThan (IntType value, std::span< const IntType > sample)

static bool	allElementsAreNonNegative (std::span< const IntType > sample)

static bool	allElementsArePositive (std::span< const IntType > sample)

Static Protected Attributes inherited from randlib::ProbabilityDistribution< T >
static constexpr size_t	MAX_ITER_REJECTION = detail::MAX_ITER_REJECTION
	MAX_ITER_REJECTION upper boundary for maximum amount of iterations in rejection methods one thousand should be enough to be sure there is a bug (or rejection method is too slow to be used)

static constexpr char	POSITIVITY_VIOLATION [] = "All elements should be positive"

static constexpr char	NON_NEGATIVITY_VIOLATION [] = "All elements should be non-negative"

static constexpr char	UPPER_LIMIT_VIOLATION [] = "No element should be greater than "

static constexpr char	LOWER_LIMIT_VIOLATION [] = "No element should be smaller than "

Detailed Description

template<typename IntType>
class randlib::DiscreteDistribution< IntType >

The DiscreteDistribution class
Abstract class for all discrete distributions.

Constructor & Destructor Documentation

◆ DiscreteDistribution()

template<typename IntType >

randlib::DiscreteDistribution< IntType >::DiscreteDistribution ( )

inlineprotected

◆ ~DiscreteDistribution()

template<typename IntType >

virtual randlib::DiscreteDistribution< IntType >::~DiscreteDistribution ( )

inlinevirtual

Member Function Documentation

◆ CFImpl()

template<typename IntType >

std::complex< double > randlib::DiscreteDistribution< IntType >::CFImpl ( double t ) const

overrideprotectedvirtual

Parameters

t

Returns: characteristic function implementation (inverse Fourier transform of pdf)

Σ P(k) e^{itk}, summed outwards from the median. Beyond the last term K of a walk with ratio r = e^{±it}, the remainder Σ_{m≥1} P(K + m) r^{K+m} is replaced by the first terms of Euler's transformation r^{K+1} / (1 - r) Σ_j (r / (1 - r))^j Δ^j P(K + 1), with forward differences Δ along the walk. The walk stops once the next term of that series is negligible or the remaining mass is; summing until P(k) itself vanishes would take ~10^10 terms for Zeta(2)

Reimplemented from randlib::UnivariateDistribution< IntType >.

◆ ExpectedValue()

template<typename IntType >

long double randlib::DiscreteDistribution< IntType >::ExpectedValue	(	const std::function< double(IntType)> &	funPtr,
		IntType	minPoint,
		IntType	maxPoint
	)		const

overrideprotectedvirtual

Parameters

funPtr	pointer on function g(x) with finite support which expected value should be returned
minPoint	min{x \| g(x) ≠ 0}
maxPoint	max{x \| g(x) ≠ 0}

Returns: E[g(x)]

Implements randlib::UnivariateDistribution< IntType >.

◆ Hazard()

template<typename IntType >

double randlib::DiscreteDistribution< IntType >::Hazard ( const IntType & x ) const

overridevirtual

Parameters

x

Returns: hazard function

0/1

0/0

Implements randlib::UnivariateDistribution< IntType >.

◆ LikelihoodFunction()

template<typename IntType >

double randlib::DiscreteDistribution< IntType >::LikelihoodFunction ( std::span< const IntType > sample ) const

overridevirtual

Parameters

sample

Returns: likelihood function of the distribution for given sample

Implements randlib::UnivariateDistribution< IntType >.

Reimplemented in randlib::UniformDiscreteRand< IntType >.

◆ LogLikelihoodFunction()

template<typename IntType >

double randlib::DiscreteDistribution< IntType >::LogLikelihoodFunction ( std::span< const IntType > sample ) const

overridevirtual

Parameters

sample

Returns: log-likelihood function of the distribution for given sample

Implements randlib::UnivariateDistribution< IntType >.

Reimplemented in randlib::UniformDiscreteRand< IntType >.

◆ logP()

template<typename IntType >

virtual double randlib::DiscreteDistribution< IntType >::logP ( const IntType & x ) const

pure virtual

Parameters

x

Returns: logarithm of probability to get x

◆ LogProbabilityMassFunction()

template<typename IntType >

void randlib::DiscreteDistribution< IntType >::LogProbabilityMassFunction	(	std::span< const IntType >	x,
		std::span< double >	y
	)		const

fill vector y with logP(x)

Parameters

x
y

◆ Mode()

template<typename IntType >

IntType randlib::DiscreteDistribution< IntType >::Mode ( ) const

overridevirtual

Mode is the value, which has the largest probability to happen, or, in the case of continuous distribution, has the largest value of density function.

Returns: mode. In case, when it's not unique, return any of them.

Works only for unimodal distributions

Implements randlib::UnivariateDistribution< IntType >.

Reimplemented in randlib::HyperGeometricRand< IntType >, randlib::LogarithmicRand< IntType >, randlib::NegativeBinomialDistribution< IntType, T >, randlib::PoissonRand< IntType >, randlib::PoissonRand< int >, randlib::RademacherRand, randlib::SkellamRand< IntType >, randlib::UniformDiscreteRand< IntType >, randlib::YuleRand< IntType >, randlib::ZetaRand< IntType >, randlib::ZetaRand< long long int >, and randlib::ZipfRand< IntType >.

◆ P()

template<typename IntType >

virtual double randlib::DiscreteDistribution< IntType >::P ( const IntType & k ) const

inlinevirtual

Parameters

k

Returns: probability to get k

◆ PearsonChiSquaredTest() [1/2]

template<typename IntType >

bool randlib::DiscreteDistribution< IntType >::PearsonChiSquaredTest	(	std::span< const IntType >	orderStatistic,
		double	alpha,
		int	lowerBoundary,
		int	upperBoundary,
		size_t	numberOfEstimatedParameters = `0`
	)		const

Parameters

orderStatistic	sample sorted in ascending order
alpha	significance level of the test
lowerBoundary	setting of the left most interval (-infinity, lowerBoundary]
upperBoundary	setting of the right most interval [upperBoundary, infinity)
numberOfEstimatedParameters	zero by default

Returns: true if sample is from this distribution according to Pearson's chi-squared test, false otherwise

Chi-squared test is implemented only for discrete distribution, as it is much more complicated for continuous one. The problem is ambiguity of grouping sample into intervals. In the case when parameters are estimated by maximum-likelihood estimator, using original observations, statistics might not follow asymptotic chi-square distribution and that leads to serious underestimate of the error of the first kind. For more details look: "The use of MLE in chi-square tests for goodness of fit" by Herman Chernoff and E.L. Lehmann

Sanity checks

Cells are (-∞, lower], every value in (lower, upper], including unobserved ones, and (upper, ∞). A boundary at the end of the support is replaced by the extreme observation, so the tails beyond the sample are grouped into one cell each. An unobserved value contributes its probability to the sum, so those cells are accounted for together

◆ PearsonChiSquaredTest() [2/2]

template<typename IntType >

bool randlib::DiscreteDistribution< IntType >::PearsonChiSquaredTest	(	std::span< const IntType >	orderStatistic,
		double	alpha,
		size_t	numberOfEstimatedParameters = `0`
	)		const

Parameters

orderStatistic	sample sorted in ascending order
alpha	significance level of the test
numberOfEstimatedParameters	zero by default

Returns: true if sample is from this distribution according to Pearson's chi-squared test, false otherwise In this function user won't set upper and lower intervals for tails. However it might be useful to group rare events for chi-squared test to achieve better results

◆ ProbabilityMassFunction()

template<typename IntType >

void randlib::DiscreteDistribution< IntType >::ProbabilityMassFunction	(	std::span< const IntType >	x,
		std::span< double >	y
	)		const

fill vector y with P(x)

Parameters

x
y

◆ quantileImpl() [1/2]

template<typename IntType >

IntType randlib::DiscreteDistribution< IntType >::quantileImpl ( double p ) const

overrideprotectedvirtual

Implements randlib::UnivariateDistribution< IntType >.

◆ quantileImpl() [2/2]

template<typename IntType >

IntType randlib::DiscreteDistribution< IntType >::quantileImpl	(	double	p,
		IntType	initValue
	)		const

overrideprotectedvirtual

Parameters

p
initValue	initial value of x

Returns: such x that F(x) = p

go up

go down

if lower quantile is not equal probability, we return upper quantile

Implements randlib::UnivariateDistribution< IntType >.

◆ quantileImpl1m() [1/2]

template<typename IntType >

IntType randlib::DiscreteDistribution< IntType >::quantileImpl1m ( double p ) const

overrideprotectedvirtual

Implements randlib::UnivariateDistribution< IntType >.

◆ quantileImpl1m() [2/2]

template<typename IntType >

IntType randlib::DiscreteDistribution< IntType >::quantileImpl1m	(	double	p,
		IntType	initValue
	)		const

overrideprotectedvirtual

Parameters

p
initValue	initial value of x

Returns: such x that F(x) = 1 - p

go up

go down

if lower quantile is not equal probability, we return upper quantile

Implements randlib::UnivariateDistribution< IntType >.

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

discrete.hpp

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DiscreteDistribution()

◆ ~DiscreteDistribution()

Member Function Documentation

◆ CFImpl()

◆ ExpectedValue()

◆ Hazard()

◆ LikelihoodFunction()

◆ LogLikelihoodFunction()

◆ logP()

◆ LogProbabilityMassFunction()

◆ Mode()

◆ P()

◆ PearsonChiSquaredTest() [1/2]

◆ PearsonChiSquaredTest() [2/2]

◆ ProbabilityMassFunction()

◆ quantileImpl() [1/2]

◆ quantileImpl() [2/2]

◆ quantileImpl1m() [1/2]

◆ quantileImpl1m() [2/2]