STK++ 0.9.13
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
STK::Law::Cauchy Class Reference
STatistiK (Statistical tools). » The probabilities laws sub-project.

Cauchy distribution law. More...

#include <STK_Law_Cauchy.h>

Inheritance diagram for STK::Law::Cauchy:
Inheritance graph

Public Types

typedef IUnivLaw< Real > Base
 

Public Member Functions

 Cauchy (Real const &mu=0, Real const &scale=1)
 Default constructor.
 
virtual ~Cauchy ()
 Destructor.
 
Real const & mu () const
 
Real const & scale () const
 
void setMu (Real const &mu)
 
void setScale (Real const &scale)
 
virtual Real rand () const
 Generate a pseudo Cauchy random variate.
 
virtual Real pdf (Real const &x) const
 
virtual Real lpdf (Real const &x) const
 
virtual Real cdf (Real const &t) const
 The cumulative distribution function of the Cauchy distribution at t is.
 
virtual Real icdf (Real const &p) const
 The inverse cumulative distribution function at p is.
 
- 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 &scale)
 Generate a pseudo Cauchy random variate with the specified parameters.
 
static Real pdf (Real const &x, Real const &mu, Real const &scale)
 
static Real lpdf (Real const &x, Real const &mu, Real const &scale)
 
static Real cdf (Real const &t, Real const &mu, Real const &scale)
 The cumulative distribution function of the Cauchy distribution at t is.
 
static Real icdf (Real const &p, Real const &mu, Real const &scale)
 The inverse cumulative distribution function at p is.
 

Protected Attributes

Real mu_
 The mu parameter.
 
Real scale_
 The scale 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

Cauchy distribution law.

The Cauchy distribution, named after Augustin Cauchy, is a continuous probability distribution. The Cauchy distribution has the probability density function

\[ f(x; \mu,\gamma) = \frac{1}{\pi\gamma \left[1 + \left(\frac{x - \mu}{\gamma}\right)^2\right]} = \frac{ 1}{\pi \gamma }\left[ \frac{\gamma^2}{(x - \mu)^2 + \gamma^2} \right]. \]

where $ \mu $ is the location parameter, specifying the location of the peak of the distribution, and $ \gamma>0 $ is the scale parameter.

The simplest Cauchy distribution is called the standard Cauchy distribution. It is the distribution of a random variable that is the ratio of two independent standard normal variables and has the probability density function $ f(x;0,1) $.

Definition at line 65 of file STK_Law_Cauchy.h.

Member Typedef Documentation

◆ Base

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

Definition at line 68 of file STK_Law_Cauchy.h.

Constructor & Destructor Documentation

◆ Cauchy()

STK::Law::Cauchy::Cauchy ( Real const &  mu = 0,
Real const &  scale = 1 
)
inline

Default constructor.

Parameters
mu,scalelocation and scale of the Cauchy distribution

Definition at line 72 of file STK_Law_Cauchy.h.

73 : Base(String(_T("Cauchy")))
74 , mu_(mu)
75 , scale_(scale)
76 {
77 // check parameters
78 if ( !Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(scale) || scale <= 0)
79 STKDOMAIN_ERROR_2ARG(Cauchy::Cauchy,mu, scale,argument error);
80 }
STKDOMAIN_ERROR_2ARG
#define STKDOMAIN_ERROR_2ARG(Where, Arg1, Arg2, Error)
Definition STK_Macros.h:147
_T
#define _T(x)
Let x unmodified.
Definition STK_Typedefs.h:71
STK::Law::Cauchy::Base
IUnivLaw< Real > Base
Definition STK_Law_Cauchy.h:68
STK::Law::Cauchy::Cauchy
Cauchy(Real const &mu=0, Real const &scale=1)
Default constructor.
Definition STK_Law_Cauchy.h:72
STK::Law::Cauchy::scale_
Real scale_
The scale parameter.
Definition STK_Law_Cauchy.h:183
STK::Law::Cauchy::scale
Real const & scale() const
Definition STK_Law_Cauchy.h:87
STK::Law::Cauchy::mu
Real const & mu() const
Definition STK_Law_Cauchy.h:85
STK::Law::Cauchy::mu_
Real mu_
The mu parameter.
Definition STK_Law_Cauchy.h:181
STK::String
std::basic_string< Char > String
STK fundamental type of a String.
Definition STK_Typedefs.h:89
STK::Arithmetic::isFinite
static bool isFinite(Type const &x)
Definition STK_Arithmetic.h:208

References Cauchy(), mu(), scale(), and STKDOMAIN_ERROR_2ARG.

Referenced by Cauchy(), and rand().

◆ ~Cauchy()

