
BoostCommit : 
From: pbristow_at_[hidden]
Date: 20070806 11:35:17
Author: pbristow
Date: 20070806 11:35:08 EDT (Mon, 06 Aug 2007)
New Revision: 38476
URL: http://svn.boost.org/trac/boost/changeset/38476
Log:
Added /corrected sample sizes example.
Text files modified:
sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk  78 ++++++++++
1 files changed, 21 insertions(+), 57 deletions()
Modified: sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk
==============================================================================
 sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk 20070806 11:35:08 EDT (Mon, 06 Aug 2007)
@@ 84,73 +84,38 @@
[section:neg_binom_size_eg Estimating Sample Sizes for the Negative Binomial.]
Imagine you have an event (let's call it a "failure") that you know will
occur in 1 in N trials. You may want to know how many trials you need to
conduct to be 100P% sure of observing at least k such failures.
+Imagine you have an event
+(let's call it a "failure"  though we could equally well call it a success if we felt it was a 'good' event)
+that you know will occur in 1 in N trials. You may want to know how many trials you need to
+conduct to be P% sure of observing at least k such failures.
If the failure events follow a negative binomial
distribution (each trial either succeeds or does not)
then the static member function `negative_binomial_distibution<>::estimate_minimum_number_of_trials`
can be used to estimate the minimum number of trials required to be 100P% sure
+distribution (each trial either succeeds or fails)
+then the static member function `negative_binomial_distibution<>::find_minimum_number_of_trials`
+can be used to estimate the minimum number of trials required to be P% sure
of observing the desired number of failures.
The example program
[@../../example/neg_binomial_sample_sizes.cpp neg_binomial_sample_sizes.cpp]
demonstrates its usage. It centres around a routine that prints out
a table of minimum sample sizes for various probability thresholds:
+demonstrates its usage.
 void estimate_max_sample_size(
 double p, // success fraction.
 unsigned failures) // Total number of observed failures required.
 {

The routine then declares a table of probability thresholds: these are the
maximum acceptable probability that /failure/ or fewer events will be
observed.

 double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };

Much of the rest of the program is prettyprinting, the important part
is in the calculation of minimum number of trials required for each
value of alpha:

 cout << "\n""Target number of failures = " << failures;
 cout << ", Success fraction = " << 100 * p << "%" << endl;

 // Print table header:
 cout << "\n\n"
 "____________________________\n"
 "Confidence Min Number\n"
 " Value (%) Of Trials \n"
 "____________________________\n";

 // Now print out the data for the table rows.
 for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
 {
 // Confidence values %:
 cout << fixed << setprecision(3) << setw(10) << right << 100 * (1alpha[i]) << " "
 // estimate_minimum_number_of_trials
 << setw(6) << right
 << ceil(negative_binomial::estimate_minimum_number_of_trials(
 failures, p, alpha[i])) << endl;
 }
 cout << endl;

Note that since we're
calculating the /minimum/ number of trials required, we'll err on the safe
side and take the ceiling of the result. Had we been calculating the
+[import ../../example/neg_binomial_sample_sizes.cpp]
+[neg_binomial_sample_sizes]
+
+[note Since we're calculating the /minimum/ number of trials required,
+we'll err on the safe side and take the ceiling of the result.
+Had we been calculating the
/maximum/ number of trials permitted to observe less than a certain
number of /failures/ then we would have taken the floor instead. We
would also have called `estimate_maximum_number_of_trials` like this:

 floor(negative_binomial::estimate_maximum_number_of_trials(
 failures, p, alpha[i]))

+would also have called `find_minimum_number_of_trials` like this:
+``
+ floor(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]))
+``
which would give us the largest number of trials we could conduct and
still be 100P% sure of observing /failures or less/ failure events, when the
probability of success is /p/.
+still be P% sure of observing /failures or less/ failure events, when the
+probability of success is /p/.]
We'll finish off by looking at some sample output, firstly suppose
we wish to observe at least 5 "failures" with a 50/50 chance of
+we wish to observe at least 5 "failures" with a 50/50 (0.5) chance of
success or failure:
[pre
@@ 195,7 +160,6 @@
So now 103 trials are required to observe at least 5 failures with
95% certainty.

[endsect][/section:neg_binom_size_eg Estimating Sample Sizes.]
[endsect][/section:neg_binom_eg Negative Binomial Distribution Examples]
BoostCommit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk