#include <STK_Law_Normal.h>

Inheritance diagram for STK::Law::Normal:

Public Types
typedef IUnivLaw< Real >	Base

Public Member Functions
	Normal (Real const &mu=0., Real const &sigma=1.)
	Constructor.

virtual	~Normal ()
	Destructor.

Real const &	mu () const

Real const &	sigma () const

void	setMu (Real const &mu)

void	setSigma (Real const &sigma)

Real	rand () const
	Generate a pseudo Normal random variate.

virtual Real	pdf (Real const &x) const

virtual Real	lpdf (Real const &x) const

virtual Real	cdf (Real const &t) const
	Compute the cumulative distribution function at t of the standard normal distribution.

virtual Real	icdf (Real const &p) const
	Compute the inverse cumulative distribution function at p of the standard normal distribution.

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 &mu, Real const &sigma)
	Generate a pseudo Normal random variate.

static Real	pdf (Real const &x, Real const &mu, Real const &sigma)

static Real	lpdf (Real const &x, Real const &mu, Real const &sigma)

static Real	cdf (Real const &t, Real const &mu, Real const &sigma)
	Compute the cumulative distribution function at t of the standard normal distribution.

static Real	icdf (Real const &p, Real const &mu, Real const &sigma)
	Compute the inverse cumulative distribution function at p of the standard normal distribution.

Protected Attributes
Real	mu_
	The mu parameter.

Real	sigma_
	The sigma parameter.

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

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

Normal distribution law.

In probability theory, the normal (or Gaussian) distribution is a very commonly occurring continuous probability distribution. Normal distributions are extremely important in statistics and are often used in the natural and social sciences for real-valued random variables whose distributions are not known.

The normal distribution is immensely useful because of the central limit theorem, which states that, under mild conditions, the mean of many random variables independently drawn from the same distribution is distributed approximately normally, irrespective of the form of the original distribution.

The probability density of normal distribution is:

$f(x;\mu,\sigma) = \frac{1}{\sigma\sqrt{2\pi}} \exp\left(-\frac{\left(x-\mu\right)^2}{2\sigma^2} \right)$

where $\mu \mbox{ and } \sigma$ are the mean and the standard deviation.

Definition at line 71 of file STK_Law_Normal.h.

Member Typedef Documentation

◆ Base

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

Definition at line 74 of file STK_Law_Normal.h.

Constructor & Destructor Documentation

◆ Normal()

STK::Law::Normal::Normal	(	Real const &	mu = `0.`,
		Real const &	sigma = `1.`
	)

inline

Constructor.

Parameters

mu	mean of the Normal distribution
sigma	standard deviation of the Normal distribution

Definition at line 79 of file STK_Law_Normal.h.

         : Base(String(_T("Normal")))
          , mu_(mu), sigma_(sigma)
    {
      if (!Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(sigma) || sigma < 0)
      { STKDOMAIN_ERROR_2ARG(Normal::Normal,mu,sigma,invalid argument);}
    }

References mu(), Normal(), sigma(), and STKDOMAIN_ERROR_2ARG.

Referenced by Normal().

◆ ~Normal()

virtual STK::Law::Normal::~Normal ( )

inlinevirtual

Destructor.

Definition at line 87 of file STK_Law_Normal.h.

87{}

Member Function Documentation

◆ cdf() [1/2]

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

virtual

Compute the cumulative distribution function at t of the standard normal distribution.

Author: W. J. Cody

See also: http://www.netlib.org/specfun/erf

This is the erfc() routine only, adapted by the transform cdf(u)=erfc(-u/sqrt(2))/2

Parameters

t	a real value

Returns: the cumulative distribution function value at t

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

Definition at line 115 of file STK_Law_Normal.cpp.

{
  // check parameter
  if (!Arithmetic<Real>::isFinite(t))
    STKDOMAIN_ERROR_1ARG(Normal::cdf,t,invalid argument);
  // trivial case
  if (sigma_ == 0) return (t < mu_) ? 0. : 1.;
  // change of variable
  return (0.5*Funct::erfc_raw(-((t - mu_) / sigma_)*Const::_1_SQRT2_));
}

References cdf(), STK::Funct::erfc_raw(), mu_, sigma_, and STKDOMAIN_ERROR_1ARG.

Referenced by cdf(), cdf(), and main().

◆ cdf() [2/2]

Real STK::Law::Normal::cdf	(	Real const &	t,
		Real const &	mu,
		Real const &	sigma
	)

static

Compute the cumulative distribution function at t of the standard normal distribution.

Parameters

t	a real value
mu,sigma	mean and standard deviation of the Normal distribution

Returns: the cumulative distribution function value at t

Definition at line 227 of file STK_Law_Normal.cpp.