virtual STK::Law::Cauchy::~Cauchy ( )
inlinevirtual

Destructor.

Definition at line 83 of file STK_Law_Cauchy.h.

83{}

Member Function Documentation

◆ cdf() [1/2]

Real STK::Law::Cauchy::cdf ( Real const &  t) const
virtual

The cumulative distribution function of the Cauchy distribution at t is.

\[ F(t; \mu,\gamma)= \frac{1}{\pi} \arctan\left(\frac{t-\mu}{\gamma}\right)+\frac{1}{2} \]

See also
http://www.faqs.org/faqs/fr/maths/maths-faq-3/ for the computation of arctan.
Parameters
ta real value
Returns
the cdf of the Cauchy distribution at t

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

Definition at line 131 of file STK_Law_Cauchy.cpp.

132{
133 // check NA value
134 if (isNA(t)) return Arithmetic<Real>::NA();
135 // check parameter
136 if (Arithmetic<Real>::isInfinite(t))
137 return (t < 0.) ? 0.0 : 1.0;
138
139 /* http://www.faqs.org/faqs/fr/maths/maths-faq-3/
140 * arctan on [0, 1[:
141 * if x<0 atan(x)= -atan(-x)
142 * elseif x>1 atan(x)= Pi/2-atan(1/x).
143 */
144 Real td = (t - mu_)/scale_;
145 if (std::abs(td) > 1)
146 {
147 Real y = Real(std::atan( 1./double(td))) / Const::_PI_;
148 return (td > 0) ? (1. - y) : (-y);
149 }
150 return 0.5 + Real(std::atan( double(td))) / Const::_PI_;
151}
STK::isNA
bool isNA(Type const &x)
utility method allowing to know if a value is a NA (Not Available) value
Definition STK_Arithmetic.h:214
STK::Real
double Real
STK fundamental type of Real values.
Definition STK_Typedefs.h:118
STK::Arithmetic::isInfinite
static bool isInfinite(Type const &x)
Definition STK_Arithmetic.h:203
STK::Arithmetic::NA
static Type NA()
Adding a Non Available (NA) special number.
Definition STK_Arithmetic.h:194

References STK::isNA(), mu_, STK::Arithmetic< Type >::NA(), and scale_.

◆ cdf() [2/2]

Real STK::Law::Cauchy::cdf ( Real const &  t,
Real const &  mu,
Real const &  scale 
)
static

The cumulative distribution function of the Cauchy distribution at t is.

\[ F(t; \mu,\gamma)= \frac{1}{\pi} \arctan\left(\frac{t-\mu}{\gamma}\right)+\frac{1}{2} \]

See also
http://www.faqs.org/faqs/fr/maths/maths-faq-3/ for the computation of arctan.
Parameters
ta real value
mu,scalelocation and scale of the Cauchy distribution
Returns
the cdf of the Cauchy distribution at t

Definition at line 174 of file STK_Law_Cauchy.cpp.

175{
176 // check NA value
177 if (isNA(t)) return Arithmetic<Real>::NA();
178 // check parameter
179 if (Arithmetic<Real>::isInfinite(t))
180 return (t < 0.) ? 0.0 : 1.0;
181
182 /* http://www.faqs.org/faqs/fr/maths/maths-faq-3/
183 * arctan on [0, 1[:
184 * if x<0 atan(x)= -atan(-x)
185 * elseif x>1 atan(x)= Pi/2-atan(1/x).
186 */
187 Real td = (t - mu)/scale;
188 if (std::abs(td) > 1)
189 {
190 Real y = Real(std::atan( 1./double(td))) / Const::_PI_;
191 return (td > 0) ? (1. - y) : (-y);
192 }
193 return 0.5 + Real(std::atan( double(td))) / Const::_PI_;
194}

References STK::isNA(), mu(), STK::Arithmetic< Type >::NA(), and scale().

◆ icdf() [1/2]

Real STK::Law::Cauchy::icdf ( Real const &  p) const
virtual

The inverse cumulative distribution function at p is.

\[ F^{-1}(p; \mu,\gamma) = \mu + \gamma \tan(\pi (p-1/2)). \]

Parameters
pa probability number
Returns
the inverse cdf of the Cauchy distribution at p

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

Definition at line 156 of file STK_Law_Cauchy.cpp.

