Gamma distribution law. More...

#include <STK_Law_Gamma.h>

Inheritance diagram for STK::Law::Gamma:

Public Types
typedef IUnivLaw< Real >	Base

Public Member Functions
	Gamma (Real const &shape=1., Real const &scale=1.)
	Default constructor.

virtual	~Gamma ()
	destructor

Real const &	shape () const

Real const &	scale () const

void	setShape (Real const &shape)

void	setScale (Real const &scale)

virtual Real	rand () const
	generate a gamma random variate using the G.S algorithm of Ahrens and Dieter (1974) for 0<a_<1 and Marsaglia fast Gamma generator with enhanced squeeze step for a>1.

virtual Real	pdf (Real const &x) const
	compute

virtual Real	lpdf (Real const &x) const
	Compute.

virtual Real	cdf (Real const &t) const

virtual Real	icdf (Real const &p) const

Public Member Functions inherited from STK::Law::IUnivLaw< Real >
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
static Real	rand (Real const &shape, Real const &scale)

static Real	pdf (Real const &x, Real const &shape, Real const &scale)

static Real	lpdf (Real const &x, Real const &shape, Real const &scale)

static Real	cdf (Real const &t, Real const &shape, Real const &scale)

static Real	icdf (Real const &p, Real const &shape, Real const &scale)

Protected Attributes
Real	a_
	The shape parameter.

Real	b_
	The scale parameter.

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

Private Member Functions
void	computeCtes () const
	compute c_ and d_

Private Attributes
Real	c_
	First and second constants for rand.

Real	d_

Additional Inherited Members
Protected Member Functions inherited from STK::Law::IUnivLaw< Real >
	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

Gamma distribution law.

In probability theory and statistics, the gamma distribution is a two-parameter family of continuous probability distributions. The common exponential distribution and chi-squared distribution are special cases of the gamma distribution.

The probability pdf function of the gamma distribution can be expressed in terms of the Funct::gamma function:

$f(x;a,b) = \left(\frac{x}{b}\right)^{a-1} \frac{e^{-x/b}}{b \, \Gamma(a)} \ \mathrm{for}\ x>0,\ a>0,\ b>0$

where a is the shape parameter and b is the scale parameter.

Definition at line 62 of file STK_Law_Gamma.h.

Member Typedef Documentation

◆ Base

typedef IUnivLaw<Real> STK::Law::Gamma::Base

Definition at line 65 of file STK_Law_Gamma.h.

Constructor & Destructor Documentation

◆ Gamma()

STK::Law::Gamma::Gamma	(	Real const &	shape = `1.`,
		Real const &	scale = `1.`
	)

inline

Default constructor.

Parameters

shape	shape (position) parameter
scale	scale (dispersion) parameter

Definition at line 70 of file STK_Law_Gamma.h.

        : Base(_T("Gamma")), a_(shape), b_(scale)
#ifndef IS_RTKPP_LIB
         , c_(), d_()
#endif
    {
      // check parameters
      if ( !Arithmetic<Real>::isFinite(a_) || !Arithmetic<Real>::isFinite(b_)
         || a_ <= 0 || b_ <= 0
         )
      { STKDOMAIN_ERROR_2ARG(Gamma::Gamma,a_, b_,arguments not valid);}
#ifndef IS_RTKPP_LIB
      computeCtes();
#endif
    }

References a_, b_, computeCtes(), Gamma(), and STKDOMAIN_ERROR_2ARG.

Referenced by Gamma().

◆ ~Gamma()

virtual STK::Law::Gamma::~Gamma ( )

inlinevirtual

destructor

Definition at line 86 of file STK_Law_Gamma.h.

86{}

Member Function Documentation

◆ cdf() [1/2]

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

virtual

Returns: the cumulative distribution function

Parameters

t	a positive real value

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

Definition at line 149 of file STK_Law_Gamma.cpp.

{
  // check NA value
  if (isNA(t)) return t;
  // trivial cases
  if (t <= 0.) return 0.;
  if (Arithmetic<Real>::isInfinite(t)) return 1.;
  // general case
  return Funct::gammaRatioP(a_, t/b_);
}

References a_, b_, STK::Funct::gammaRatioP(), and STK::isNA().

◆ cdf() [2/2]

Real STK::Law::Gamma::cdf	(	Real const &	t,
		Real const &	shape,
		Real const &	scale
	)

static

Returns: the cumulative distribution function

Parameters

t	a positive real value
shape,scale	shape and scale parameters

