#include <STK_Law_Categorical.h>

Inheritance diagram for STK::Law::Categorical:

Public Types
typedef IUnivLaw< int >	Base

Public Member Functions
	Categorical ()
	Default constructor.

	Categorical (Array2DVector< Real > const &prob)
	constructor with given probabilities.

template<class OtherArray >
	Categorical (OtherArray const &prob)
	constructor with given probabilities.

virtual	~Categorical ()
	destructor

Array2DVector< Real > const &	prob () const

Array2DVector< Real > const &	cumProb () const

template<class OtherArray >
void	setProb (OtherArray const &prob)

virtual int	rand () const

virtual Real	cdf (Real const &t) const
	compute the cumulative distribution function Give the probability that a Categorical random variate is less or equal to t.

virtual Real	pdf (int const &x) const
	compute the probability distribution function (density) Give the value of the pdf at the point x.

virtual Real	lpdf (int const &x) const
	compute the log probability distribution function Give the value of the log-pdf at the point x.

virtual int	icdf (Real const &prob) const
	inverse cumulative distribution function The quantile is defined as the smallest value x such that F(x) >= p , where F is the cumulative distribution function.

Public Member Functions inherited from STK::Law::IUnivLaw< int >
virtual	~IUnivLaw ()
	Virtual destructor.

virtual Real	lcdf (Real const &t) const
	compute the lower tail log-cumulative distribution function Give the log-probability that a random variate is less or equal to t.

virtual Real	cdfc (Real const &t) const
	calculate the complement of cumulative distribution function, called in statistics the survival function.

virtual Real	lcdfc (Real const &t) const
	calculate the log-complement of cumulative distribution function Give the log-probability that a random variate is greater than t.

Public Member Functions inherited from STK::Law::ILawBase
String const &	name () const

Static Public Member Functions
template<class OtherArray >
static int	rand (OtherArray const &prob)

template<class OtherArray >
static Real	lpdf (int const &x, OtherArray const &prob)
	compute the log probability distribution function Give the value of the log-pdf at the point x.

Protected Attributes
Array2DVector< Real >	prob_
	probabilities in a Categorical trial

Array2DVector< Real >	cumProb_
	cumulative probabilities in a Categorical trial

Protected Attributes inherited from STK::Law::ILawBase
String	name_
	Name of the Law.

Private Member Functions
void	computeCumProb ()

Additional Inherited Members
Protected Member Functions inherited from STK::Law::IUnivLaw< int >
	IUnivLaw (String const &name)
	Constructor.

	IUnivLaw (IUnivLaw const &law)
	copy Constructor.

Protected Member Functions inherited from STK::Law::ILawBase
	ILawBase (String const &name)
	Constructor.

	~ILawBase ()
	destructor.

Detailed Description

Categorical probability law.

In probability theory and statistics, a categorical distribution (also called a "generalized Bernoulli distribution" or, less precisely, a "discrete distribution") is a probability distribution that describes the result of a random event that can take on one of K possible outcomes, with the probability of each outcome separately specified. There is not necessarily an underlying ordering of these outcomes, but numerical labels are attached for convenience in describing the distribution, often in the range 1 to K. Note that the K-dimensional categorical distribution is the most general distribution over a K-way event; any other discrete distribution over a size-K sample space is a special case. The parameters specifying the probabilities of each possible outcome are constrained only by the fact that each must be in the range 0 to 1, and all must sum to 1.

Note that, in some fields, such as machine learning and natural language processing, the categorical and multinomial distributions are conflated, and it is common to speak of a "multinomial distribution" when a categorical distribution is actually meant.

Definition at line 68 of file STK_Law_Categorical.h.

Member Typedef Documentation

◆ Base

typedef IUnivLaw<int> STK::Law::Categorical::Base

Definition at line 71 of file STK_Law_Categorical.h.

Constructor & Destructor Documentation

◆ Categorical() [1/3]

STK::Law::Categorical::Categorical ( )

inline

Default constructor.

Only one category

Definition at line 73 of file STK_Law_Categorical.h.

73: Base(_T("Categorical")), prob_(1,1) { computeCumProb();}

_T

#define _T(x)

Let x unmodified.

Definition STK_Typedefs.h:71

STK::Law::Categorical::Base

IUnivLaw< int > Base

Definition STK_Law_Categorical.h:71

STK::Law::Categorical::prob_

Array2DVector< Real > prob_

