math/distributions/cauchy.hpp

0001 // Copyright John Maddock 2006, 2007.
0002 // Copyright Paul A. Bristow 2007.
0003
0004 //  Use, modification and distribution are subject to the
0005 //  Boost Software License, Version 1.0. (See accompanying file
0006 //  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0007
0008 #ifndef BOOST_STATS_CAUCHY_HPP
0009 #define BOOST_STATS_CAUCHY_HPP
0010
0011 #ifdef _MSC_VER
0012 #pragma warning(push)
0013 #pragma warning(disable : 4127) // conditional expression is constant
0014 #endif
0015
0016 #include <boost/math/distributions/fwd.hpp>
0017 #include <boost/math/constants/constants.hpp>
0018 #include <boost/math/distributions/complement.hpp>
0019 #include <boost/math/distributions/detail/common_error_handling.hpp>
0020 #include <utility>
0021 #include <cmath>
0022
0023 namespace boost{ namespace math
0024 {
0025
0026 template <class RealType, class Policy>
0027 class cauchy_distribution;
0028
0029 namespace detail
0030 {
0031
0032 template <class RealType, class Policy>
0033 RealType cdf_imp(const cauchy_distribution<RealType, Policy>& dist, const RealType& x, bool complement)
0034 {
0035    //
0036    // This calculates the cdf of the Cauchy distribution and/or its complement.
0037    //
0038    // The usual formula for the Cauchy cdf is:
0039    //
0040    // cdf = 0.5 + atan(x)/pi
0041    //
0042    // But that suffers from cancellation error as x -> -INF.
0043    //
0044    // Recall that for x < 0:
0045    //
0046    // atan(x) = -pi/2 - atan(1/x)
0047    //
0048    // Substituting into the above we get:
0049    //
0050    // CDF = -atan(1/x)  ; x < 0
0051    //
0052    // So the procedure is to calculate the cdf for -fabs(x)
0053    // using the above formula, and then subtract from 1 when required
0054    // to get the result.
0055    //
0056    BOOST_MATH_STD_USING // for ADL of std functions
0057    static const char* function = "boost::math::cdf(cauchy<%1%>&, %1%)";
0058    RealType result = 0;
0059    RealType location = dist.location();
0060    RealType scale = dist.scale();
0061    if(false == detail::check_location(function, location, &result, Policy()))
0062    {
0063      return result;
0064    }
0065    if(false == detail::check_scale(function, scale, &result, Policy()))
0066    {
0067       return result;
0068    }
0069    if(std::numeric_limits<RealType>::has_infinity && x == std::numeric_limits<RealType>::infinity())
0070    { // cdf +infinity is unity.
0071      return static_cast<RealType>((complement) ? 0 : 1);
0072    }
0073    if(std::numeric_limits<RealType>::has_infinity && x == -std::numeric_limits<RealType>::infinity())
0074    { // cdf -infinity is zero.
0075      return static_cast<RealType>((complement) ? 1 : 0);
0076    }
0077    if(false == detail::check_x(function, x, &result, Policy()))
0078    { // Catches x == NaN
0079       return result;
0080    }
0081    RealType mx = -fabs((x - location) / scale); // scale is > 0
0082    if(mx > -tools::epsilon<RealType>() / 8)
0083    {  // special case first: x extremely close to location.
0084       return static_cast<RealType>(0.5f);
0085    }
0086    result = -atan(1 / mx) / constants::pi<RealType>();
0087    return (((x > location) != complement) ? 1 - result : result);
0088 } // cdf
0089
0090 template <class RealType, class Policy>
0091 RealType quantile_imp(
0092       const cauchy_distribution<RealType, Policy>& dist,
0093       const RealType& p,
0094       bool complement)
0095 {
0096    // This routine implements the quantile for the Cauchy distribution,
0097    // the value p may be the probability, or its complement if complement=true.
0098    //
0099    // The procedure first performs argument reduction on p to avoid error
0100    // when calculating the tangent, then calculates the distance from the
0101    // mid-point of the distribution.  This is either added or subtracted
0102    // from the location parameter depending on whether `complement` is true.
0103    //
0104    static const char* function = "boost::math::quantile(cauchy<%1%>&, %1%)";
0105    BOOST_MATH_STD_USING // for ADL of std functions
0106
0107    RealType result = 0;
0108    RealType location = dist.location();
0109    RealType scale = dist.scale();
0110    if(false == detail::check_location(function, location, &result, Policy()))
0111    {
0112      return result;
0113    }
0114    if(false == detail::check_scale(function, scale, &result, Policy()))
0115    {
0116       return result;
0117    }
0118    if(false == detail::check_probability(function, p, &result, Policy()))
0119    {
0120       return result;
0121    }
0122    // Special cases:
0123    if(p == 1)
0124    {
0125       return (complement ? -1 : 1) * policies::raise_overflow_error<RealType>(function, 0, Policy());
0126    }
0127    if(p == 0)
0128    {
0129       return (complement ? 1 : -1) * policies::raise_overflow_error<RealType>(function, 0, Policy());
0130    }
0131
0132    RealType P = p - floor(p);   // argument reduction of p:
0133    if(P > 0.5)
0134    {
0135       P = P - 1;
0136    }
0137    if(P == 0.5)   // special case:
0138    {
0139       return location;
0140    }
0141    result = -scale / tan(constants::pi<RealType>() * P);
0142    return complement ? RealType(location - result) : RealType(location + result);
0143 } // quantile
0144
0145 } // namespace detail
0146
0147 template <class RealType = double, class Policy = policies::policy<> >
0148 class cauchy_distribution
0149 {
0150 public:
0151    typedef RealType value_type;
0152    typedef Policy policy_type;
0153
0154    cauchy_distribution(RealType l_location = 0, RealType l_scale = 1)
0155       : m_a(l_location), m_hg(l_scale)
0156    {
0157     static const char* function = "boost::math::cauchy_distribution<%1%>::cauchy_distribution";
0158      RealType result;
0159      detail::check_location(function, l_location, &result, Policy());
0160      detail::check_scale(function, l_scale, &result, Policy());
0161    } // cauchy_distribution
0162
0163    RealType location()const
0164    {
0165       return m_a;
0166    }
0167    RealType scale()const
0168    {
0169       return m_hg;
0170    }
0171
0172 private:
0173    RealType m_a;    // The location, this is the median of the distribution.
0174    RealType m_hg;   // The scale )or shape), this is the half width at half height.
0175 };
0176
0177 typedef cauchy_distribution<double> cauchy;
0178
0179 #ifdef __cpp_deduction_guides
0180 template <class RealType>
0181 cauchy_distribution(RealType)->cauchy_distribution<typename boost::math::tools::promote_args<RealType>::type>;
0182 template <class RealType>
0183 cauchy_distribution(RealType,RealType)->cauchy_distribution<typename boost::math::tools::promote_args<RealType>::type>;
0184 #endif
0185
0186 template <class RealType, class Policy>
0187 inline const std::pair<RealType, RealType> range(const cauchy_distribution<RealType, Policy>&)
0188 { // Range of permissible values for random variable x.
0189   if (std::numeric_limits<RealType>::has_infinity)
0190   {
0191      return std::pair<RealType, RealType>(-std::numeric_limits<RealType>::infinity(), std::numeric_limits<RealType>::infinity()); // - to + infinity.
0192   }
0193   else
0194   { // Can only use max_value.
0195    using boost::math::tools::max_value;
0196    return std::pair<RealType, RealType>(-max_value<RealType>(), max_value<RealType>()); // - to + max.
0197   }
0198 }
0199
0200 template <class RealType, class Policy>
0201 inline const std::pair<RealType, RealType> support(const cauchy_distribution<RealType, Policy>& )
0202 { // Range of supported values for random variable x.
0203    // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero.
0204   if (std::numeric_limits<RealType>::has_infinity)
0205   {
0206      return std::pair<RealType, RealType>(-std::numeric_limits<RealType>::infinity(), std::numeric_limits<RealType>::infinity()); // - to + infinity.
0207   }
0208   else
0209   { // Can only use max_value.
0210      using boost::math::tools::max_value;
0211      return std::pair<RealType, RealType>(-tools::max_value<RealType>(), max_value<RealType>()); // - to + max.
0212   }
0213 }
0214
0215 template <class RealType, class Policy>
0216 inline RealType pdf(const cauchy_distribution<RealType, Policy>& dist, const RealType& x)
0217 {
0218    BOOST_MATH_STD_USING  // for ADL of std functions
0219
0220    static const char* function = "boost::math::pdf(cauchy<%1%>&, %1%)";
0221    RealType result = 0;
0222    RealType location = dist.location();
0223    RealType scale = dist.scale();
0224    if(false == detail::check_scale("boost::math::pdf(cauchy<%1%>&, %1%)", scale, &result, Policy()))
0225    {
0226       return result;
0227    }
0228    if(false == detail::check_location("boost::math::pdf(cauchy<%1%>&, %1%)", location, &result, Policy()))
0229    {
0230       return result;
0231    }
0232    if((boost::math::isinf)(x))
0233    {
0234      return 0; // pdf + and - infinity is zero.
0235    }
0236    // These produce MSVC 4127 warnings, so the above used instead.
0237    //if(std::numeric_limits<RealType>::has_infinity && abs(x) == std::numeric_limits<RealType>::infinity())
0238    //{ // pdf + and - infinity is zero.
0239    //  return 0;
0240    //}
0241
0242    if(false == detail::check_x(function, x, &result, Policy()))
0243    { // Catches x = NaN
0244       return result;
0245    }
0246
0247    RealType xs = (x - location) / scale;
0248    result = 1 / (constants::pi<RealType>() * scale * (1 + xs * xs));
0249    return result;
0250 } // pdf
0251
0252 template <class RealType, class Policy>
0253 inline RealType cdf(const cauchy_distribution<RealType, Policy>& dist, const RealType& x)
0254 {
0255    return detail::cdf_imp(dist, x, false);
0256 } // cdf
0257
0258 template <class RealType, class Policy>
0259 inline RealType quantile(const cauchy_distribution<RealType, Policy>& dist, const RealType& p)
0260 {
0261    return detail::quantile_imp(dist, p, false);
0262 } // quantile
0263
0264 template <class RealType, class Policy>
0265 inline RealType cdf(const complemented2_type<cauchy_distribution<RealType, Policy>, RealType>& c)
0266 {
0267    return detail::cdf_imp(c.dist, c.param, true);
0268 } //  cdf complement
0269
0270 template <class RealType, class Policy>
0271 inline RealType quantile(const complemented2_type<cauchy_distribution<RealType, Policy>, RealType>& c)
0272 {
0273    return detail::quantile_imp(c.dist, c.param, true);
0274 } // quantile complement
0275
0276 template <class RealType, class Policy>
0277 inline RealType mean(const cauchy_distribution<RealType, Policy>&)
0278 {  // There is no mean:
0279    typedef typename Policy::assert_undefined_type assert_type;
0280    static_assert(assert_type::value == 0, "assert type is undefined");
0281
0282    return policies::raise_domain_error<RealType>(
0283       "boost::math::mean(cauchy<%1%>&)",
0284       "The Cauchy distribution does not have a mean: "
0285       "the only possible return value is %1%.",
0286       std::numeric_limits<RealType>::quiet_NaN(), Policy());
0287 }
0288
0289 template <class RealType, class Policy>
0290 inline RealType variance(const cauchy_distribution<RealType, Policy>& /*dist*/)
0291 {
0292    // There is no variance:
0293    typedef typename Policy::assert_undefined_type assert_type;
0294    static_assert(assert_type::value == 0, "assert type is undefined");
0295
0296    return policies::raise_domain_error<RealType>(
0297       "boost::math::variance(cauchy<%1%>&)",
0298       "The Cauchy distribution does not have a variance: "
0299       "the only possible return value is %1%.",
0300       std::numeric_limits<RealType>::quiet_NaN(), Policy());
0301 }
0302
0303 template <class RealType, class Policy>
0304 inline RealType mode(const cauchy_distribution<RealType, Policy>& dist)
0305 {
0306    return dist.location();
0307 }
0308
0309 template <class RealType, class Policy>
0310 inline RealType median(const cauchy_distribution<RealType, Policy>& dist)
0311 {
0312    return dist.location();
0313 }
0314 template <class RealType, class Policy>
0315 inline RealType skewness(const cauchy_distribution<RealType, Policy>& /*dist*/)
0316 {
0317    // There is no skewness:
0318    typedef typename Policy::assert_undefined_type assert_type;
0319    static_assert(assert_type::value == 0, "assert type is undefined");
0320
0321    return policies::raise_domain_error<RealType>(
0322       "boost::math::skewness(cauchy<%1%>&)",
0323       "The Cauchy distribution does not have a skewness: "
0324       "the only possible return value is %1%.",
0325       std::numeric_limits<RealType>::quiet_NaN(), Policy()); // infinity?
0326 }
0327
0328 template <class RealType, class Policy>
0329 inline RealType kurtosis(const cauchy_distribution<RealType, Policy>& /*dist*/)
0330 {
0331    // There is no kurtosis:
0332    typedef typename Policy::assert_undefined_type assert_type;
0333    static_assert(assert_type::value == 0, "assert type is undefined");
0334
0335    return policies::raise_domain_error<RealType>(
0336       "boost::math::kurtosis(cauchy<%1%>&)",
0337       "The Cauchy distribution does not have a kurtosis: "
0338       "the only possible return value is %1%.",
0339       std::numeric_limits<RealType>::quiet_NaN(), Policy());
0340 }
0341
0342 template <class RealType, class Policy>
0343 inline RealType kurtosis_excess(const cauchy_distribution<RealType, Policy>& /*dist*/)
0344 {
0345    // There is no kurtosis excess:
0346    typedef typename Policy::assert_undefined_type assert_type;
0347    static_assert(assert_type::value == 0, "assert type is undefined");
0348
0349    return policies::raise_domain_error<RealType>(
0350       "boost::math::kurtosis_excess(cauchy<%1%>&)",
0351       "The Cauchy distribution does not have a kurtosis: "
0352       "the only possible return value is %1%.",
0353       std::numeric_limits<RealType>::quiet_NaN(), Policy());
0354 }
0355
0356 template <class RealType, class Policy>
0357 inline RealType entropy(const cauchy_distribution<RealType, Policy> & dist)
0358 {
0359    using std::log;
0360    return log(2*constants::two_pi<RealType>()*dist.scale());
0361 }
0362
0363 } // namespace math
0364 } // namespace boost
0365
0366 #ifdef _MSC_VER
0367 #pragma warning(pop)
0368 #endif
0369
0370 // This include must be at the end, *after* the accessors
0371 // for this distribution have been defined, in order to
0372 // keep compilers that support two-phase lookup happy.
0373 #include <boost/math/distributions/detail/derived_accessors.hpp>
0374
0375 #endif // BOOST_STATS_CAUCHY_HPP