{
  // check parameter
  if (!Arithmetic<Real>::isFinite(t))
    STKDOMAIN_ERROR_1ARG(Normal::cdf,t,invalid argument);
  // trivial case
  if (sigma == 0) return (t < mu) ? 0. : 1.;
  // change of variable
  return (0.5*Funct::erfc_raw(-((t - mu) / sigma)*Const::_1_SQRT2_));
}

References cdf(), STK::Funct::erfc_raw(), mu(), sigma(), and STKDOMAIN_ERROR_1ARG.

◆ icdf() [1/2]

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

virtual

Compute the inverse cumulative distribution function at p of the standard normal distribution.

Author: Peter J. Acklam pjack.nosp@m.lam@.nosp@m.onlin.nosp@m.e.no

See also: http://home.online.no/~pjacklam/notes/invnorm/index.html

This function is based on the MATLAB code from the address above.

Parameters

p	a probability number.

Returns: the inverse cumulative distribution function value at p.

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

Definition at line 127 of file STK_Law_Normal.cpp.

{
  // check parameter
  if ( (!Arithmetic<Real>::isFinite(p)) || (p > 1.) || (p < 0.) )
    STKDOMAIN_ERROR_1ARG(Normal::icdf,p,invalid argument);
 // trivial cases
 if (p == 0.)  return -Arithmetic<Real>::infinity();
 if (p == 1.)  return  Arithmetic<Real>::infinity();
 if (p == 0.5) return  mu_;
 
 double p_low =  0.02425, p_high = 1 - p_low;
 double x = 0.0;
 //Rational approximation for lower region.
 if ( p < p_low)
 {
   double q = sqrt(-2*log(p));
   x = (((((c1*q+c2)*q+c3)*q+c4)*q+c5)*q+c6) / ((((d1*q+d2)*q+d3)*q+d4)*q+1);
 }
 //Rational approximation for central region.
 if (p_low <= p && p <= p_high)
 {
   double r = (p-0.5)*(p-0.5);
   x = (((((a1*r+a2)*r+a3)*r+a4)*r+a5)*r+a6)*(p-0.5)/(((((b1*r+b2)*r+b3)*r+b4)*r+b5)*r+1);
 }
 //Rational approximation for upper region.
 if (p_high < p )
 {
   double q = sqrt(-2*log(1-p));
   x = -(((((c1*q+c2)*q+c3)*q+c4)*q+c5)*q+c6) / ((((d1*q+d2)*q+d3)*q+d4)*q+1);
 }
 
 /* The relative error of the approximation has absolute value less
    than 1.15e-9.  One iteration of Halley's rational method (third
    order) gives full machine precision... */
// if(( 0 < p)&&(p < 1))
// {
//     double e = cdf(u) - p;
//     double u = e * Const::_SQRT2PI_ * exp(x*x/2);
//     x = x - u/(1 + x*u/2);
// }
 return  mu_ + sigma_ * x;
}

References a1, a2, a3, a4, a5, a6, b1, b2, b3, b4, b5, c1, c2, c3, c4, c5, c6, d1, d2, d3, d4, icdf(), mu_, sigma_, and STKDOMAIN_ERROR_1ARG.

Referenced by icdf(), icdf(), and main().

◆ icdf() [2/2]

Real STK::Law::Normal::icdf	(	Real const &	p,
		Real const &	mu,
		Real const &	sigma
	)

static

Compute the inverse cumulative distribution function at p of the standard normal distribution.

Parameters

p	a probability number.
mu,sigma	mean and standard deviation of the Normal distribution

Returns: the inverse cumulative distribution function value at p.

Definition at line 239 of file STK_Law_Normal.cpp.

{
  // check parameter
  if ( (!Arithmetic<Real>::isFinite(p)) || (p > 1.) || (p < 0.) )
    STKDOMAIN_ERROR_1ARG(Normal::icdf,p,invalid argument);
 // trivial cases
 if (p == 0.)  return -Arithmetic<Real>::infinity();
 if (p == 1.)  return  Arithmetic<Real>::infinity();
 if (p == 0.5) return  mu;
 
  double p_low =  0.02425, p_high = 1 - p_low;
  double x = 0.0;
  //Rational approximation for lower region.
  if ( p < p_low)
  {
    double q = sqrt(-2*log(p));
    x = (((((c1*q+c2)*q+c3)*q+c4)*q+c5)*q+c6) / ((((d1*q+d2)*q+d3)*q+d4)*q+1);
  }
  //Rational approximation for central region.
  if (p_low <= p && p <= p_high)
  {
    double r = (p-0.5)*(p-0.5);
    x = (((((a1*r+a2)*r+a3)*r+a4)*r+a5)*r+a6)*(p-0.5) / (((((b1*r+b2)*r+b3)*r+b4)*r+b5)*r+1);
  }
  //Rational approximation for upper region.
  if (p_high < p )
  {
    double q = sqrt(-2*log(1-p));
    x = -(((((c1*q+c2)*q+c3)*q+c4)*q+c5)*q+c6) / ((((d1*q+d2)*q+d3)*q+d4)*q+1);
  }
 
  /* The relative error of the approximation has absolute value less
     than 1.15e-9.  One iteration of Halley's rational method (third
     order) gives full machine precision... */
  //Pseudo-code algorithm for refinement
  // if(( 0 < p)&&(p < 1))
  // {
  //     double e = cdf(u) - p;
  //     double u = e * Const::_SQRT2PI_ * exp(x*x/2);
  //     x = x - u/(1 + x*u/2);
  // }
  return  mu + sigma * x;
}