probabilities in a Categorical trial

Definition STK_Law_Categorical.h:151

STK::Law::Categorical::computeCumProb

void computeCumProb()

Definition STK_Law_Categorical.h:207

References computeCumProb().

◆ Categorical() [2/3]

STK::Law::Categorical::Categorical ( Array2DVector< Real > const & prob )

inline

constructor with given probabilities.

The probabilities will be normalized in order to have an overall sum of 1

Parameters

prob	probabilities of success in a Categorical trial

Definition at line 78 of file STK_Law_Categorical.h.

78 : Base(_T("Categorical")), prob_(prob)

79 { computeCumProb();}

STK::Law::Categorical::prob

Array2DVector< Real > const & prob() const

Definition STK_Law_Categorical.h:91

References computeCumProb().

◆ Categorical() [3/3]

template<class OtherArray >

STK::Law::Categorical::Categorical ( OtherArray const & prob )

inline

constructor with given probabilities.

The probabilities will be normalized in order to have an overall sum of 1

Parameters

prob	probabilities of success in a Categorical trial

Definition at line 85 of file STK_Law_Categorical.h.

85 : Base(_T("Categorical"))

86 { prob_ = prob; computeCumProb();}

References computeCumProb(), prob(), and prob_.

◆ ~Categorical()

virtual STK::Law::Categorical::~Categorical ( )

inlinevirtual

destructor

Definition at line 88 of file STK_Law_Categorical.h.

88{}

Member Function Documentation

◆ cdf()

Real STK::Law::Categorical::cdf ( Real const & t ) const

inlinevirtual

compute the cumulative distribution function Give the probability that a Categorical random variate is less or equal to t.

Parameters

t	a real value

Returns: the value of the cdf

Implements STK::Law::IUnivLaw< int >.

Definition at line 189 of file STK_Law_Categorical.h.

190{ return (t<prob_.begin()) ? 0. : (t>=prob_.lastIdx()) ? 1. : cumProb_[std::floor(t)];}

STK::Law::Categorical::cumProb_

Array2DVector< Real > cumProb_

cumulative probabilities in a Categorical trial

Definition STK_Law_Categorical.h:153

References cumProb_, and prob_.

◆ computeCumProb()

void STK::Law::Categorical::computeCumProb ( )

inlineprivate

Definition at line 207 of file STK_Law_Categorical.h.

{
  cumProb_.resize(prob_.range());
  Real sum=0.;
  for (int k=prob_.begin(); k< prob_.end(); ++k)
  { cumProb_[k] = (sum+=prob_[k]);}
  // normalize
  if (sum) {cumProb_/=sum; prob_ /=sum;}
  else {STKINVALIDARGUMENT_ERROR_NO_ARG(Categorical::computeCumProb,sum of the probabilities is zero);}
}

References computeCumProb(), cumProb_, prob_, STK::IArray2D< Derived >::resize(), STKINVALIDARGUMENT_ERROR_NO_ARG, and STK::sum().

Referenced by Categorical(), Categorical(), Categorical(), computeCumProb(), and setProb().

◆ cumProb()

Array2DVector< Real > const & STK::Law::Categorical::cumProb ( ) const

inline

Returns: the cumulative probabilities of success

Definition at line 93 of file STK_Law_Categorical.h.

93{ return cumProb_;}

References cumProb_.

◆ icdf()

int STK::Law::Categorical::icdf ( Real const & prob ) const

inlinevirtual

inverse cumulative distribution function The quantile is defined as the smallest value x such that F(x) >= p , where F is the cumulative distribution function.

Parameters

prob	a probability number

Implements STK::Law::IUnivLaw< int >.

Definition at line 197 of file STK_Law_Categorical.h.

{
  if (prob<0) STKDOMAIN_ERROR_1ARG(Categorical::icdf,prob,prob must be >= 0);
  if (prob>1) STKDOMAIN_ERROR_1ARG(Categorical::icdf,prob,prob must be <= 1);
  int k;
  for (k = cumProb_.begin(); k< cumProb_.lastIdx(); ++k)
  { if (cumProb_[k] >= prob) return k;}
  return k;
}

References cumProb_, icdf(), prob(), and STKDOMAIN_ERROR_1ARG.

Referenced by icdf().

◆ lpdf() [1/2]

Real STK::Law::Categorical::lpdf ( int const & x ) const

inlinevirtual

