1 // boost\math\distributions\binomial.hpp
2 
3 // Copyright John Maddock 2006.
4 // Copyright Paul A. Bristow 2007.
5 
6 // Use, modification and distribution are subject to the
7 // Boost Software License, Version 1.0.
8 // (See accompanying file LICENSE_1_0.txt
9 // or copy at http://www.boost.org/LICENSE_1_0.txt)
10 
11 // http://en.wikipedia.org/wiki/binomial_distribution
12 
13 // Binomial distribution is the discrete probability distribution of
14 // the number (k) of successes, in a sequence of
15 // n independent (yes or no, success or failure) Bernoulli trials.
16 
17 // It expresses the probability of a number of events occurring in a fixed time
18 // if these events occur with a known average rate (probability of success),
19 // and are independent of the time since the last event.
20 
21 // The number of cars that pass through a certain point on a road during a given period of time.
22 // The number of spelling mistakes a secretary makes while typing a single page.
23 // The number of phone calls at a call center per minute.
24 // The number of times a web server is accessed per minute.
25 // The number of light bulbs that burn out in a certain amount of time.
26 // The number of roadkill found per unit length of road
27 
28 // http://en.wikipedia.org/wiki/binomial_distribution
29 
30 // Given a sample of N measured values k[i],
31 // we wish to estimate the value of the parameter x (mean)
32 // of the binomial population from which the sample was drawn.
33 // To calculate the maximum likelihood value = 1/N sum i = 1 to N of k[i]
34 
35 // Also may want a function for EXACTLY k.
36 
37 // And probability that there are EXACTLY k occurrences is
38 // exp(-x) * pow(x, k) / factorial(k)
39 // where x is expected occurrences (mean) during the given interval.
40 // For example, if events occur, on average, every 4 min,
41 // and we are interested in number of events occurring in 10 min,
42 // then x = 10/4 = 2.5
43 
44 // http://www.itl.nist.gov/div898/handbook/eda/section3/eda366i.htm
45 
46 // The binomial distribution is used when there are
47 // exactly two mutually exclusive outcomes of a trial.
48 // These outcomes are appropriately labeled "success" and "failure".
49 // The binomial distribution is used to obtain
50 // the probability of observing x successes in N trials,
51 // with the probability of success on a single trial denoted by p.
52 // The binomial distribution assumes that p is fixed for all trials.
53 
54 // P(x, p, n) = n!/(x! * (n-x)!) * p^x * (1-p)^(n-x)
55 
56 // http://mathworld.wolfram.com/BinomialCoefficient.html
57 
58 // The binomial coefficient (n; k) is the number of ways of picking
59 // k unordered outcomes from n possibilities,
60 // also known as a combination or combinatorial number.
61 // The symbols _nC_k and (n; k) are used to denote a binomial coefficient,
62 // and are sometimes read as "n choose k."
63 // (n; k) therefore gives the number of k-subsets  possible out of a set of n distinct items.
64 
65 // For example:
66 //  The 2-subsets of {1,2,3,4} are the six pairs {1,2}, {1,3}, {1,4}, {2,3}, {2,4}, and {3,4}, so (4; 2)==6.
67 
68 // http://functions.wolfram.com/GammaBetaErf/Binomial/ for evaluation.
69 
70 // But note that the binomial distribution
71 // (like others including the poisson, negative binomial & Bernoulli)
72 // is strictly defined as a discrete function: only integral values of k are envisaged.
73 // However because of the method of calculation using a continuous gamma function,
74 // it is convenient to treat it as if a continous function,
75 // and permit non-integral values of k.
76 // To enforce the strict mathematical model, users should use floor or ceil functions
77 // on k outside this function to ensure that k is integral.
78 
79 #ifndef BOOST_MATH_SPECIAL_BINOMIAL_HPP
80 #define BOOST_MATH_SPECIAL_BINOMIAL_HPP
81 
82 #include <boost/math/distributions/fwd.hpp>
83 #include <boost/math/special_functions/beta.hpp> // for incomplete beta.
84 #include <boost/math/distributions/complement.hpp> // complements
85 #include <boost/math/distributions/detail/common_error_handling.hpp> // error checks
86 #include <boost/math/distributions/detail/inv_discrete_quantile.hpp> // error checks
87 #include <boost/math/special_functions/fpclassify.hpp> // isnan.
88 #include <boost/math/tools/roots.hpp> // for root finding.
89 
90 #include <utility>
91 
92 namespace boost
93 {
94   namespace math
95   {
96 
97      template <class RealType, class Policy>
98      class binomial_distribution;
99 
100      namespace binomial_detail{
101         // common error checking routines for binomial distribution functions:
102         template <class RealType, class Policy>
check_N(const char * function,const RealType & N,RealType * result,const Policy & pol)103         inline bool check_N(const char* function, const RealType& N, RealType* result, const Policy& pol)
104         {
105            if((N < 0) || !(boost::math::isfinite)(N))
106            {
107                *result = policies::raise_domain_error<RealType>(
108                   function,
109                   "Number of Trials argument is %1%, but must be >= 0 !", N, pol);
110                return false;
111            }
112            return true;
113         }
114         template <class RealType, class Policy>
check_success_fraction(const char * function,const RealType & p,RealType * result,const Policy & pol)115         inline bool check_success_fraction(const char* function, const RealType& p, RealType* result, const Policy& pol)
116         {
117            if((p < 0) || (p > 1) || !(boost::math::isfinite)(p))
118            {
119                *result = policies::raise_domain_error<RealType>(
120                   function,
121                   "Success fraction argument is %1%, but must be >= 0 and <= 1 !", p, pol);
122                return false;
123            }
124            return true;
125         }
126         template <class RealType, class Policy>
check_dist(const char * function,const RealType & N,const RealType & p,RealType * result,const Policy & pol)127         inline bool check_dist(const char* function, const RealType& N, const RealType& p, RealType* result, const Policy& pol)
128         {
129            return check_success_fraction(
130               function, p, result, pol)
131               && check_N(
132                function, N, result, pol);
133         }
134         template <class RealType, class Policy>
check_dist_and_k(const char * function,const RealType & N,const RealType & p,RealType k,RealType * result,const Policy & pol)135         inline bool check_dist_and_k(const char* function, const RealType& N, const RealType& p, RealType k, RealType* result, const Policy& pol)
136         {
137            if(check_dist(function, N, p, result, pol) == false)
138               return false;
139            if((k < 0) || !(boost::math::isfinite)(k))
140            {
141                *result = policies::raise_domain_error<RealType>(
142                   function,
143                   "Number of Successes argument is %1%, but must be >= 0 !", k, pol);
144                return false;
145            }
146            if(k > N)
147            {
148                *result = policies::raise_domain_error<RealType>(
149                   function,
150                   "Number of Successes argument is %1%, but must be <= Number of Trials !", k, pol);
151                return false;
152            }
153            return true;
154         }
155         template <class RealType, class Policy>
check_dist_and_prob(const char * function,const RealType & N,RealType p,RealType prob,RealType * result,const Policy & pol)156         inline bool check_dist_and_prob(const char* function, const RealType& N, RealType p, RealType prob, RealType* result, const Policy& pol)
157         {
158            if(check_dist(function, N, p, result, pol) && detail::check_probability(function, prob, result, pol) == false)
159               return false;
160            return true;
161         }
162 
163          template <class T, class Policy>
164          T inverse_binomial_cornish_fisher(T n, T sf, T p, T q, const Policy& pol)
165          {
166             BOOST_MATH_STD_USING
167             // mean:
168             T m = n * sf;
169             // standard deviation:
170             T sigma = sqrt(n * sf * (1 - sf));
171             // skewness
172             T sk = (1 - 2 * sf) / sigma;
173             // kurtosis:
174             // T k = (1 - 6 * sf * (1 - sf) ) / (n * sf * (1 - sf));
175             // Get the inverse of a std normal distribution:
176             T x = boost::math::erfc_inv(p > q ? 2 * q : 2 * p, pol) * constants::root_two<T>();
177             // Set the sign:
178             if(p < 0.5)
179                x = -x;
180             T x2 = x * x;
181             // w is correction term due to skewness
182             T w = x + sk * (x2 - 1) / 6;
183             /*
184             // Add on correction due to kurtosis.
185             // Disabled for now, seems to make things worse?
186             //
187             if(n >= 10)
188                w += k * x * (x2 - 3) / 24 + sk * sk * x * (2 * x2 - 5) / -36;
189                */
190             w = m + sigma * w;
191             if(w < tools::min_value<T>())
192                return sqrt(tools::min_value<T>());
193             if(w > n)
194                return n;
195             return w;
196          }
197 
198       template <class RealType, class Policy>
199       RealType quantile_imp(const binomial_distribution<RealType, Policy>& dist, const RealType& p, const RealType& q)
200       { // Quantile or Percent Point Binomial function.
201         // Return the number of expected successes k,
202         // for a given probability p.
203         //
204         // Error checks:
205         BOOST_MATH_STD_USING  // ADL of std names
206         RealType result = 0;
207         RealType trials = dist.trials();
208         RealType success_fraction = dist.success_fraction();
209         if(false == binomial_detail::check_dist_and_prob(
210            "boost::math::quantile(binomial_distribution<%1%> const&, %1%)",
211            trials,
212            success_fraction,
213            p,
214            &result, Policy()))
215         {
216            return result;
217         }
218 
219         // Special cases:
220         //
221         if(p == 0)
222         {  // There may actually be no answer to this question,
223            // since the probability of zero successes may be non-zero,
224            // but zero is the best we can do:
225            return 0;
226         }
227         if(p == 1)
228         {  // Probability of n or fewer successes is always one,
229            // so n is the most sensible answer here:
230            return trials;
231         }
232         if (p <= pow(1 - success_fraction, trials))
233         { // p <= pdf(dist, 0) == cdf(dist, 0)
234           return 0; // So the only reasonable result is zero.
235         } // And root finder would fail otherwise.
236 
237         // Solve for quantile numerically:
238         //
239         RealType guess = binomial_detail::inverse_binomial_cornish_fisher(trials, success_fraction, p, q, Policy());
240         RealType factor = 8;
241         if(trials > 100)
242            factor = 1.01f; // guess is pretty accurate
243         else if((trials > 10) && (trials - 1 > guess) && (guess > 3))
244            factor = 1.15f; // less accurate but OK.
245         else if(trials < 10)
246         {
247            // pretty inaccurate guess in this area:
248            if(guess > trials / 64)
249            {
250               guess = trials / 4;
251               factor = 2;
252            }
253            else
254               guess = trials / 1024;
255         }
256         else
257            factor = 2; // trials largish, but in far tails.
258 
259         typedef typename Policy::discrete_quantile_type discrete_quantile_type;
260         boost::uintmax_t max_iter = policies::get_max_root_iterations<Policy>();
261         return detail::inverse_discrete_quantile(
262             dist,
263             p,
264             q,
265             guess,
266             factor,
267             RealType(1),
268             discrete_quantile_type(),
269             max_iter);
270       } // quantile
271 
272      }
273 
274     template <class RealType = double, class Policy = policies::policy<> >
275     class binomial_distribution
276     {
277     public:
278       typedef RealType value_type;
279       typedef Policy policy_type;
280 
binomial_distribution(RealType n=1,RealType p=0.5)281       binomial_distribution(RealType n = 1, RealType p = 0.5) : m_n(n), m_p(p)
282       { // Default n = 1 is the Bernoulli distribution
283         // with equal probability of 'heads' or 'tails.
284          RealType r;
285          binomial_detail::check_dist(
286             "boost::math::binomial_distribution<%1%>::binomial_distribution",
287             m_n,
288             m_p,
289             &r, Policy());
290       } // binomial_distribution constructor.
291 
success_fraction() const292       RealType success_fraction() const
293       { // Probability.
294         return m_p;
295       }
trials() const296       RealType trials() const
297       { // Total number of trials.
298         return m_n;
299       }
300 
301       enum interval_type{
302          clopper_pearson_exact_interval,
303          jeffreys_prior_interval
304       };
305 
306       //
307       // Estimation of the success fraction parameter.
308       // The best estimate is actually simply successes/trials,
309       // these functions are used
310       // to obtain confidence intervals for the success fraction.
311       //
find_lower_bound_on_p(RealType trials,RealType successes,RealType probability,interval_type t=clopper_pearson_exact_interval)312       static RealType find_lower_bound_on_p(
313          RealType trials,
314          RealType successes,
315          RealType probability,
316          interval_type t = clopper_pearson_exact_interval)
317       {
318         static const char* function = "boost::math::binomial_distribution<%1%>::find_lower_bound_on_p";
319         // Error checks:
320         RealType result = 0;
321         if(false == binomial_detail::check_dist_and_k(
322            function, trials, RealType(0), successes, &result, Policy())
323             &&
324            binomial_detail::check_dist_and_prob(
325            function, trials, RealType(0), probability, &result, Policy()))
326         { return result; }
327 
328         if(successes == 0)
329            return 0;
330 
331         // NOTE!!! The Clopper Pearson formula uses "successes" not
332         // "successes+1" as usual to get the lower bound,
333         // see http://www.itl.nist.gov/div898/handbook/prc/section2/prc241.htm
334         return (t == clopper_pearson_exact_interval) ? ibeta_inv(successes, trials - successes + 1, probability, static_cast<RealType*>(0), Policy())
335            : ibeta_inv(successes + 0.5f, trials - successes + 0.5f, probability, static_cast<RealType*>(0), Policy());
336       }
find_upper_bound_on_p(RealType trials,RealType successes,RealType probability,interval_type t=clopper_pearson_exact_interval)337       static RealType find_upper_bound_on_p(
338          RealType trials,
339          RealType successes,
340          RealType probability,
341          interval_type t = clopper_pearson_exact_interval)
342       {
343         static const char* function = "boost::math::binomial_distribution<%1%>::find_upper_bound_on_p";
344         // Error checks:
345         RealType result = 0;
346         if(false == binomial_detail::check_dist_and_k(
347            function, trials, RealType(0), successes, &result, Policy())
348             &&
349            binomial_detail::check_dist_and_prob(
350            function, trials, RealType(0), probability, &result, Policy()))
351         { return result; }
352 
353         if(trials == successes)
354            return 1;
355 
356         return (t == clopper_pearson_exact_interval) ? ibetac_inv(successes + 1, trials - successes, probability, static_cast<RealType*>(0), Policy())
357            : ibetac_inv(successes + 0.5f, trials - successes + 0.5f, probability, static_cast<RealType*>(0), Policy());
358       }
359       // Estimate number of trials parameter:
360       //
361       // "How many trials do I need to be P% sure of seeing k events?"
362       //    or
363       // "How many trials can I have to be P% sure of seeing fewer than k events?"
364       //
find_minimum_number_of_trials(RealType k,RealType p,RealType alpha)365       static RealType find_minimum_number_of_trials(
366          RealType k,     // number of events
367          RealType p,     // success fraction
368          RealType alpha) // risk level
369       {
370         static const char* function = "boost::math::binomial_distribution<%1%>::find_minimum_number_of_trials";
371         // Error checks:
372         RealType result = 0;
373         if(false == binomial_detail::check_dist_and_k(
374            function, k, p, k, &result, Policy())
375             &&
376            binomial_detail::check_dist_and_prob(
377            function, k, p, alpha, &result, Policy()))
378         { return result; }
379 
380         result = ibetac_invb(k + 1, p, alpha, Policy());  // returns n - k
381         return result + k;
382       }
383 
find_maximum_number_of_trials(RealType k,RealType p,RealType alpha)384       static RealType find_maximum_number_of_trials(
385          RealType k,     // number of events
386          RealType p,     // success fraction
387          RealType alpha) // risk level
388       {
389         static const char* function = "boost::math::binomial_distribution<%1%>::find_maximum_number_of_trials";
390         // Error checks:
391         RealType result = 0;
392         if(false == binomial_detail::check_dist_and_k(
393            function, k, p, k, &result, Policy())
394             &&
395            binomial_detail::check_dist_and_prob(
396            function, k, p, alpha, &result, Policy()))
397         { return result; }
398 
399         result = ibeta_invb(k + 1, p, alpha, Policy());  // returns n - k
400         return result + k;
401       }
402 
403     private:
404         RealType m_n; // Not sure if this shouldn't be an int?
405         RealType m_p; // success_fraction
406       }; // template <class RealType, class Policy> class binomial_distribution
407 
408       typedef binomial_distribution<> binomial;
409       // typedef binomial_distribution<double> binomial;
410       // IS now included since no longer a name clash with function binomial.
411       //typedef binomial_distribution<double> binomial; // Reserved name of type double.
412 
413       template <class RealType, class Policy>
range(const binomial_distribution<RealType,Policy> & dist)414       const std::pair<RealType, RealType> range(const binomial_distribution<RealType, Policy>& dist)
415       { // Range of permissible values for random variable k.
416         using boost::math::tools::max_value;
417         return std::pair<RealType, RealType>(static_cast<RealType>(0), dist.trials());
418       }
419 
420       template <class RealType, class Policy>
support(const binomial_distribution<RealType,Policy> & dist)421       const std::pair<RealType, RealType> support(const binomial_distribution<RealType, Policy>& dist)
422       { // Range of supported values for random variable k.
423         // This is range where cdf rises from 0 to 1, and outside it, the pdf is zero.
424         return std::pair<RealType, RealType>(static_cast<RealType>(0),  dist.trials());
425       }
426 
427       template <class RealType, class Policy>
mean(const binomial_distribution<RealType,Policy> & dist)428       inline RealType mean(const binomial_distribution<RealType, Policy>& dist)
429       { // Mean of Binomial distribution = np.
430         return  dist.trials() * dist.success_fraction();
431       } // mean
432 
433       template <class RealType, class Policy>
variance(const binomial_distribution<RealType,Policy> & dist)434       inline RealType variance(const binomial_distribution<RealType, Policy>& dist)
435       { // Variance of Binomial distribution = np(1-p).
436         return  dist.trials() * dist.success_fraction() * (1 - dist.success_fraction());
437       } // variance
438 
439       template <class RealType, class Policy>
440       RealType pdf(const binomial_distribution<RealType, Policy>& dist, const RealType& k)
441       { // Probability Density/Mass Function.
442         BOOST_FPU_EXCEPTION_GUARD
443 
444         BOOST_MATH_STD_USING // for ADL of std functions
445 
446         RealType n = dist.trials();
447 
448         // Error check:
449         RealType result = 0; // initialization silences some compiler warnings
450         if(false == binomial_detail::check_dist_and_k(
451            "boost::math::pdf(binomial_distribution<%1%> const&, %1%)",
452            n,
453            dist.success_fraction(),
454            k,
455            &result, Policy()))
456         {
457            return result;
458         }
459 
460         // Special cases of success_fraction, regardless of k successes and regardless of n trials.
461         if (dist.success_fraction() == 0)
462         {  // probability of zero successes is 1:
463            return static_cast<RealType>(k == 0 ? 1 : 0);
464         }
465         if (dist.success_fraction() == 1)
466         {  // probability of n successes is 1:
467            return static_cast<RealType>(k == n ? 1 : 0);
468         }
469         // k argument may be integral, signed, or unsigned, or floating point.
470         // If necessary, it has already been promoted from an integral type.
471         if (n == 0)
472         {
473           return 1; // Probability = 1 = certainty.
474         }
475         if (k == 0)
476         { // binomial coeffic (n 0) = 1,
477           // n ^ 0 = 1
478           return pow(1 - dist.success_fraction(), n);
479         }
480         if (k == n)
481         { // binomial coeffic (n n) = 1,
482           // n ^ 0 = 1
483           return pow(dist.success_fraction(), k);  // * pow((1 - dist.success_fraction()), (n - k)) = 1
484         }
485 
486         // Probability of getting exactly k successes
487         // if C(n, k) is the binomial coefficient then:
488         //
489         // f(k; n,p) = C(n, k) * p^k * (1-p)^(n-k)
490         //           = (n!/(k!(n-k)!)) * p^k * (1-p)^(n-k)
491         //           = (tgamma(n+1) / (tgamma(k+1)*tgamma(n-k+1))) * p^k * (1-p)^(n-k)
492         //           = p^k (1-p)^(n-k) / (beta(k+1, n-k+1) * (n+1))
493         //           = ibeta_derivative(k+1, n-k+1, p) / (n+1)
494         //
495         using boost::math::ibeta_derivative; // a, b, x
496         return ibeta_derivative(k+1, n-k+1, dist.success_fraction(), Policy()) / (n+1);
497 
498       } // pdf
499 
500       template <class RealType, class Policy>
cdf(const binomial_distribution<RealType,Policy> & dist,const RealType & k)501       inline RealType cdf(const binomial_distribution<RealType, Policy>& dist, const RealType& k)
502       { // Cumulative Distribution Function Binomial.
503         // The random variate k is the number of successes in n trials.
504         // k argument may be integral, signed, or unsigned, or floating point.
505         // If necessary, it has already been promoted from an integral type.
506 
507         // Returns the sum of the terms 0 through k of the Binomial Probability Density/Mass:
508         //
509         //   i=k
510         //   --  ( n )   i      n-i
511         //   >   |   |  p  (1-p)
512         //   --  ( i )
513         //   i=0
514 
515         // The terms are not summed directly instead
516         // the incomplete beta integral is employed,
517         // according to the formula:
518         // P = I[1-p]( n-k, k+1).
519         //   = 1 - I[p](k + 1, n - k)
520 
521         BOOST_MATH_STD_USING // for ADL of std functions
522 
523         RealType n = dist.trials();
524         RealType p = dist.success_fraction();
525 
526         // Error check:
527         RealType result = 0;
528         if(false == binomial_detail::check_dist_and_k(
529            "boost::math::cdf(binomial_distribution<%1%> const&, %1%)",
530            n,
531            p,
532            k,
533            &result, Policy()))
534         {
535            return result;
536         }
537         if (k == n)
538         {
539           return 1;
540         }
541 
542         // Special cases, regardless of k.
543         if (p == 0)
544         {  // This need explanation:
545            // the pdf is zero for all cases except when k == 0.
546            // For zero p the probability of zero successes is one.
547            // Therefore the cdf is always 1:
548            // the probability of k or *fewer* successes is always 1
549            // if there are never any successes!
550            return 1;
551         }
552         if (p == 1)
553         { // This is correct but needs explanation:
554           // when k = 1
555           // all the cdf and pdf values are zero *except* when k == n,
556           // and that case has been handled above already.
557           return 0;
558         }
559         //
560         // P = I[1-p](n - k, k + 1)
561         //   = 1 - I[p](k + 1, n - k)
562         // Use of ibetac here prevents cancellation errors in calculating
563         // 1-p if p is very small, perhaps smaller than machine epsilon.
564         //
565         // Note that we do not use a finite sum here, since the incomplete
566         // beta uses a finite sum internally for integer arguments, so
567         // we'll just let it take care of the necessary logic.
568         //
569         return ibetac(k + 1, n - k, p, Policy());
570       } // binomial cdf
571 
572       template <class RealType, class Policy>
cdf(const complemented2_type<binomial_distribution<RealType,Policy>,RealType> & c)573       inline RealType cdf(const complemented2_type<binomial_distribution<RealType, Policy>, RealType>& c)
574       { // Complemented Cumulative Distribution Function Binomial.
575         // The random variate k is the number of successes in n trials.
576         // k argument may be integral, signed, or unsigned, or floating point.
577         // If necessary, it has already been promoted from an integral type.
578 
579         // Returns the sum of the terms k+1 through n of the Binomial Probability Density/Mass:
580         //
581         //   i=n
582         //   --  ( n )   i      n-i
583         //   >   |   |  p  (1-p)
584         //   --  ( i )
585         //   i=k+1
586 
587         // The terms are not summed directly instead
588         // the incomplete beta integral is employed,
589         // according to the formula:
590         // Q = 1 -I[1-p]( n-k, k+1).
591         //   = I[p](k + 1, n - k)
592 
593         BOOST_MATH_STD_USING // for ADL of std functions
594 
595         RealType const& k = c.param;
596         binomial_distribution<RealType, Policy> const& dist = c.dist;
597         RealType n = dist.trials();
598         RealType p = dist.success_fraction();
599 
600         // Error checks:
601         RealType result = 0;
602         if(false == binomial_detail::check_dist_and_k(
603            "boost::math::cdf(binomial_distribution<%1%> const&, %1%)",
604            n,
605            p,
606            k,
607            &result, Policy()))
608         {
609            return result;
610         }
611 
612         if (k == n)
613         { // Probability of greater than n successes is necessarily zero:
614           return 0;
615         }
616 
617         // Special cases, regardless of k.
618         if (p == 0)
619         {
620            // This need explanation: the pdf is zero for all
621            // cases except when k == 0.  For zero p the probability
622            // of zero successes is one.  Therefore the cdf is always
623            // 1: the probability of *more than* k successes is always 0
624            // if there are never any successes!
625            return 0;
626         }
627         if (p == 1)
628         {
629           // This needs explanation, when p = 1
630           // we always have n successes, so the probability
631           // of more than k successes is 1 as long as k < n.
632           // The k == n case has already been handled above.
633           return 1;
634         }
635         //
636         // Calculate cdf binomial using the incomplete beta function.
637         // Q = 1 -I[1-p](n - k, k + 1)
638         //   = I[p](k + 1, n - k)
639         // Use of ibeta here prevents cancellation errors in calculating
640         // 1-p if p is very small, perhaps smaller than machine epsilon.
641         //
642         // Note that we do not use a finite sum here, since the incomplete
643         // beta uses a finite sum internally for integer arguments, so
644         // we'll just let it take care of the necessary logic.
645         //
646         return ibeta(k + 1, n - k, p, Policy());
647       } // binomial cdf
648 
649       template <class RealType, class Policy>
quantile(const binomial_distribution<RealType,Policy> & dist,const RealType & p)650       inline RealType quantile(const binomial_distribution<RealType, Policy>& dist, const RealType& p)
651       {
652          return binomial_detail::quantile_imp(dist, p, RealType(1-p));
653       } // quantile
654 
655       template <class RealType, class Policy>
656       RealType quantile(const complemented2_type<binomial_distribution<RealType, Policy>, RealType>& c)
657       {
658          return binomial_detail::quantile_imp(c.dist, RealType(1-c.param), c.param);
659       } // quantile
660 
661       template <class RealType, class Policy>
mode(const binomial_distribution<RealType,Policy> & dist)662       inline RealType mode(const binomial_distribution<RealType, Policy>& dist)
663       {
664          BOOST_MATH_STD_USING // ADL of std functions.
665          RealType p = dist.success_fraction();
666          RealType n = dist.trials();
667          return floor(p * (n + 1));
668       }
669 
670       template <class RealType, class Policy>
median(const binomial_distribution<RealType,Policy> & dist)671       inline RealType median(const binomial_distribution<RealType, Policy>& dist)
672       { // Bounds for the median of the negative binomial distribution
673         // VAN DE VEN R. ; WEBER N. C. ;
674         // Univ. Sydney, school mathematics statistics, Sydney N.S.W. 2006, AUSTRALIE
675         // Metrika  (Metrika)  ISSN 0026-1335   CODEN MTRKA8
676         // 1993, vol. 40, no3-4, pp. 185-189 (4 ref.)
677 
678         // Bounds for median and 50 percetage point of binomial and negative binomial distribution
679         // Metrika, ISSN   0026-1335 (Print) 1435-926X (Online)
680         // Volume 41, Number 1 / December, 1994, DOI   10.1007/BF01895303
681          BOOST_MATH_STD_USING // ADL of std functions.
682          RealType p = dist.success_fraction();
683          RealType n = dist.trials();
684          // Wikipedia says one of floor(np) -1, floor (np), floor(np) +1
685          return floor(p * n); // Chose the middle value.
686       }
687 
688       template <class RealType, class Policy>
skewness(const binomial_distribution<RealType,Policy> & dist)689       inline RealType skewness(const binomial_distribution<RealType, Policy>& dist)
690       {
691          BOOST_MATH_STD_USING // ADL of std functions.
692          RealType p = dist.success_fraction();
693          RealType n = dist.trials();
694          return (1 - 2 * p) / sqrt(n * p * (1 - p));
695       }
696 
697       template <class RealType, class Policy>
kurtosis(const binomial_distribution<RealType,Policy> & dist)698       inline RealType kurtosis(const binomial_distribution<RealType, Policy>& dist)
699       {
700          RealType p = dist.success_fraction();
701          RealType n = dist.trials();
702          return 3 - 6 / n + 1 / (n * p * (1 - p));
703       }
704 
705       template <class RealType, class Policy>
kurtosis_excess(const binomial_distribution<RealType,Policy> & dist)706       inline RealType kurtosis_excess(const binomial_distribution<RealType, Policy>& dist)
707       {
708          RealType p = dist.success_fraction();
709          RealType q = 1 - p;
710          RealType n = dist.trials();
711          return (1 - 6 * p * q) / (n * p * q);
712       }
713 
714     } // namespace math
715   } // namespace boost
716 
717 // This include must be at the end, *after* the accessors
718 // for this distribution have been defined, in order to
719 // keep compilers that support two-phase lookup happy.
720 #include <boost/math/distributions/detail/derived_accessors.hpp>
721 
722 #endif // BOOST_MATH_SPECIAL_BINOMIAL_HPP
723 
724 
725