References a1, a2, a3, a4, a5, a6, b1, b2, b3, b4, b5, c1, c2, c3, c4, c5, c6, d1, d2, d3, d4, icdf(), mu(), sigma(), and STKDOMAIN_ERROR_1ARG.

◆ lpdf() [1/2]

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

virtual

Returns: Give the value of the log-pdf at x.

Parameters

x	a real value

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

Definition at line 99 of file STK_Law_Normal.cpp.

{
  // check parameter
  if ( !Arithmetic<Real>::isFinite(x))
    STKDOMAIN_ERROR_1ARG(Normal::lpdf,x,invalid argument);
  // trivial case
  if (sigma_ == 0)
    return (x==mu_) ? 0. : -Arithmetic<Real>::infinity();
  // compute lpdf
  const Real y = (x - mu_)/sigma_;
  return -(Const::_LNSQRT2PI_ + std::log(double(sigma_)) + 0.5 * y * y);
}

References lpdf(), mu_, sigma_, and STKDOMAIN_ERROR_1ARG.

Referenced by STK::JointGaussianModel< Array, WColVector >::computeLnLikelihood(), STK::ModelDiagGaussian_muj_sj< Data_, WColVector_ >::computeLnLikelihood(), STK::DiagGaussianBase< Derived >::lnComponentProbability(), STK::HDGaussian_AjkBkQkD< Array >::lnComponentProbability(), lpdf(), lpdf(), and main().

◆ lpdf() [2/2]

Real STK::Law::Normal::lpdf	(	Real const &	x,
		Real const &	mu,
		Real const &	sigma
	)

static

Returns: Give the value of the log-pdf at x.

Parameters

x	a real value
mu,sigma	mean and standard deviation of the Normal distribution

Definition at line 206 of file STK_Law_Normal.cpp.

{
#ifdef STK_DEBUG
  // check parameters
  if ( !Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(sigma) || sigma < 0)
    STKDOMAIN_ERROR_2ARG(Normal::rand,mu,sigma,invalid argument);
#endif
  // check parameter
  if ( !Arithmetic<Real>::isFinite(x))
    STKDOMAIN_ERROR_1ARG(Normal::lpdf,x,invalid argument);
  // trivial case
  if (sigma == 0)
    return (x==mu) ? 0. : -Arithmetic<Real>::infinity();
  // compute lpdf
  const Real y = (x - mu)/sigma;
  return -(Const::_LNSQRT2PI_ + std::log(double(sigma)) + 0.5 * y * y);
}

References lpdf(), mu(), rand(), sigma(), STKDOMAIN_ERROR_1ARG, and STKDOMAIN_ERROR_2ARG.

◆ mu()

Real const & STK::Law::Normal::mu ( ) const

inline

Returns: the mean

Definition at line 89 of file STK_Law_Normal.h.

89{ return mu_;}

References mu_.

Referenced by cdf(), icdf(), lpdf(), Normal(), pdf(), rand(), and setMu().

◆ pdf() [1/2]

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

virtual

Parameters

x	a real value

Returns: the value of the normal pdf at x

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

Definition at line 84 of file STK_Law_Normal.cpp.

{
  // check parameter
  if ( !Arithmetic<Real>::isFinite(x))
    STKDOMAIN_ERROR_1ARG(Normal::pdf,x,invalid argument);
  // trivial case
  if (sigma_ == 0.) return (x==mu_) ? 1. : 0.;
  // compute pdf
  const Real y = (x - mu_)/sigma_;
  return Const::_1_SQRT2PI_ * std::exp(-0.5 * y * y)  / sigma_;
}

References mu_, pdf(), sigma_, and STKDOMAIN_ERROR_1ARG.

Referenced by main(), pdf(), and pdf().

◆ pdf() [2/2]

Real STK::Law::Normal::pdf	(	Real const &	x,
		Real const &	mu,
		Real const &	sigma
	)