Definition at line 270 of file STK_Law_Gamma.cpp.

{
  // check NA value
  if (isNA(t)) return t;
  // trivial cases
  if (t <= 0.) return 0.;
  if (Arithmetic<Real>::isInfinite(t)) return 1.;
  // general case
  return Funct::gammaRatioP(a, t/b);
}

References STK::Funct::gammaRatioP(), and STK::isNA().

◆ computeCtes()

void STK::Law::Gamma::computeCtes ( ) const

private

compute c_ and d_

Definition at line 290 of file STK_Law_Gamma.cpp.

{
  if (a_ < 1.)
  {
    c_ = 1. + a_/Const::_E_;
    d_ = c_ * generator.randUnif();
  }
  else
  {
    d_ = a_-1./3.;
    c_ = 1./std::sqrt(9.*d_);
  }
}

References a_, c_, and d_.

Referenced by Gamma(), and setShape().

◆ icdf() [1/2]

Real STK::Law::Gamma::icdf ( Real const & p ) const

virtual

Returns: the inverse cumulative distribution function

Parameters

p	a probability number

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

Definition at line 164 of file STK_Law_Gamma.cpp.

{
  STKRUNTIME_ERROR_1ARG(Gamma::icdf,p,not implemented);
  return 0.0;
}

References icdf(), and STKRUNTIME_ERROR_1ARG.

Referenced by icdf().

◆ icdf() [2/2]

Real STK::Law::Gamma::icdf	(	Real const &	p,
		Real const &	shape,
		Real const &	scale
	)

static

Returns: the inverse cumulative distribution function

Parameters

p	a probability number
shape,scale	shape and scale parameters

Definition at line 285 of file STK_Law_Gamma.cpp.

{
  return 0;
}

◆ lpdf() [1/2]

Real STK::Law::Gamma::lpdf ( Real const & x ) const

virtual

Compute.

$\ln(f(x;\alpha,\beta)) = - x/\beta + (\alpha-1) \ln(x) - \alpha \ln(\beta) + \ln(\Gamma(\alpha))$

Returns: the value of the log-pdf

Parameters

x	a positive real value

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

Definition at line 127 of file STK_Law_Gamma.cpp.

{
  // check NA value
  if (isNA(x)) return x;
  // trivial cases
  if (x < 0.) return -Arithmetic<Real>::infinity();
  if (Arithmetic<Real>::isInfinite(x)) return -Arithmetic<Real>::infinity();
  if (x == 0.) return (a_<1) ? Arithmetic<Real>::infinity()
                             : (a_>1.) ?  -Arithmetic<Real>::infinity() : -std::log(b_);
  // general case
  return (a_ < 1) ? Funct::poisson_lpdf_raw(a_, x/b_) +std::log(a_/x)
                  : Funct::poisson_lpdf_raw(a_-1, x/b_) - std::log(b_);
}

References a_, b_, STK::isNA(), and STK::Funct::poisson_lpdf_raw().

Referenced by STK::JointGammaModel< Array, WColVector >::computeLnLikelihood(), STK::ModelGamma_aj_bj< Data_, WColVector_ >::computeLnLikelihood(), and STK::GammaBase< Derived >::lnComponentProbability().

◆ lpdf() [2/2]

Real STK::Law::Gamma::lpdf	(	Real const &	x,
		Real const &	shape,
		Real const &	scale
	)

static

Returns: the value of the log-pdf

Parameters

x	a positive real value
shape,scale	shape and scale parameters

Definition at line 251 of file STK_Law_Gamma.cpp.

{
  // check NA value
  if (isNA(x)) return x;
  // trivial cases
  if (x < 0.) return -Arithmetic<Real>::infinity();
  if (Arithmetic<Real>::isInfinite(x)) return -Arithmetic<Real>::infinity();
  if (x == 0.) return (a<1) ? Arithmetic<Real>::infinity()
                            : (a>1.) ?  -Arithmetic<Real>::infinity() : -std::log(b);
  // general case
  return (a < 1) ? Funct::poisson_lpdf_raw(a, x/b) + std::log(a/x)
                 : Funct::poisson_lpdf_raw(a-1, x/b) - std::log(b);
}

References STK::isNA(), and STK::Funct::poisson_lpdf_raw().

◆ pdf() [1/2]

Real STK::Law::Gamma::pdf ( Real const & x ) const

virtual

compute

$f(x;\alpha,\beta) = \left(\frac{x}{\beta}\right)^{\alpha-1} \frac{e^{-x/\beta}}{\beta \, \Gamma(\alpha)} \ \mathrm{for}\ x > 0$

where $\alpha >, \mbox{ et } \beta > 0$ are the shape and scale parameters.

Returns: the value of the pdf

Parameters

x	a positive real value

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

Definition at line 106 of file STK_Law_Gamma.cpp.

{
  // check NA value
  if (isNA(x)) return x;
  // trivial cases
  if (x < 0.) return 0.;
  if (Arithmetic<Real>::isInfinite(x)) return 0.;
  if (x == 0.) return (a_<1) ? Arithmetic<Real>::infinity()
                             : (a_>1.) ?  0. : 1./b_;
  // general case
  return (a_ < 1) ? Funct::poisson_pdf_raw(a_, x/b_) * a_/x
                  : Funct::poisson_pdf_raw(a_-1, x/b_)/b_;
}

References a_, b_, STK::isNA(), and STK::Funct::poisson_pdf_raw().

◆ pdf() [2/2]

Real STK::Law::Gamma::pdf	(	Real const &	x,
		Real const &	shape,
		Real const &	scale
	)

static

Returns: the value of the pdf

Parameters

x	a positive real value
shape,scale	shape and scale parameters

Definition at line 230 of file STK_Law_Gamma.cpp.

{
  // check NA value
  if (isNA(x)) return x;
  // trivial cases
  if (x < 0.) return 0.;
  if (Arithmetic<Real>::isInfinite(x)) return 0.;
  if (x == 0.) return (a<1) ? Arithmetic<Real>::infinity()
                            : (a>1.) ?  0. : 1./b;
  // general case
  return (a < 1) ? Funct::poisson_pdf_raw(a, x/b) * a/x
                 : Funct::poisson_pdf_raw(a-1, x/b)/b;
}

References STK::isNA(), and STK::Funct::poisson_pdf_raw().

◆ rand() [1/2]

Real STK::Law::Gamma::rand ( ) const

virtual

generate a gamma random variate using the G.S algorithm of Ahrens and Dieter (1974) for 0<a_<1 and Marsaglia fast Gamma generator with enhanced squeeze step for a>1.

Returns: a pseudo Gamma random variate.

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

Definition at line 52 of file STK_Law_Gamma.cpp.

{
  // GS algorithm for parameter a_ < 1.
  if (a_ < 1.)
  {
    if(a_ == 0.) return 0.;
    Real x;
    do
    {
      Real p = c_ * generator.randUnif();
      if (p >= 1.)
      {
        x = -std::log((c_ - p) / a_);
        if (generator.randExp() >= (1. - a_) * std::log(x)) break;
      }
      else
      {
        x = std::exp(std::log(p) / a_);
        if (generator.randExp() >= x) break;
      }
    }
    while(1);
    return(x*b_);
  }
  // Exponential law for parameter a_ = 1
  if (a_ == 1.0) return b_*generator.randExp();
  // Marsaglia fast Gamma generator with enhanced squeeze step for a>1
  // initialize constants
  Real v;
  while(1)
  {
    Real x,u;
   // generate gaussian rv in the range (-1/c, infty)
    while( (v = 1. + c_* ( x = generator.randGauss() ) ) <= 0. );
    // cubic normal variate
    v = v*v*v;
    // squeeze step
    if ( (u = generator.randUnif()) < 1.-(x*x)*(x*x)/(108. * d_) ) break;
    // rejection step
    if ( std::log(u) < 0.5*x*x+d_*(1.-v+std::log(v)) ) break;
  }
  return b_*d_*v;
}

References a_, b_, c_, and d_.

Referenced by STK::Law::Beta::rand(), STK::GammaBase< Derived >::rand(), STK::Law::Beta::rand(), and rand().

◆ rand() [2/2]

Real STK::Law::Gamma::rand	(	Real const &	shape,
		Real const &	scale
	)

static

Returns: a pseudo Gamma random variate with the specified parameters.

Parameters

shape,scale shape and scale parameters

Definition at line 170 of file STK_Law_Gamma.cpp.