157{
158 // check NA value
159 if (isNA(p)) return Arithmetic<Real>::NA();
160 // check parameter
161 if ((p > 1.) || (p < 0.))
162 STKDOMAIN_ERROR_1ARG(Cauchy::icdf,p,p must be a probability);
163 // trivial cases
164 if (p == 0.) return -Arithmetic<Real>::infinity();
165 if (p == 1.) return Arithmetic<Real>::infinity();
166
167 // general case
168 // tan(pi * (p - 1/2)) = -cot(pi * p) = -1/tan(pi * p)
169 return mu_ - scale_ / Real(std::tan( double(Const::_PI_ * p) ));
170}
STKDOMAIN_ERROR_1ARG
#define STKDOMAIN_ERROR_1ARG(Where, Arg, Error)
Definition STK_Macros.h:165
STK::Law::Cauchy::icdf
virtual Real icdf(Real const &p) const
The inverse cumulative distribution function at p is.
Definition STK_Law_Cauchy.cpp:156

References icdf(), STK::isNA(), mu_, STK::Arithmetic< Type >::NA(), scale_, and STKDOMAIN_ERROR_1ARG.

Referenced by icdf(), and icdf().

◆ icdf() [2/2]

Real STK::Law::Cauchy::icdf ( Real const &  p,
Real const &  mu,
Real const &  scale 
)
static

The inverse cumulative distribution function at p is.

\[ F^{-1}(p; \mu,\gamma) = \mu + \gamma \tan(\pi (p-1/2)). \]

Parameters
pa probability number
mu,scalelocation and scale of the Cauchy distribution
Returns
the inverse cdf of the Cauchy distribution at p

Definition at line 199 of file STK_Law_Cauchy.cpp.

200{
201 // check NA value
202 if (isNA(p)) return Arithmetic<Real>::NA();
203 // check parameter
204 if ((p > 1.) || (p < 0.))
205 STKDOMAIN_ERROR_1ARG(Cauchy::icdf,p,p must be a probability);
206 // trivial cases
207 if (p == 0.) return -Arithmetic<Real>::infinity();
208 if (p == 1.) return Arithmetic<Real>::infinity();
209
210 // general case
211 // tan(pi * (p - 1/2)) = -cot(pi * p) = -1/tan(pi * p)
212 return mu - scale / Real(std::tan( double(Const::_PI_ * p) ));
213}

References icdf(), STK::isNA(), mu(), STK::Arithmetic< Type >::NA(), scale(), and STKDOMAIN_ERROR_1ARG.

◆ lpdf() [1/2]

Real STK::Law::Cauchy::lpdf ( Real const &  x) const
virtual
Parameters
xa real value
Returns
the log-pdf of the cauchy distribution at x

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

Definition at line 98 of file STK_Law_Cauchy.cpp.

99{
100 // check NA value
101 if (isNA(x)) return Arithmetic<Real>::NA();
102 // trivial case
103 if (Arithmetic<Real>::isInfinite(x)) return -Arithmetic<Real>::infinity();
104
105 // general case
106 Real y = (x - mu_) / scale_;
107 return -Real(std::log( double(Const::_PI_ * scale_ * (1. + y * y)) ));
108}

References STK::isNA(), mu_, STK::Arithmetic< Type >::NA(), and scale_.

Referenced by lpdf().

◆ lpdf() [2/2]

Real STK::Law::Cauchy::lpdf ( Real const &  x,
Real const &  mu,
Real const &  scale 
)
static
Parameters
xa real value
mumu of the Cauchy distribution
scalescale of the Cauchy distribution
Returns
the log-pdf of the cauchy distribution at x

Definition at line 111 of file STK_Law_Cauchy.cpp.

112{
113#ifdef STK_DEBUG
114 // check parameters
115 if ( !Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(scale) || scale <= 0)
116 STKDOMAIN_ERROR_2ARG(Cauchy::lpdf,mu, scale,argument error);
117#endif
118 // check NA value
119 if (isNA(x)) return Arithmetic<Real>::NA();
120 // trivial case
121 if (Arithmetic<Real>::isInfinite(x))
122 return -Arithmetic<Real>::infinity();
123
124 // general case
125 Real y = (x - mu) / scale;
126 return - Real(std::log( double(Const::_PI_ * scale * (1. + y * y)) ));
127}
STK::Law::Cauchy::lpdf
virtual Real lpdf(Real const &x) const
Definition STK_Law_Cauchy.cpp:98

References STK::isNA(), lpdf(), mu(), STK::Arithmetic< Type >::NA(), scale(), and STKDOMAIN_ERROR_2ARG.

◆ mu()

Real const & STK::Law::Cauchy::mu ( ) const
inline
Returns
the mu parameter

Definition at line 85 of file STK_Law_Cauchy.h.

85{ return mu_;}

References mu_.

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

◆ pdf() [1/2]

Real STK::Law::Cauchy::pdf ( Real const &  x) const
virtual
Parameters
xa real value
Returns
the pdf of the cauchy distribution at x

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

Definition at line 67 of file STK_Law_Cauchy.cpp.

