Chris@16: // boost\math\special_functions\negative_binomial.hpp
Chris@16: 
Chris@16: // Copyright Paul A. Bristow 2007.
Chris@16: // Copyright John Maddock 2007.
Chris@16: 
Chris@16: // Use, modification and distribution are subject to the
Chris@16: // Boost Software License, Version 1.0.
Chris@16: // (See accompanying file LICENSE_1_0.txt
Chris@16: // or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16: 
Chris@16: // http://en.wikipedia.org/wiki/negative_binomial_distribution
Chris@16: // http://mathworld.wolfram.com/NegativeBinomialDistribution.html
Chris@16: // http://documents.wolfram.com/teachersedition/Teacher/Statistics/DiscreteDistributions.html
Chris@16: 
Chris@16: // The negative binomial distribution NegativeBinomialDistribution[n, p]
Chris@16: // is the distribution of the number (k) of failures that occur in a sequence of trials before
Chris@16: // r successes have occurred, where the probability of success in each trial is p.
Chris@16: 
Chris@16: // In a sequence of Bernoulli trials or events
Chris@16: // (independent, yes or no, succeed or fail) with success_fraction probability p,
Chris@16: // negative_binomial is the probability that k or fewer failures
Chris@16: // preceed the r th trial's success.
Chris@16: // random variable k is the number of failures (NOT the probability).
Chris@16: 
Chris@16: // Negative_binomial distribution is a discrete probability distribution.
Chris@16: // But note that the negative binomial distribution
Chris@16: // (like others including the binomial, Poisson & Bernoulli)
Chris@16: // is strictly defined as a discrete function: only integral values of k are envisaged.
Chris@16: // However because of the method of calculation using a continuous gamma function,
Chris@16: // it is convenient to treat it as if a continous function,
Chris@16: // and permit non-integral values of k.
Chris@16: 
Chris@16: // However, by default the policy is to use discrete_quantile_policy.
Chris@16: 
Chris@16: // To enforce the strict mathematical model, users should use conversion
Chris@16: // on k outside this function to ensure that k is integral.
Chris@16: 
Chris@16: // MATHCAD cumulative negative binomial pnbinom(k, n, p)
Chris@16: 
Chris@16: // Implementation note: much greater speed, and perhaps greater accuracy,
Chris@16: // might be achieved for extreme values by using a normal approximation.
Chris@16: // This is NOT been tested or implemented.
Chris@16: 
Chris@16: #ifndef BOOST_MATH_SPECIAL_NEGATIVE_BINOMIAL_HPP
Chris@16: #define BOOST_MATH_SPECIAL_NEGATIVE_BINOMIAL_HPP
Chris@16: 
Chris@16: #include <boost/math/distributions/fwd.hpp>
Chris@16: #include <boost/math/special_functions/beta.hpp> // for ibeta(a, b, x) == Ix(a, b).
Chris@16: #include <boost/math/distributions/complement.hpp> // complement.
Chris@16: #include <boost/math/distributions/detail/common_error_handling.hpp> // error checks domain_error & logic_error.
Chris@16: #include <boost/math/special_functions/fpclassify.hpp> // isnan.
Chris@16: #include <boost/math/tools/roots.hpp> // for root finding.
Chris@16: #include <boost/math/distributions/detail/inv_discrete_quantile.hpp>
Chris@16: 
Chris@16: #include <boost/type_traits/is_floating_point.hpp>
Chris@16: #include <boost/type_traits/is_integral.hpp>
Chris@16: #include <boost/type_traits/is_same.hpp>
Chris@16: #include <boost/mpl/if.hpp>
Chris@16: 
Chris@16: #include <limits> // using std::numeric_limits;
Chris@16: #include <utility>
Chris@16: 
Chris@16: #if defined (BOOST_MSVC)
Chris@16: #  pragma warning(push)
Chris@16: // This believed not now necessary, so commented out.
Chris@16: //#  pragma warning(disable: 4702) // unreachable code.
Chris@16: // in domain_error_imp in error_handling.
Chris@16: #endif
Chris@16: 
Chris@16: namespace boost
Chris@16: {
Chris@16:   namespace math
Chris@16:   {
Chris@16:     namespace negative_binomial_detail
Chris@16:     {
Chris@16:       // Common error checking routines for negative binomial distribution functions:
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_successes(const char* function, const RealType& r, RealType* result, const Policy& pol)
Chris@16:       {
Chris@16:         if( !(boost::math::isfinite)(r) || (r <= 0) )
Chris@16:         {
Chris@16:           *result = policies::raise_domain_error<RealType>(
Chris@16:             function,
Chris@16:             "Number of successes argument is %1%, but must be > 0 !", r, pol);
Chris@16:           return false;
Chris@16:         }
Chris@16:         return true;
Chris@16:       }
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_success_fraction(const char* function, const RealType& p, RealType* result, const Policy& pol)
Chris@16:       {
Chris@16:         if( !(boost::math::isfinite)(p) || (p < 0) || (p > 1) )
Chris@16:         {
Chris@16:           *result = policies::raise_domain_error<RealType>(
Chris@16:             function,
Chris@16:             "Success fraction argument is %1%, but must be >= 0 and <= 1 !", p, pol);
Chris@16:           return false;
Chris@16:         }
Chris@16:         return true;
Chris@16:       }
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist(const char* function, const RealType& r, const RealType& p, RealType* result, const Policy& pol)
Chris@16:       {
Chris@16:         return check_success_fraction(function, p, result, pol)
Chris@16:           && check_successes(function, r, result, pol);
Chris@16:       }
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist_and_k(const char* function, const RealType& r, const RealType& p, RealType k, RealType* result, const Policy& pol)
Chris@16:       {
Chris@16:         if(check_dist(function, r, p, result, pol) == false)
Chris@16:         {
Chris@16:           return false;
Chris@16:         }
Chris@16:         if( !(boost::math::isfinite)(k) || (k < 0) )
Chris@16:         { // Check k failures.
Chris@16:           *result = policies::raise_domain_error<RealType>(
Chris@16:             function,
Chris@16:             "Number of failures argument is %1%, but must be >= 0 !", k, pol);
Chris@16:           return false;
Chris@16:         }
Chris@16:         return true;
Chris@16:       } // Check_dist_and_k
Chris@16: 
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline bool check_dist_and_prob(const char* function, const RealType& r, RealType p, RealType prob, RealType* result, const Policy& pol)
Chris@16:       {
Chris@16:         if(check_dist(function, r, p, result, pol) && detail::check_probability(function, prob, result, pol) == false)
Chris@16:         {
Chris@16:           return false;
Chris@16:         }
Chris@16:         return true;
Chris@16:       } // check_dist_and_prob
Chris@16:     } //  namespace negative_binomial_detail
Chris@16: 
Chris@16:     template <class RealType = double, class Policy = policies::policy<> >
Chris@16:     class negative_binomial_distribution
Chris@16:     {
Chris@16:     public:
Chris@16:       typedef RealType value_type;
Chris@16:       typedef Policy policy_type;
Chris@16: 
Chris@16:       negative_binomial_distribution(RealType r, RealType p) : m_r(r), m_p(p)
Chris@16:       { // Constructor.
Chris@16:         RealType result;
Chris@16:         negative_binomial_detail::check_dist(
Chris@16:           "negative_binomial_distribution<%1%>::negative_binomial_distribution",
Chris@16:           m_r, // Check successes r > 0.
Chris@16:           m_p, // Check success_fraction 0 <= p <= 1.
Chris@16:           &result, Policy());
Chris@16:       } // negative_binomial_distribution constructor.
Chris@16: 
Chris@16:       // Private data getter class member functions.
Chris@16:       RealType success_fraction() const
Chris@16:       { // Probability of success as fraction in range 0 to 1.
Chris@16:         return m_p;
Chris@16:       }
Chris@16:       RealType successes() const
Chris@16:       { // Total number of successes r.
Chris@16:         return m_r;
Chris@16:       }
Chris@16: 
Chris@16:       static RealType find_lower_bound_on_p(
Chris@16:         RealType trials,
Chris@16:         RealType successes,
Chris@16:         RealType alpha) // alpha 0.05 equivalent to 95% for one-sided test.
Chris@16:       {
Chris@16:         static const char* function = "boost::math::negative_binomial<%1%>::find_lower_bound_on_p";
Chris@16:         RealType result = 0;  // of error checks.
Chris@16:         RealType failures = trials - successes;
Chris@16:         if(false == detail::check_probability(function, alpha, &result, Policy())
Chris@16:           && negative_binomial_detail::check_dist_and_k(
Chris@16:           function, successes, RealType(0), failures, &result, Policy()))
Chris@16:         {
Chris@16:           return result;
Chris@16:         }
Chris@16:         // Use complement ibeta_inv function for lower bound.
Chris@16:         // This is adapted from the corresponding binomial formula
Chris@16:         // here: http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm
Chris@16:         // This is a Clopper-Pearson interval, and may be overly conservative,
Chris@16:         // see also "A Simple Improved Inferential Method for Some
Chris@16:         // Discrete Distributions" Yong CAI and K. KRISHNAMOORTHY
Chris@16:         // http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
Chris@16:         //
Chris@16:         return ibeta_inv(successes, failures + 1, alpha, static_cast<RealType*>(0), Policy());
Chris@16:       } // find_lower_bound_on_p
Chris@16: 
Chris@16:       static RealType find_upper_bound_on_p(
Chris@16:         RealType trials,
Chris@16:         RealType successes,
Chris@16:         RealType alpha) // alpha 0.05 equivalent to 95% for one-sided test.
Chris@16:       {
Chris@16:         static const char* function = "boost::math::negative_binomial<%1%>::find_upper_bound_on_p";
Chris@16:         RealType result = 0;  // of error checks.
Chris@16:         RealType failures = trials - successes;
Chris@16:         if(false == negative_binomial_detail::check_dist_and_k(
Chris@16:           function, successes, RealType(0), failures, &result, Policy())
Chris@16:           && detail::check_probability(function, alpha, &result, Policy()))
Chris@16:         {
Chris@16:           return result;
Chris@16:         }
Chris@16:         if(failures == 0)
Chris@16:            return 1;
Chris@16:         // Use complement ibetac_inv function for upper bound.
Chris@16:         // Note adjusted failures value: *not* failures+1 as usual.
Chris@16:         // This is adapted from the corresponding binomial formula
Chris@16:         // here: http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm
Chris@16:         // This is a Clopper-Pearson interval, and may be overly conservative,
Chris@16:         // see also "A Simple Improved Inferential Method for Some
Chris@16:         // Discrete Distributions" Yong CAI and K. KRISHNAMOORTHY
Chris@16:         // http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf
Chris@16:         //
Chris@16:         return ibetac_inv(successes, failures, alpha, static_cast<RealType*>(0), Policy());
Chris@16:       } // find_upper_bound_on_p
Chris@16: 
Chris@16:       // Estimate number of trials :
Chris@16:       // "How many trials do I need to be P% sure of seeing k or fewer failures?"
Chris@16: 
Chris@16:       static RealType find_minimum_number_of_trials(
Chris@16:         RealType k,     // number of failures (k >= 0).
Chris@16:         RealType p,     // success fraction 0 <= p <= 1.
Chris@16:         RealType alpha) // risk level threshold 0 <= alpha <= 1.
Chris@16:       {
Chris@16:         static const char* function = "boost::math::negative_binomial<%1%>::find_minimum_number_of_trials";
Chris@16:         // Error checks:
Chris@16:         RealType result = 0;
Chris@16:         if(false == negative_binomial_detail::check_dist_and_k(
Chris@16:           function, RealType(1), p, k, &result, Policy())
Chris@16:           && detail::check_probability(function, alpha, &result, Policy()))
Chris@16:         { return result; }
Chris@16: 
Chris@16:         result = ibeta_inva(k + 1, p, alpha, Policy());  // returns n - k
Chris@16:         return result + k;
Chris@16:       } // RealType find_number_of_failures
Chris@16: 
Chris@16:       static RealType find_maximum_number_of_trials(
Chris@16:         RealType k,     // number of failures (k >= 0).
Chris@16:         RealType p,     // success fraction 0 <= p <= 1.
Chris@16:         RealType alpha) // risk level threshold 0 <= alpha <= 1.
Chris@16:       {
Chris@16:         static const char* function = "boost::math::negative_binomial<%1%>::find_maximum_number_of_trials";
Chris@16:         // Error checks:
Chris@16:         RealType result = 0;
Chris@16:         if(false == negative_binomial_detail::check_dist_and_k(
Chris@16:           function, RealType(1), p, k, &result, Policy())
Chris@16:           &&  detail::check_probability(function, alpha, &result, Policy()))
Chris@16:         { return result; }
Chris@16: 
Chris@16:         result = ibetac_inva(k + 1, p, alpha, Policy());  // returns n - k
Chris@16:         return result + k;
Chris@16:       } // RealType find_number_of_trials complemented
Chris@16: 
Chris@16:     private:
Chris@16:       RealType m_r; // successes.
Chris@16:       RealType m_p; // success_fraction
Chris@16:     }; // template <class RealType, class Policy> class negative_binomial_distribution
Chris@16: 
Chris@16:     typedef negative_binomial_distribution<double> negative_binomial; // Reserved name of type double.
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline const std::pair<RealType, RealType> range(const negative_binomial_distribution<RealType, Policy>& /* dist */)
Chris@16:     { // Range of permissible values for random variable k.
Chris@16:        using boost::math::tools::max_value;
Chris@16:        return std::pair<RealType, RealType>(static_cast<RealType>(0), max_value<RealType>()); // max_integer?
Chris@16:     }
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline const std::pair<RealType, RealType> support(const negative_binomial_distribution<RealType, Policy>& /* dist */)
Chris@16:     { // Range of supported values for random variable k.
Chris@16:        // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero.
Chris@16:        using boost::math::tools::max_value;
Chris@16:        return std::pair<RealType, RealType>(static_cast<RealType>(0),  max_value<RealType>()); // max_integer?
Chris@16:     }
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType mean(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     { // Mean of Negative Binomial distribution = r(1-p)/p.
Chris@16:       return dist.successes() * (1 - dist.success_fraction() ) / dist.success_fraction();
Chris@16:     } // mean
Chris@16: 
Chris@16:     //template <class RealType, class Policy>
Chris@16:     //inline RealType median(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     //{ // Median of negative_binomial_distribution is not defined.
Chris@16:     //  return policies::raise_domain_error<RealType>(BOOST_CURRENT_FUNCTION, "Median is not implemented, result is %1%!", std::numeric_limits<RealType>::quiet_NaN());
Chris@16:     //} // median
Chris@16:     // Now implemented via quantile(half) in derived accessors.
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType mode(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     { // Mode of Negative Binomial distribution = floor[(r-1) * (1 - p)/p]
Chris@16:       BOOST_MATH_STD_USING // ADL of std functions.
Chris@16:       return floor((dist.successes() -1) * (1 - dist.success_fraction()) / dist.success_fraction());
Chris@16:     } // mode
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType skewness(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     { // skewness of Negative Binomial distribution = 2-p / (sqrt(r(1-p))
Chris@16:       BOOST_MATH_STD_USING // ADL of std functions.
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       RealType r = dist.successes();
Chris@16: 
Chris@16:       return (2 - p) /
Chris@16:         sqrt(r * (1 - p));
Chris@16:     } // skewness
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType kurtosis(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     { // kurtosis of Negative Binomial distribution
Chris@16:       // http://en.wikipedia.org/wiki/Negative_binomial is kurtosis_excess so add 3
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       RealType r = dist.successes();
Chris@16:       return 3 + (6 / r) + ((p * p) / (r * (1 - p)));
Chris@16:     } // kurtosis
Chris@16: 
Chris@16:      template <class RealType, class Policy>
Chris@16:     inline RealType kurtosis_excess(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     { // kurtosis excess of Negative Binomial distribution
Chris@16:       // http://mathworld.wolfram.com/Kurtosis.html table of kurtosis_excess
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       RealType r = dist.successes();
Chris@16:       return (6 - p * (6-p)) / (r * (1-p));
Chris@16:     } // kurtosis_excess
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType variance(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     { // Variance of Binomial distribution = r (1-p) / p^2.
Chris@16:       return  dist.successes() * (1 - dist.success_fraction())
Chris@16:         / (dist.success_fraction() * dist.success_fraction());
Chris@16:     } // variance
Chris@16: 
Chris@16:     // RealType standard_deviation(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     // standard_deviation provided by derived accessors.
Chris@16:     // RealType hazard(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     // hazard of Negative Binomial distribution provided by derived accessors.
Chris@16:     // RealType chf(const negative_binomial_distribution<RealType, Policy>& dist)
Chris@16:     // chf of Negative Binomial distribution provided by derived accessors.
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType pdf(const negative_binomial_distribution<RealType, Policy>& dist, const RealType& k)
Chris@16:     { // Probability Density/Mass Function.
Chris@16:       BOOST_FPU_EXCEPTION_GUARD
Chris@16: 
Chris@16:       static const char* function = "boost::math::pdf(const negative_binomial_distribution<%1%>&, %1%)";
Chris@16: 
Chris@16:       RealType r = dist.successes();
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       RealType result = 0;
Chris@16:       if(false == negative_binomial_detail::check_dist_and_k(
Chris@16:         function,
Chris@16:         r,
Chris@16:         dist.success_fraction(),
Chris@16:         k,
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16: 
Chris@16:       result = (p/(r + k)) * ibeta_derivative(r, static_cast<RealType>(k+1), p, Policy());
Chris@16:       // Equivalent to:
Chris@16:       // return exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, r) * pow((1-p), k);
Chris@16:       return result;
Chris@16:     } // negative_binomial_pdf
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType cdf(const negative_binomial_distribution<RealType, Policy>& dist, const RealType& k)
Chris@16:     { // Cumulative Distribution Function of Negative Binomial.
Chris@16:       static const char* function = "boost::math::cdf(const negative_binomial_distribution<%1%>&, %1%)";
Chris@16:       using boost::math::ibeta; // Regularized incomplete beta function.
Chris@16:       // k argument may be integral, signed, or unsigned, or floating point.
Chris@16:       // If necessary, it has already been promoted from an integral type.
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       RealType r = dist.successes();
Chris@16:       // Error check:
Chris@16:       RealType result = 0;
Chris@16:       if(false == negative_binomial_detail::check_dist_and_k(
Chris@16:         function,
Chris@16:         r,
Chris@16:         dist.success_fraction(),
Chris@16:         k,
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16: 
Chris@16:       RealType probability = ibeta(r, static_cast<RealType>(k+1), p, Policy());
Chris@16:       // Ip(r, k+1) = ibeta(r, k+1, p)
Chris@16:       return probability;
Chris@16:     } // cdf Cumulative Distribution Function Negative Binomial.
Chris@16: 
Chris@16:       template <class RealType, class Policy>
Chris@16:       inline RealType cdf(const complemented2_type<negative_binomial_distribution<RealType, Policy>, RealType>& c)
Chris@16:       { // Complemented Cumulative Distribution Function Negative Binomial.
Chris@16: 
Chris@16:       static const char* function = "boost::math::cdf(const negative_binomial_distribution<%1%>&, %1%)";
Chris@16:       using boost::math::ibetac; // Regularized incomplete beta function complement.
Chris@16:       // k argument may be integral, signed, or unsigned, or floating point.
Chris@16:       // If necessary, it has already been promoted from an integral type.
Chris@16:       RealType const& k = c.param;
Chris@16:       negative_binomial_distribution<RealType, Policy> const& dist = c.dist;
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       RealType r = dist.successes();
Chris@16:       // Error check:
Chris@16:       RealType result = 0;
Chris@16:       if(false == negative_binomial_detail::check_dist_and_k(
Chris@16:         function,
Chris@16:         r,
Chris@16:         p,
Chris@16:         k,
Chris@16:         &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16:       // Calculate cdf negative binomial using the incomplete beta function.
Chris@16:       // Use of ibeta here prevents cancellation errors in calculating
Chris@16:       // 1-p if p is very small, perhaps smaller than machine epsilon.
Chris@16:       // Ip(k+1, r) = ibetac(r, k+1, p)
Chris@16:       // constrain_probability here?
Chris@16:      RealType probability = ibetac(r, static_cast<RealType>(k+1), p, Policy());
Chris@16:       // Numerical errors might cause probability to be slightly outside the range < 0 or > 1.
Chris@16:       // This might cause trouble downstream, so warn, possibly throw exception, but constrain to the limits.
Chris@16:       return probability;
Chris@16:     } // cdf Cumulative Distribution Function Negative Binomial.
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType quantile(const negative_binomial_distribution<RealType, Policy>& dist, const RealType& P)
Chris@16:     { // Quantile, percentile/100 or Percent Point Negative Binomial function.
Chris@16:       // Return the number of expected failures k for a given probability p.
Chris@16: 
Chris@16:       // Inverse cumulative Distribution Function or Quantile (percentile / 100) of negative_binomial Probability.
Chris@16:       // MAthCAD pnbinom return smallest k such that negative_binomial(k, n, p) >= probability.
Chris@16:       // k argument may be integral, signed, or unsigned, or floating point.
Chris@16:       // BUT Cephes/CodeCogs says: finds argument p (0 to 1) such that cdf(k, n, p) = y
Chris@16:       static const char* function = "boost::math::quantile(const negative_binomial_distribution<%1%>&, %1%)";
Chris@16:       BOOST_MATH_STD_USING // ADL of std functions.
Chris@16: 
Chris@16:       RealType p = dist.success_fraction();
Chris@16:       RealType r = dist.successes();
Chris@16:       // Check dist and P.
Chris@16:       RealType result = 0;
Chris@16:       if(false == negative_binomial_detail::check_dist_and_prob
Chris@16:         (function, r, p, P, &result, Policy()))
Chris@16:       {
Chris@16:         return result;
Chris@16:       }
Chris@16: 
Chris@16:       // Special cases.
Chris@16:       if (P == 1)
Chris@16:       {  // Would need +infinity failures for total confidence.
Chris@16:         result = policies::raise_overflow_error<RealType>(
Chris@16:             function,
Chris@16:             "Probability argument is 1, which implies infinite failures !", Policy());
Chris@16:         return result;
Chris@16:        // usually means return +std::numeric_limits<RealType>::infinity();
Chris@16:        // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR
Chris@16:       }
Chris@16:       if (P == 0)
Chris@16:       { // No failures are expected if P = 0.
Chris@16:         return 0; // Total trials will be just dist.successes.
Chris@16:       }
Chris@16:       if (P <= pow(dist.success_fraction(), dist.successes()))
Chris@16:       { // p <= pdf(dist, 0) == cdf(dist, 0)
Chris@16:         return 0;
Chris@16:       }
Chris@101:       if(p == 0)
Chris@101:       {  // Would need +infinity failures for total confidence.
Chris@101:          result = policies::raise_overflow_error<RealType>(
Chris@101:             function,
Chris@101:             "Success fraction is 0, which implies infinite failures !", Policy());
Chris@101:          return result;
Chris@101:          // usually means return +std::numeric_limits<RealType>::infinity();
Chris@101:          // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR
Chris@101:       }
Chris@16:       /*
Chris@16:       // Calculate quantile of negative_binomial using the inverse incomplete beta function.
Chris@16:       using boost::math::ibeta_invb;
Chris@16:       return ibeta_invb(r, p, P, Policy()) - 1; //
Chris@16:       */
Chris@16:       RealType guess = 0;
Chris@16:       RealType factor = 5;
Chris@16:       if(r * r * r * P * p > 0.005)
Chris@16:          guess = detail::inverse_negative_binomial_cornish_fisher(r, p, RealType(1-p), P, RealType(1-P), Policy());
Chris@16: 
Chris@16:       if(guess < 10)
Chris@16:       {
Chris@16:          //
Chris@16:          // Cornish-Fisher Negative binomial approximation not accurate in this area:
Chris@16:          //
Chris@16:          guess = (std::min)(RealType(r * 2), RealType(10));
Chris@16:       }
Chris@16:       else
Chris@16:          factor = (1-P < sqrt(tools::epsilon<RealType>())) ? 2 : (guess < 20 ? 1.2f : 1.1f);
Chris@16:       BOOST_MATH_INSTRUMENT_CODE("guess = " << guess);
Chris@16:       //
Chris@16:       // Max iterations permitted:
Chris@16:       //
Chris@16:       boost::uintmax_t max_iter = policies::get_max_root_iterations<Policy>();
Chris@16:       typedef typename Policy::discrete_quantile_type discrete_type;
Chris@16:       return detail::inverse_discrete_quantile(
Chris@16:          dist,
Chris@16:          P,
Chris@16:          false,
Chris@16:          guess,
Chris@16:          factor,
Chris@16:          RealType(1),
Chris@16:          discrete_type(),
Chris@16:          max_iter);
Chris@16:     } // RealType quantile(const negative_binomial_distribution dist, p)
Chris@16: 
Chris@16:     template <class RealType, class Policy>
Chris@16:     inline RealType quantile(const complemented2_type<negative_binomial_distribution<RealType, Policy>, RealType>& c)
Chris@16:     {  // Quantile or Percent Point Binomial function.
Chris@16:        // Return the number of expected failures k for a given
Chris@16:        // complement of the probability Q = 1 - P.
Chris@16:        static const char* function = "boost::math::quantile(const negative_binomial_distribution<%1%>&, %1%)";
Chris@16:        BOOST_MATH_STD_USING
Chris@16: 
Chris@16:        // Error checks:
Chris@16:        RealType Q = c.param;
Chris@16:        const negative_binomial_distribution<RealType, Policy>& dist = c.dist;
Chris@16:        RealType p = dist.success_fraction();
Chris@16:        RealType r = dist.successes();
Chris@16:        RealType result = 0;
Chris@16:        if(false == negative_binomial_detail::check_dist_and_prob(
Chris@16:           function,
Chris@16:           r,
Chris@16:           p,
Chris@16:           Q,
Chris@16:           &result, Policy()))
Chris@16:        {
Chris@16:           return result;
Chris@16:        }
Chris@16: 
Chris@16:        // Special cases:
Chris@16:        //
Chris@16:        if(Q == 1)
Chris@16:        {  // There may actually be no answer to this question,
Chris@16:           // since the probability of zero failures may be non-zero,
Chris@16:           return 0; // but zero is the best we can do:
Chris@16:        }
Chris@16:        if(Q == 0)
Chris@16:        {  // Probability 1 - Q  == 1 so infinite failures to achieve certainty.
Chris@16:           // Would need +infinity failures for total confidence.
Chris@16:           result = policies::raise_overflow_error<RealType>(
Chris@16:              function,
Chris@16:              "Probability argument complement is 0, which implies infinite failures !", Policy());
Chris@16:           return result;
Chris@16:           // usually means return +std::numeric_limits<RealType>::infinity();
Chris@16:           // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR
Chris@16:        }
Chris@101:        if (-Q <= boost::math::powm1(dist.success_fraction(), dist.successes(), Policy()))
Chris@101:        {  // q <= cdf(complement(dist, 0)) == pdf(dist, 0)
Chris@101:           return 0; //
Chris@101:        }
Chris@101:        if(p == 0)
Chris@101:        {  // Success fraction is 0 so infinite failures to achieve certainty.
Chris@101:           // Would need +infinity failures for total confidence.
Chris@101:           result = policies::raise_overflow_error<RealType>(
Chris@101:              function,
Chris@101:              "Success fraction is 0, which implies infinite failures !", Policy());
Chris@101:           return result;
Chris@101:           // usually means return +std::numeric_limits<RealType>::infinity();
Chris@101:           // unless #define BOOST_MATH_THROW_ON_OVERFLOW_ERROR
Chris@101:        }
Chris@16:        //return ibetac_invb(r, p, Q, Policy()) -1;
Chris@16:        RealType guess = 0;
Chris@16:        RealType factor = 5;
Chris@16:        if(r * r * r * (1-Q) * p > 0.005)
Chris@16:           guess = detail::inverse_negative_binomial_cornish_fisher(r, p, RealType(1-p), RealType(1-Q), Q, Policy());
Chris@16: 
Chris@16:        if(guess < 10)
Chris@16:        {
Chris@16:           //
Chris@16:           // Cornish-Fisher Negative binomial approximation not accurate in this area:
Chris@16:           //
Chris@16:           guess = (std::min)(RealType(r * 2), RealType(10));
Chris@16:        }
Chris@16:        else
Chris@16:           factor = (Q < sqrt(tools::epsilon<RealType>())) ? 2 : (guess < 20 ? 1.2f : 1.1f);
Chris@16:        BOOST_MATH_INSTRUMENT_CODE("guess = " << guess);
Chris@16:        //
Chris@16:        // Max iterations permitted:
Chris@16:        //
Chris@16:        boost::uintmax_t max_iter = policies::get_max_root_iterations<Policy>();
Chris@16:        typedef typename Policy::discrete_quantile_type discrete_type;
Chris@16:        return detail::inverse_discrete_quantile(
Chris@16:           dist,
Chris@16:           Q,
Chris@16:           true,
Chris@16:           guess,
Chris@16:           factor,
Chris@16:           RealType(1),
Chris@16:           discrete_type(),
Chris@16:           max_iter);
Chris@16:     } // quantile complement
Chris@16: 
Chris@16:  } // namespace math
Chris@16: } // namespace boost
Chris@16: 
Chris@16: // This include must be at the end, *after* the accessors
Chris@16: // for this distribution have been defined, in order to
Chris@16: // keep compilers that support two-phase lookup happy.
Chris@16: #include <boost/math/distributions/detail/derived_accessors.hpp>
Chris@16: 
Chris@16: #if defined (BOOST_MSVC)
Chris@16: # pragma warning(pop)
Chris@16: #endif
Chris@16: 
Chris@16: #endif // BOOST_MATH_SPECIAL_NEGATIVE_BINOMIAL_HPP