{
  // check parameters
  if (  !Arithmetic<Real>::isFinite(a) || !Arithmetic<Real>::isFinite(b)
     || a <= 0 || b <= 0
     )
    STKDOMAIN_ERROR_2ARG(Gamma::rand,a, b,arguments not valid);
  // GS algorithm for parameter a_ < 1.
  if (a < 1.)
  {
    Real c = 1. + a/Const::_E_;
    Real x;
    if(a == 0.) return 0.;
    do
    {
      Real p = c * generator.randUnif();
      if (p >= 1.)
      {
        x = -std::log((c - p) / a);
        if (generator.randExp() >= (1. - a) * std::log(x)) break;
      }
      else
      {
        x = std::exp(std::log(p) / a);
        if (generator.randExp() >= x) break;
      }
    } while(1);
    return b *x;
  }
  // special case
  if (a == 1.0) return Exponential::rand(b);
  // Marsaglia fast Gamma generator with enhanced squeeze step for alpha>1
  // initialize constants
  const Real d = a-1./3.;
  const Real c = 1./sqrt(9.*d);
  // rejection method : main loop
  Real v;
  while(1)
  {
    // auxiliary variables
    Real x,u;
    // generate gaussian rv in the range (-1/c, infty)
    while( (v = 1. + c * ( x = generator.randGauss() ) ) <= 0. ) {}
    // cubic normal variate
    v = v*v*v;
    // squeeze step
    if ( (u = generator.randUnif()) < 1.-(x*x)*(x*x)/(108. * d) ) break;
    // rejection step
    if ( std::log(double(u)) < 0.5*x*x+d*(1.-v+log(v)) ) break;
  }
  return (b*d*v);
}

References STK::Law::Exponential::rand(), rand(), and STKDOMAIN_ERROR_2ARG.

◆ scale()

Real const & STK::Law::Gamma::scale ( ) const

inline

Returns: scale

Definition at line 90 of file STK_Law_Gamma.h.

90{ return b_;}

References b_.

Referenced by setScale().

◆ setScale()

void STK::Law::Gamma::setScale ( Real const & scale )

inline

Parameters

scale the scale parameter

Definition at line 101 of file STK_Law_Gamma.h.

    {
      if (scale<=0) STKDOMAIN_ERROR_1ARG(Gamma::setScale,scale,scale must be > 0);
      b_ = scale;
    }

References b_, scale(), setScale(), and STKDOMAIN_ERROR_1ARG.

Referenced by setScale().

◆ setShape()

void STK::Law::Gamma::setShape ( Real const & shape )

inline

Parameters

shape the shape parameter

Definition at line 92 of file STK_Law_Gamma.h.

    {
      if (shape<=0) STKDOMAIN_ERROR_1ARG(Gamma::setShape,shape,shape must be > 0);
      a_ = shape;
#ifndef IS_RTKPP_LIB
      computeCtes();
#endif
    }

References a_, computeCtes(), setShape(), shape(), and STKDOMAIN_ERROR_1ARG.

Referenced by setShape().

◆ shape()

Real const & STK::Law::Gamma::shape ( ) const

inline

Returns: shape

Definition at line 88 of file STK_Law_Gamma.h.

88{ return a_;}

References a_.

Referenced by setShape().

Member Data Documentation

◆ a_

Real STK::Law::Gamma::a_

protected

The shape parameter.

Definition at line 178 of file STK_Law_Gamma.h.

Referenced by cdf(), computeCtes(), Gamma(), lpdf(), pdf(), rand(), setShape(), and shape().

◆ b_

Real STK::Law::Gamma::b_

protected

The scale parameter.

Definition at line 180 of file STK_Law_Gamma.h.

Referenced by cdf(), Gamma(), lpdf(), pdf(), rand(), scale(), and setScale().

◆ c_

Real STK::Law::Gamma::c_

mutableprivate

First and second constants for rand.

Definition at line 185 of file STK_Law_Gamma.h.

Referenced by computeCtes(), and rand().

◆ d_

Real STK::Law::Gamma::d_

private

Definition at line 185 of file STK_Law_Gamma.h.

Referenced by computeCtes(), and rand().

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Base

Constructor & Destructor Documentation

◆ Gamma()

◆ ~Gamma()

Member Function Documentation

◆ cdf() [1/2]

◆ cdf() [2/2]

◆ computeCtes()

◆ icdf() [1/2]

◆ icdf() [2/2]

◆ lpdf() [1/2]

◆ lpdf() [2/2]

◆ pdf() [1/2]

◆ pdf() [2/2]

◆ rand() [1/2]

◆ rand() [2/2]

◆ scale()

◆ setScale()

◆ setShape()

◆ shape()

Member Data Documentation

◆ a_

◆ b_

◆ c_

◆ d_