compute the log probability distribution function Give the value of the log-pdf at the point x.

Parameters

x	a binary value

Returns: the value of the log-pdf

Reimplemented from STK::Law::IUnivLaw< int >.

Definition at line 181 of file STK_Law_Categorical.h.

182{ return (prob_[x] == 0) ? -Arithmetic<Real>::infinity() : std::log(prob_[x]);}

References prob_.

◆ lpdf() [2/2]

template<class OtherArray >

static Real STK::Law::Categorical::lpdf	(	int const &	x,
		OtherArray const &	prob
	)

inlinestatic

compute the log probability distribution function Give the value of the log-pdf at the point x.

Parameters

x	the value to compute the lpdf.
prob	the probability of each value

Returns: the value of the log-pdf

Definition at line 146 of file STK_Law_Categorical.h.

147 { return (prob[x] == 0) ? -Arithmetic<Real>::infinity() : std::log(prob[x]);}

References prob().

◆ pdf()

Real STK::Law::Categorical::pdf ( int const & x ) const

inlinevirtual

compute the probability distribution function (density) Give the value of the pdf at the point x.

Parameters

x	an integer value

Returns: the value of the pdf

Implements STK::Law::IUnivLaw< int >.

Definition at line 174 of file STK_Law_Categorical.h.

175{ return prob_[x];}

References prob_.

◆ prob()

Array2DVector< Real > const & STK::Law::Categorical::prob ( ) const

inline

Returns: the probabilities of success

Definition at line 91 of file STK_Law_Categorical.h.

91{ return prob_;}

References prob_.

Referenced by Categorical(), icdf(), lpdf(), rand(), and setProb().

◆ rand() [1/2]

int STK::Law::Categorical::rand ( ) const

inlinevirtual

Returns: a categorical random variate .

Implements STK::Law::IUnivLaw< int >.

Definition at line 160 of file STK_Law_Categorical.h.

{
  Real u = Law::generator.randUnif();
  int k;
  for(k = cumProb_.begin(); k< cumProb_.end(); k++)
  { if (u<=cumProb_[k]) return k;}
  return k;
}

References cumProb_.

Referenced by STK::CategoricalBase< Derived >::rand(), STK::MixtureSemiLearner::randomZi(), STK::IMixtureDensity< Derived >::sample(), STK::IMixtureModel< Derived >::sample(), and STK::IMixtureComposer::sStep().

◆ rand() [2/2]

template<class OtherArray >

static int STK::Law::Categorical::rand ( OtherArray const & prob )

inlinestatic

Returns: a categorical random variate .

Definition at line 129 of file STK_Law_Categorical.h.

    {
      Real u = Law::generator.randUnif(), cum = 0.;
      for(int k = prob.begin(); k< prob.lastIdx(); k++)
      {
        cum += prob[k];
        if (u<=cum) return k;
      }
      return prob.lastIdx();
    }

References prob().

◆ setProb()

template<class OtherArray >

void STK::Law::Categorical::setProb ( OtherArray const & prob )

inline

Parameters

prob	the probability of success to set

Definition at line 97 of file STK_Law_Categorical.h.

98 { prob_ = prob; computeCumProb();}

References computeCumProb(), prob(), and prob_.

Member Data Documentation

◆ cumProb_

Array2DVector<Real> STK::Law::Categorical::cumProb_

protected

cumulative probabilities in a Categorical trial

Definition at line 153 of file STK_Law_Categorical.h.

Referenced by cdf(), computeCumProb(), cumProb(), icdf(), and rand().

◆ prob_

Array2DVector<Real> STK::Law::Categorical::prob_

protected

probabilities in a Categorical trial

Definition at line 151 of file STK_Law_Categorical.h.

Referenced by Categorical(), cdf(), computeCumProb(), lpdf(), pdf(), prob(), and setProb().

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

STK_Law_Categorical.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Base

Constructor & Destructor Documentation

◆ Categorical() [1/3]

◆ Categorical() [2/3]

◆ Categorical() [3/3]

◆ ~Categorical()

Member Function Documentation

◆ cdf()

◆ computeCumProb()

◆ cumProb()

◆ icdf()

◆ lpdf() [1/2]

◆ lpdf() [2/2]

◆ pdf()

◆ prob()

◆ rand() [1/2]

◆ rand() [2/2]

◆ setProb()

Member Data Documentation

◆ cumProb_

◆ prob_