static

Parameters

x	a real value
mu,sigma	mean and standard deviation of the Normal distribution

Returns: the value of the normal pdf at x

Definition at line 187 of file STK_Law_Normal.cpp.

{
#ifdef STK_DEBUG
  // check parameters
  if ( !Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(sigma) || sigma < 0)
    STKDOMAIN_ERROR_2ARG(Normal::rand,mu,sigma,invalid argument);
#endif
  // check parameter
  if ( !Arithmetic<Real>::isFinite(x))
    STKDOMAIN_ERROR_1ARG(Normal::pdf,x,invalid argument);
  // trivial case
  if (sigma == 0.) return (x==mu) ? 1. : 0.;
  // compute pdf
  const Real y = (x - mu)/sigma;
  return Const::_1_SQRT2PI_ * std::exp(-0.5 * y * y)  / sigma;
}

References mu(), pdf(), rand(), sigma(), STKDOMAIN_ERROR_1ARG, and STKDOMAIN_ERROR_2ARG.

◆ rand() [1/2]

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

virtual

Generate a pseudo Normal random variate.

Generate a pseudo Normal random variate with location parameter mu_ and standard deviation sigma_.

Returns: a pseudo normal random variate

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

Definition at line 78 of file STK_Law_Normal.cpp.

79{ return (sigma_ == 0.) ? mu_ : generator.randGauss(mu_, sigma_);}

References mu_, and sigma_.

Referenced by lpdf(), main(), pdf(), STK::DiagGaussianBase< Derived >::rand(), STK::HDGaussianBase< Derived >::rand(), rand(), and STK::HDMatrixGaussianModel< IdRow_, IdCol_, Array_ >::randomInit().

◆ rand() [2/2]

Real STK::Law::Normal::rand	(	Real const &	mu,
		Real const &	sigma
	)

static

Generate a pseudo Normal random variate.

Generate a pseudo Normal random variate with location mu and standard deviation sigma parameters.

Parameters

mu,sigma mean and standard deviation of the Normal distribution

Returns: a pseudo normal random variate, centered in mu and with standard deviation sigma

Definition at line 173 of file STK_Law_Normal.cpp.

{
#ifdef STK_DEBUG
  // check parameters
  if ( !Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(sigma) || sigma < 0)
    STKDOMAIN_ERROR_2ARG(Normal::rand,mu,sigma,invalid argument);
#endif
  // return variate
  return (sigma == 0.) ? mu : generator.randGauss(mu, sigma);
}

References mu(), rand(), sigma(), and STKDOMAIN_ERROR_2ARG.

◆ setMu()

void STK::Law::Normal::setMu ( Real const & mu )

inline

Parameters

mu	the mean to set

Definition at line 93 of file STK_Law_Normal.h.

93{ mu_ = mu;}

References mu(), and mu_.

◆ setSigma()

void STK::Law::Normal::setSigma ( Real const & sigma )

inline

Parameters

sigma the standard deviation to set

Definition at line 95 of file STK_Law_Normal.h.

    {
      if (sigma<0) STKDOMAIN_ERROR_1ARG(Normal::setSigma,sigma,sigma must be >= 0);
       sigma_ = sigma;
    }

References setSigma(), sigma(), sigma_, and STKDOMAIN_ERROR_1ARG.

Referenced by setSigma().

◆ sigma()

Real const & STK::Law::Normal::sigma ( ) const

inline

Returns: the standard deviation

Definition at line 91 of file STK_Law_Normal.h.

91{ return sigma_;}

References sigma_.

Referenced by cdf(), icdf(), lpdf(), Normal(), pdf(), rand(), and setSigma().

Member Data Documentation

◆ mu_

Real STK::Law::Normal::mu_

protected

The mu parameter.

Definition at line 185 of file STK_Law_Normal.h.

Referenced by cdf(), icdf(), lpdf(), mu(), pdf(), rand(), and setMu().

◆ sigma_

Real STK::Law::Normal::sigma_

protected

The sigma parameter.

Definition at line 187 of file STK_Law_Normal.h.

Referenced by cdf(), icdf(), lpdf(), pdf(), rand(), setSigma(), and sigma().

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Base

Constructor & Destructor Documentation

◆ Normal()

◆ ~Normal()

Member Function Documentation

◆ cdf() [1/2]

◆ cdf() [2/2]

◆ icdf() [1/2]

◆ icdf() [2/2]

◆ lpdf() [1/2]

◆ lpdf() [2/2]

◆ mu()

◆ pdf() [1/2]

◆ pdf() [2/2]

◆ rand() [1/2]

◆ rand() [2/2]

◆ setMu()

◆ setSigma()

◆ sigma()

Member Data Documentation

◆ mu_

◆ sigma_