[Boost-commit] svn:boost r38476 - sandbox/math_toolkit/libs/math/doc/distributions

From: pbristow_at_[hidden]
Date: 2007-08-06 11:35:17

Author: pbristow
Date: 2007-08-06 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	2007-08-06 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 pretty-printing, 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 * (1-alpha[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]