#include <boost/math/distributions/binomial.hpp>
namespace boost{ namespace math{ template <class RealType = double, class Policy = policies::policy<> > class binomial_distribution; typedef binomial_distribution<> binomial; template <class RealType, class Policy> class binomial_distribution { public: typedef RealType value_type; typedef Policy policy_type; static const unspecified-type cloppper_pearson_exact_interval; static const unspecified-type jeffreys_prior_interval; // construct: binomial_distribution(RealType n, RealType p); // parameter access:: RealType success_fraction() const; RealType trials() const; // Bounds on success fraction: static RealType find_lower_bound_on_p( RealType trials, RealType successes, RealType probability, unspecified-type method = clopper_pearson_exact_interval); static RealType find_upper_bound_on_p( RealType trials, RealType successes, RealType probability, unspecified-type method = clopper_pearson_exact_interval); // estimate min/max number of trials: static RealType find_minimum_number_of_trials( RealType k, // number of events RealType p, // success fraction RealType alpha); // risk level static RealType find_maximum_number_of_trials( RealType k, // number of events RealType p, // success fraction RealType alpha); // risk level }; }} // namespaces
The class type
The PDF for the binomial distribution is given by:
The following two graphs illustrate how the PDF changes depending upon the distributions parameters, first we'll keep the success fraction p fixed at 0.5, and vary the sample size:
Alternatively, we can keep the sample size fixed at N=20 and vary the success fraction p:
Member FunctionsConstructbinomial_distribution(RealType n, RealType p); Constructor: n is the total number of trials, p is the probability of success of a single trial.
Requires AccessorsRealType success_fraction() const; Returns the parameter p from which this distribution was constructed. RealType trials() const; Returns the parameter n from which this distribution was constructed. Lower Bound on the Success Fractionstatic RealType find_lower_bound_on_p( RealType trials, RealType successes, RealType alpha, unspecified-type method = clopper_pearson_exact_interval); Returns a lower bound on the success fraction:
For example, if you observe k successes from n trials the best estimate for the success fraction is simply k/n, but if you want to be 95% sure that the true value is greater than some value, pmin, then: pmin = binomial_distribution<RealType>::find_lower_bound_on_p( n, k, 0.05);
There are currently two possible values available for the method
optional parameter: clopper_pearson_exact_interval
or jeffreys_prior_interval. These constants are
both members of class template p = binomial_distribution<RealType>::find_lower_bound_on_p( n, k, 0.05, binomial_distribution<RealType>::jeffreys_prior_interval);
The default method if this parameter is not specified is the Clopper
Pearson "exact" interval. This produces an interval that guarantees
at least
The alternative calculation method produces a non-informative Jeffreys
Prior interval. It produces Please note that the "textbook" calculation method using a normal approximation (the Wald interval) is deliberately not provided: it is known to produce consistently poor results, even when the sample size is surprisingly large. Refer to Brown, Cai and DasGupta for a full explanation. Many other methods of calculation are available, and may be more appropriate for specific situations. Unfortunately there appears to be no consensus amongst statisticians as to which is "best": refer to the discussion at the end of Brown, Cai and DasGupta for examples. The two methods provided here were chosen principally because they can be used for both one and two sided intervals. See also: Lawrence D. Brown, T. Tony Cai and Anirban DasGupta (2001), Interval Estimation for a Binomial Proportion, Statistical Science, Vol. 16, No. 2, 101-133. T. Tony Cai (2005), One-sided confidence intervals in discrete distributions, Journal of Statistical Planning and Inference 131, 63-88. Agresti, A. and Coull, B. A. (1998). Approximate is better than "exact" for interval estimation of binomial proportions. Amer. Statist. 52 119-126. Clopper, C. J. and Pearson, E. S. (1934). The use of confidence or fiducial limits illustrated in the case of the binomial. Biometrika 26 404-413. Upper Bound on the Success Fractionstatic RealType find_upper_bound_on_p( RealType trials, RealType successes, RealType alpha, unspecified-type method = clopper_pearson_exact_interval); Returns an upper bound on the success fraction:
For example, if you observe k successes from n trials the best estimate for the success fraction is simply k/n, but if you want to be 95% sure that the true value is less than some value, pmax, then: pmax = binomial_distribution<RealType>::find_upper_bound_on_p( n, k, 0.05);
Estimating the Number of Trials Required for a Certain Number of Successesstatic RealType find_minimum_number_of_trials( RealType k, // number of events RealType p, // success fraction RealType alpha); // probability threshold This function estimates the minimum number of trials required to ensure that more than k events is observed with a level of risk alpha that k or fewer events occur.
For example: binomial_distribution<RealType>::find_number_of_trials(10, 0.5, 0.05); Returns the smallest number of trials we must conduct to be 95% sure of seeing 10 events that occur with frequency one half. Estimating the Maximum Number of Trials to Ensure no more than a Certain Number of Successesstatic RealType find_maximum_number_of_trials( RealType k, // number of events RealType p, // success fraction RealType alpha); // probability threshold This function estimates the maximum number of trials we can conduct to ensure that k successes or fewer are observed, with a risk alpha that more than k occur.
For example: binomial_distribution<RealType>::find_maximum_number_of_trials(0, 1e-6, 0.05); Returns the largest number of trials we can conduct and still be 95% certain of not observing any events that occur with one in a million frequency. This is typically used in failure analysis. Non-member AccessorsAll the usual non-member accessor functions that are generic to all distributions are supported: Cumulative Distribution Function, Probability Density Function, Quantile, Hazard Function, Cumulative Hazard Function, mean, median, mode, variance, standard deviation, skewness, kurtosis, kurtosis_excess, range and support.
The domain for the random variable k is It's worth taking a moment to define what these accessors actually mean in the context of this distribution: Table?11.?Meaning of the non-member accessors
ExamplesVarious worked examples are available illustrating the use of the binomial distribution. AccuracyThis distribution is implemented using the incomplete beta functions ibeta and ibetac, please refer to these functions for information on accuracy. ImplementationIn the following table p is the probability that one trial will be successful (the success fraction), n is the number of trials, k is the number of successes, p is the probability and q = 1-p.
References |