68{
69 // check NA value
70 if (isNA(x)) return Arithmetic<Real>::NA();
71 // trivial case
72 if (Arithmetic<Real>::isInfinite(x)) return 0.0;
73
74 // general case
75 Real y = (x - mu_) / scale_;
76 return 1. / (Const::_PI_ * scale_ * (1. + y * y));
77}

References STK::isNA(), mu_, STK::Arithmetic< Type >::NA(), and scale_.

Referenced by pdf().

◆ pdf() [2/2]

Real STK::Law::Cauchy::pdf ( Real const &  x,
Real const &  mu,
Real const &  scale 
)
static
Parameters
xa real value
mu,scalelocation and scale of the Cauchy distribution
Returns
the pdf of the cauchy distribution at x

Definition at line 80 of file STK_Law_Cauchy.cpp.

81{
82#ifdef STK_DEBUG
83 // check parameters
84 if ( !Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(scale) || scale <= 0)
85 STKDOMAIN_ERROR_2ARG(Cauchy::pdf,mu, scale,argument error);
86#endif
87 // check NA value
88 if (isNA(x)) return Arithmetic<Real>::NA();
89 // trivial case
90 if (Arithmetic<Real>::isInfinite(x)) return 0.0;
91
92 // general case
93 Real y = (x - mu) / scale;
94 return 1. / (Const::_PI_ * scale * (1. + y * y));
95}
STK::Law::Cauchy::pdf
virtual Real pdf(Real const &x) const
Definition STK_Law_Cauchy.cpp:67

References STK::isNA(), mu(), STK::Arithmetic< Type >::NA(), pdf(), scale(), and STKDOMAIN_ERROR_2ARG.

◆ rand() [1/2]

Real STK::Law::Cauchy::rand ( ) const
virtual

Generate a pseudo Cauchy random variate.

Returns
a cauchy random variable

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

Definition at line 49 of file STK_Law_Cauchy.cpp.

50{ return mu_ + scale_ * Real(std::tan( double(Const::_PI_ * generator.randUnif())));}

References mu_, and scale_.

◆ rand() [2/2]

Real STK::Law::Cauchy::rand ( Real const &  mu,
Real const &  scale 
)
static

Generate a pseudo Cauchy random variate with the specified parameters.

Parameters
mu,scalelocation and scale of the Cauchy distribution
Returns
a cauchy random variable

Definition at line 56 of file STK_Law_Cauchy.cpp.

57{
58#ifdef STK_DEBUG
59 // check parameters
60 if ( !Arithmetic<Real>::isFinite(mu) || !Arithmetic<Real>::isFinite(scale) || scale <= 0)
61 STKDOMAIN_ERROR_2ARG(Cauchy::Cauchy,mu, scale,argument error);
62#endif
63 return mu + scale * Real(std::tan( double(Const::_PI_ * generator.randUnif()) ));
64}

References Cauchy(), mu(), scale(), and STKDOMAIN_ERROR_2ARG.

◆ scale()

Real const & STK::Law::Cauchy::scale ( ) const
inline
Returns
the scale parameter

Definition at line 87 of file STK_Law_Cauchy.h.

87{ return scale_;}

References scale_.

Referenced by Cauchy(), cdf(), icdf(), lpdf(), pdf(), rand(), and setScale().

◆ setMu()

void STK::Law::Cauchy::setMu ( Real const &  mu)
inline
Parameters
muthe mu parameter

Definition at line 89 of file STK_Law_Cauchy.h.

89{ mu_ = mu;}

References mu(), and mu_.

◆ setScale()

void STK::Law::Cauchy::setScale ( Real const &  scale)
inline
Parameters
scalethe scale parameter

Definition at line 91 of file STK_Law_Cauchy.h.

92 {
93 if (scale<0) STKRUNTIME_ERROR_1ARG(Cauchy::setScale,scale,scale must be >= 0);
94 scale_ = scale;
95 }
STKRUNTIME_ERROR_1ARG
#define STKRUNTIME_ERROR_1ARG(Where, Arg, Error)
Definition STK_Macros.h:129
STK::Law::Cauchy::setScale
void setScale(Real const &scale)
Definition STK_Law_Cauchy.h:91

References scale(), scale_, setScale(), and STKRUNTIME_ERROR_1ARG.

Referenced by setScale().

Member Data Documentation

◆ mu_

Real STK::Law::Cauchy::mu_
protected

The mu parameter.

Definition at line 181 of file STK_Law_Cauchy.h.

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

◆ scale_

Real STK::Law::Cauchy::scale_
protected

The scale parameter.

Definition at line 183 of file STK_Law_Cauchy.h.

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

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