| // boost\math\distributions\geometric.hpp |
| |
| // Copyright John Maddock 2010. |
| // Copyright Paul A. Bristow 2010. |
| |
| // Use, modification and distribution are subject to the |
| // Boost Software License, Version 1.0. |
| // (See accompanying file LICENSE_1_0.txt |
| // or copy at http://www.boost.org/LICENSE_1_0.txt) |
| |
| // geometric distribution is a discrete probability distribution. |
| // It expresses the probability distribution of the number (k) of |
| // events, occurrences, failures or arrivals before the first success. |
| // supported on the set {0, 1, 2, 3...} |
| |
| // Note that the set includes zero (unlike some definitions that start at one). |
| |
| // The random variate k is the number of events, occurrences or arrivals. |
| // k argument may be integral, signed, or unsigned, or floating point. |
| // If necessary, it has already been promoted from an integral type. |
| |
| // Note that the geometric distribution |
| // (like others including the binomial, geometric & Bernoulli) |
| // is strictly defined as a discrete function: |
| // only integral values of k are envisaged. |
| // However because the method of calculation uses a continuous gamma function, |
| // it is convenient to treat it as if a continous function, |
| // and permit non-integral values of k. |
| // To enforce the strict mathematical model, users should use floor or ceil functions |
| // on k outside this function to ensure that k is integral. |
| |
| // See http://en.wikipedia.org/wiki/geometric_distribution |
| // http://documents.wolfram.com/v5/Add-onsLinks/StandardPackages/Statistics/DiscreteDistributions.html |
| // http://mathworld.wolfram.com/GeometricDistribution.html |
| |
| #ifndef BOOST_MATH_SPECIAL_GEOMETRIC_HPP |
| #define BOOST_MATH_SPECIAL_GEOMETRIC_HPP |
| |
| #include <boost/math/distributions/fwd.hpp> |
| #include <boost/math/special_functions/beta.hpp> // for ibeta(a, b, x) == Ix(a, b). |
| #include <boost/math/distributions/complement.hpp> // complement. |
| #include <boost/math/distributions/detail/common_error_handling.hpp> // error checks domain_error & logic_error. |
| #include <boost/math/special_functions/fpclassify.hpp> // isnan. |
| #include <boost/math/tools/roots.hpp> // for root finding. |
| #include <boost/math/distributions/detail/inv_discrete_quantile.hpp> |
| |
| #include <boost/type_traits/is_floating_point.hpp> |
| #include <boost/type_traits/is_integral.hpp> |
| #include <boost/type_traits/is_same.hpp> |
| #include <boost/mpl/if.hpp> |
| |
| #include <limits> // using std::numeric_limits; |
| #include <utility> |
| |
| #if defined (BOOST_MSVC) |
| # pragma warning(push) |
| // This believed not now necessary, so commented out. |
| //# pragma warning(disable: 4702) // unreachable code. |
| // in domain_error_imp in error_handling. |
| #endif |
| |
| namespace boost |
| { |
| namespace math |
| { |
| namespace geometric_detail |
| { |
| // Common error checking routines for geometric distribution function: |
| template <class RealType, class Policy> |
| inline bool check_success_fraction(const char* function, const RealType& p, RealType* result, const Policy& pol) |
| { |
| if( !(boost::math::isfinite)(p) || (p < 0) || (p > 1) ) |
| { |
| *result = policies::raise_domain_error<RealType>( |
| function, |
| "Success fraction argument is %1%, but must be >= 0 and <= 1 !", p, pol); |
| return false; |
| } |
| return true; |
| } |
| |
| template <class RealType, class Policy> |
| inline bool check_dist(const char* function, const RealType& p, RealType* result, const Policy& pol) |
| { |
| return check_success_fraction(function, p, result, pol); |
| } |
| |
| template <class RealType, class Policy> |
| inline bool check_dist_and_k(const char* function, const RealType& p, RealType k, RealType* result, const Policy& pol) |
| { |
| if(check_dist(function, p, result, pol) == false) |
| { |
| return false; |
| } |
| if( !(boost::math::isfinite)(k) || (k < 0) ) |
| { // Check k failures. |
| *result = policies::raise_domain_error<RealType>( |
| function, |
| "Number of failures argument is %1%, but must be >= 0 !", k, pol); |
| return false; |
| } |
| return true; |
| } // Check_dist_and_k |
| |
| template <class RealType, class Policy> |
| inline bool check_dist_and_prob(const char* function, RealType p, RealType prob, RealType* result, const Policy& pol) |
| { |
| if(check_dist(function, p, result, pol) && detail::check_probability(function, prob, result, pol) == false) |
| { |
| return false; |
| } |
| return true; |
| } // check_dist_and_prob |
| } // namespace geometric_detail |
| |
| template <class RealType = double, class Policy = policies::policy<> > |
| class geometric_distribution |
| { |
| public: |
| typedef RealType value_type; |
| typedef Policy policy_type; |
| |
| geometric_distribution(RealType p) : m_p(p) |
| { // Constructor stores success_fraction p. |
| RealType result; |
| geometric_detail::check_dist( |
| "geometric_distribution<%1%>::geometric_distribution", |
| m_p, // Check success_fraction 0 <= p <= 1. |
| &result, Policy()); |
| } // geometric_distribution constructor. |
| |
| // Private data getter class member functions. |
| RealType success_fraction() const |
| { // Probability of success as fraction in range 0 to 1. |
| return m_p; |
| } |
| RealType successes() const |
| { // Total number of successes r = 1 (for compatibility with negative binomial?). |
| return 1; |
| } |
| |
| // Parameter estimation. |
| // (These are copies of negative_binomial distribution with successes = 1). |
| static RealType find_lower_bound_on_p( |
| RealType trials, |
| RealType alpha) // alpha 0.05 equivalent to 95% for one-sided test. |
| { |
| static const char* function = "boost::math::geometric<%1%>::find_lower_bound_on_p"; |
| RealType result = 0; // of error checks. |
| RealType successes = 1; |
| RealType failures = trials - successes; |
| if(false == detail::check_probability(function, alpha, &result, Policy()) |
| && geometric_detail::check_dist_and_k( |
| function, RealType(0), failures, &result, Policy())) |
| { |
| return result; |
| } |
| // Use complement ibeta_inv function for lower bound. |
| // This is adapted from the corresponding binomial formula |
| // here: http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm |
| // This is a Clopper-Pearson interval, and may be overly conservative, |
| // see also "A Simple Improved Inferential Method for Some |
| // Discrete Distributions" Yong CAI and K. KRISHNAMOORTHY |
| // http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf |
| // |
| return ibeta_inv(successes, failures + 1, alpha, static_cast<RealType*>(0), Policy()); |
| } // find_lower_bound_on_p |
| |
| static RealType find_upper_bound_on_p( |
| RealType trials, |
| RealType alpha) // alpha 0.05 equivalent to 95% for one-sided test. |
| { |
| static const char* function = "boost::math::geometric<%1%>::find_upper_bound_on_p"; |
| RealType result = 0; // of error checks. |
| RealType successes = 1; |
| RealType failures = trials - successes; |
| if(false == geometric_detail::check_dist_and_k( |
| function, RealType(0), failures, &result, Policy()) |
| && detail::check_probability(function, alpha, &result, Policy())) |
| { |
| return result; |
| } |
| if(failures == 0) |
| { |
| return 1; |
| }// Use complement ibetac_inv function for upper bound. |
| // Note adjusted failures value: *not* failures+1 as usual. |
| // This is adapted from the corresponding binomial formula |
| // here: http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm |
| // This is a Clopper-Pearson interval, and may be overly conservative, |
| // see also "A Simple Improved Inferential Method for Some |
| // Discrete Distributions" Yong CAI and K. Krishnamoorthy |
| // http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf |
| // |
| return ibetac_inv(successes, failures, alpha, static_cast<RealType*>(0), Policy()); |
| } // find_upper_bound_on_p |
| |
| // Estimate number of trials : |
| // "How many trials do I need to be P% sure of seeing k or fewer failures?" |
| |
| static RealType find_minimum_number_of_trials( |
| RealType k, // number of failures (k >= 0). |
| RealType p, // success fraction 0 <= p <= 1. |
| RealType alpha) // risk level threshold 0 <= alpha <= 1. |
| { |
| static const char* function = "boost::math::geometric<%1%>::find_minimum_number_of_trials"; |
| // Error checks: |
| RealType result = 0; |
| if(false == geometric_detail::check_dist_and_k( |
| function, p, k, &result, Policy()) |
| && detail::check_probability(function, alpha, &result, Policy())) |
| { |
| return result; |
| } |
| result = ibeta_inva(k + 1, p, alpha, Policy()); // returns n - k |
| return result + k; |
| } // RealType find_number_of_failures |
| |
| static RealType find_maximum_number_of_trials( |
| RealType k, // number of failures (k >= 0). |
| RealType p, // success fraction 0 <= p <= 1. |
| RealType alpha) // risk level threshold 0 <= alpha <= 1. |
| { |
| static const char* function = "boost::math::geometric<%1%>::find_maximum_number_of_trials"; |
| // Error checks: |
| RealType result = 0; |
| if(false == geometric_detail::check_dist_and_k( |
| function, p, k, &result, Policy()) |
| && detail::check_probability(function, alpha, &result, Policy())) |
| { |
| return result; |
| } |
| result = ibetac_inva(k + 1, p, alpha, Policy()); // returns n - k |
| return result + k; |
| } // RealType find_number_of_trials complemented |
| |
| private: |
| //RealType m_r; // successes fixed at unity. |
| RealType m_p; // success_fraction |
| }; // template <class RealType, class Policy> class geometric_distribution |
| |
| typedef geometric_distribution<double> geometric; // Reserved name of type double. |
| |
| template <class RealType, class Policy> |
| inline const std::pair<RealType, RealType> range(const geometric_distribution<RealType, Policy>& /* dist */) |
| { // Range of permissible values for random variable k. |
| using boost::math::tools::max_value; |
| return std::pair<RealType, RealType>(static_cast<RealType>(0), max_value<RealType>()); // max_integer? |
| } |
| |
| template <class RealType, class Policy> |
| inline const std::pair<RealType, RealType> support(const geometric_distribution<RealType, Policy>& /* dist */) |
| { // Range of supported values for random variable k. |
| // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero. |
| using boost::math::tools::max_value; |
| return std::pair<RealType, RealType>(static_cast<RealType>(0), max_value<RealType>()); // max_integer? |
| } |
| |
| template <class RealType, class Policy> |
| inline RealType mean(const geometric_distribution<RealType, Policy>& dist) |
| { // Mean of geometric distribution = (1-p)/p. |
| return (1 - dist.success_fraction() ) / dist.success_fraction(); |
| } // mean |
| |
| // median implemented via quantile(half) in derived accessors. |
| |
| template <class RealType, class Policy> |
| inline RealType mode(const geometric_distribution<RealType, Policy>&) |
| { // Mode of geometric distribution = zero. |
| BOOST_MATH_STD_USING // ADL of std functions. |
| return 0; |
| } // mode |
| |
| template <class RealType, class Policy> |
| inline RealType variance(const geometric_distribution<RealType, Policy>& dist) |
| { // Variance of Binomial distribution = (1-p) / p^2. |
| return (1 - dist.success_fraction()) |
| / (dist.success_fraction() * dist.success_fraction()); |
| } // variance |
| |
| template <class RealType, class Policy> |
| inline RealType skewness(const geometric_distribution<RealType, Policy>& dist) |
| { // skewness of geometric distribution = 2-p / (sqrt(r(1-p)) |
| BOOST_MATH_STD_USING // ADL of std functions. |
| RealType p = dist.success_fraction(); |
| return (2 - p) / sqrt(1 - p); |
| } // skewness |
| |
| template <class RealType, class Policy> |
| inline RealType kurtosis(const geometric_distribution<RealType, Policy>& dist) |
| { // kurtosis of geometric distribution |
| // http://en.wikipedia.org/wiki/geometric is kurtosis_excess so add 3 |
| RealType p = dist.success_fraction(); |
| return 3 + (p*p - 6*p + 6) / (1 - p); |
| } // kurtosis |
| |
| template <class RealType, class Policy> |
| inline RealType kurtosis_excess(const geometric_distribution<RealType, Policy>& dist) |
| { // kurtosis excess of geometric distribution |
| // http://mathworld.wolfram.com/Kurtosis.html table of kurtosis_excess |
| RealType p = dist.success_fraction(); |
| return (p*p - 6*p + 6) / (1 - p); |
| } // kurtosis_excess |
| |
| // RealType standard_deviation(const geometric_distribution<RealType, Policy>& dist) |
| // standard_deviation provided by derived accessors. |
| // RealType hazard(const geometric_distribution<RealType, Policy>& dist) |
| // hazard of geometric distribution provided by derived accessors. |
| // RealType chf(const geometric_distribution<RealType, Policy>& dist) |
| // chf of geometric distribution provided by derived accessors. |
| |
| template <class RealType, class Policy> |
| inline RealType pdf(const geometric_distribution<RealType, Policy>& dist, const RealType& k) |
| { // Probability Density/Mass Function. |
| BOOST_FPU_EXCEPTION_GUARD |
| BOOST_MATH_STD_USING // For ADL of math functions. |
| static const char* function = "boost::math::pdf(const geometric_distribution<%1%>&, %1%)"; |
| |
| RealType p = dist.success_fraction(); |
| RealType result = 0; |
| if(false == geometric_detail::check_dist_and_k( |
| function, |
| p, |
| k, |
| &result, Policy())) |
| { |
| return result; |
| } |
| if (k == 0) |
| { |
| return p; // success_fraction |
| } |
| RealType q = 1 - p; // Inaccurate for small p? |
| // So try to avoid inaccuracy for large or small p. |
| // but has little effect > last significant bit. |
| //cout << "p * pow(q, k) " << result << endl; // seems best whatever p |
| //cout << "exp(p * k * log1p(-p)) " << p * exp(k * log1p(-p)) << endl; |
| //if (p < 0.5) |
| //{ |
| // result = p * pow(q, k); |
| //} |
| //else |
| //{ |
| // result = p * exp(k * log1p(-p)); |
| //} |
| result = p * pow(q, k); |
| return result; |
| } // geometric_pdf |
| |
| template <class RealType, class Policy> |
| inline RealType cdf(const geometric_distribution<RealType, Policy>& dist, const RealType& k) |
| { // Cumulative Distribution Function of geometric. |
| static const char* function = "boost::math::cdf(const geometric_distribution<%1%>&, %1%)"; |
| |
| // k argument may be integral, signed, or unsigned, or floating point. |
| // If necessary, it has already been promoted from an integral type. |
| RealType p = dist.success_fraction(); |
| // Error check: |
| RealType result = 0; |
| if(false == geometric_detail::check_dist_and_k( |
| function, |
| p, |
| k, |
| &result, Policy())) |
| { |
| return result; |
| } |
| if(k == 0) |
| { |
| return p; // success_fraction |
| } |
| //RealType q = 1 - p; // Bad for small p |
| //RealType probability = 1 - std::pow(q, k+1); |
| |
| RealType z = boost::math::log1p(-p, Policy()) * (k + 1); |
| RealType probability = -boost::math::expm1(z, Policy()); |
| |
| return probability; |
| } // cdf Cumulative Distribution Function geometric. |
| |
| template <class RealType, class Policy> |
| inline RealType cdf(const complemented2_type<geometric_distribution<RealType, Policy>, RealType>& c) |
| { // Complemented Cumulative Distribution Function geometric. |
| BOOST_MATH_STD_USING |
| static const char* function = "boost::math::cdf(const geometric_distribution<%1%>&, %1%)"; |
| // k argument may be integral, signed, or unsigned, or floating point. |
| // If necessary, it has already been promoted from an integral type. |
| RealType const& k = c.param; |
| geometric_distribution<RealType, Policy> const& dist = c.dist; |
| RealType p = dist.success_fraction(); |
| // Error check: |
| RealType result = 0; |
| if(false == geometric_detail::check_dist_and_k( |
| function, |
| p, |
| k, |
| &result, Policy())) |
| { |
| return result; |
| } |
| RealType z = boost::math::log1p(-p, Policy()) * (k+1); |
| RealType probability = exp(z); |
| return probability; |
| } // cdf Complemented Cumulative Distribution Function geometric. |
| |
| template <class RealType, class Policy> |
| inline RealType quantile(const geometric_distribution<RealType, Policy>& dist, const RealType& x) |
| { // Quantile, percentile/100 or Percent Point geometric function. |
| // Return the number of expected failures k for a given probability p. |
| |
| // Inverse cumulative Distribution Function or Quantile (percentile / 100) of geometric Probability. |
| // k argument may be integral, signed, or unsigned, or floating point. |
| |
| static const char* function = "boost::math::quantile(const geometric_distribution<%1%>&, %1%)"; |
| BOOST_MATH_STD_USING // ADL of std functions. |
| |
| RealType success_fraction = dist.success_fraction(); |
| // Check dist and x. |
| RealType result = 0; |
| if(false == geometric_detail::check_dist_and_prob |
| (function, success_fraction, x, &result, Policy())) |
| { |
| return result; |
| } |
| |
| // Special cases. |
| if (x == 1) |
| { // Would need +infinity failures for total confidence. |
| result = policies::raise_overflow_error<RealType>( |
| function, |
| "Probability argument is 1, which implies infinite failures !", Policy()); |
| return result; |
| // usually means return +std::numeric_limits<RealType>::infinity(); |
| // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR |
| } |
| if (x == 0) |
| { // No failures are expected if P = 0. |
| return 0; // Total trials will be just dist.successes. |
| } |
| // if (P <= pow(dist.success_fraction(), 1)) |
| if (x <= success_fraction) |
| { // p <= pdf(dist, 0) == cdf(dist, 0) |
| return 0; |
| } |
| if (x == 1) |
| { |
| return 0; |
| } |
| |
| // log(1-x) /log(1-success_fraction) -1; but use log1p in case success_fraction is small |
| result = boost::math::log1p(-x, Policy()) / boost::math::log1p(-success_fraction, Policy()) - 1; |
| // Subtract a few epsilons here too? |
| // to make sure it doesn't slip over, so ceil would be one too many. |
| return result; |
| } // RealType quantile(const geometric_distribution dist, p) |
| |
| template <class RealType, class Policy> |
| inline RealType quantile(const complemented2_type<geometric_distribution<RealType, Policy>, RealType>& c) |
| { // Quantile or Percent Point Binomial function. |
| // Return the number of expected failures k for a given |
| // complement of the probability Q = 1 - P. |
| static const char* function = "boost::math::quantile(const geometric_distribution<%1%>&, %1%)"; |
| BOOST_MATH_STD_USING |
| // Error checks: |
| RealType x = c.param; |
| const geometric_distribution<RealType, Policy>& dist = c.dist; |
| RealType success_fraction = dist.success_fraction(); |
| RealType result = 0; |
| if(false == geometric_detail::check_dist_and_prob( |
| function, |
| success_fraction, |
| x, |
| &result, Policy())) |
| { |
| return result; |
| } |
| |
| // Special cases: |
| if(x == 1) |
| { // There may actually be no answer to this question, |
| // since the probability of zero failures may be non-zero, |
| return 0; // but zero is the best we can do: |
| } |
| if (-x <= boost::math::powm1(dist.success_fraction(), dist.successes(), Policy())) |
| { // q <= cdf(complement(dist, 0)) == pdf(dist, 0) |
| return 0; // |
| } |
| if(x == 0) |
| { // Probability 1 - Q == 1 so infinite failures to achieve certainty. |
| // Would need +infinity failures for total confidence. |
| result = policies::raise_overflow_error<RealType>( |
| function, |
| "Probability argument complement is 0, which implies infinite failures !", Policy()); |
| return result; |
| // usually means return +std::numeric_limits<RealType>::infinity(); |
| // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR |
| } |
| // log(x) /log(1-success_fraction) -1; but use log1p in case success_fraction is small |
| result = log(x) / boost::math::log1p(-success_fraction, Policy()) - 1; |
| return result; |
| |
| } // quantile complement |
| |
| } // namespace math |
| } // namespace boost |
| |
| // This include must be at the end, *after* the accessors |
| // for this distribution have been defined, in order to |
| // keep compilers that support two-phase lookup happy. |
| #include <boost/math/distributions/detail/derived_accessors.hpp> |
| |
| #if defined (BOOST_MSVC) |
| # pragma warning(pop) |
| #endif |
| |
| #endif // BOOST_MATH_SPECIAL_GEOMETRIC_HPP |