[Boost-commit] svn:boost r38477 - sandbox/math_toolkit/libs/math/example

From: pbristow_at_[hidden]
Date: 2007-08-06 11:36:32

Author: pbristow
Date: 2007-08-06 11:36:31 EDT (Mon, 06 Aug 2007)
New Revision: 38477
URL: http://svn.boost.org/trac/boost/changeset/38477

Log:
Docs in code added for sample sizes example
Text files modified: 
   sandbox/math_toolkit/libs/math/example/neg_binomial_sample_sizes.cpp |    60 ++++++++++++++++++++++++++++++++--------
   1 files changed, 48 insertions(+), 12 deletions(-)

Modified: sandbox/math_toolkit/libs/math/example/neg_binomial_sample_sizes.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/neg_binomial_sample_sizes.cpp	(original)
+++ sandbox/math_toolkit/libs/math/example/neg_binomial_sample_sizes.cpp	2007-08-06 11:36:31 EDT (Mon, 06 Aug 2007)
@@ -1,3 +1,5 @@
+// neg_binomial_sample_sizes.cpp
+
 // Copyright Paul A. Bristow 2007
 // Copyright John Maddock 2006
 // Use, modification and distribution are subject to the
@@ -7,10 +9,12 @@
 
 #include <boost/math/distributions/negative_binomial.hpp>
 using boost::math::negative_binomial;
-  // RealType find_number_of_trials(
-  // RealType k,     // number of failures, k >= 0.
-  // RealType p,     // success fraction 0 <= p <= 1.
-  // RealType probability) // probability threshold 0 <= p <= 0.
+
+// Default RealType is double so this permits use of:
+double find_minimum_number_of_trials(
+double k,     // number of failures (events), k >= 0.
+double p,     // fraction of trails for which event occurs, 0 <= p <= 1.
+double probability); // probability threshold, 0 <= probability <= 1.
 
 #include <iostream>
 using std::cout;
@@ -21,18 +25,46 @@
 using std::setprecision;
 using std::setw; 
 
+//[neg_binomial_sample_sizes
+
+/*`
+It centres around a routine that prints out
+a table of minimum sample sizes for various probability thresholds:
+*/
+  void find_number_of_trials(double failures, double p);
+/*`
+First define a table of significance levels: 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 };
+/*`
+Confidence value as % is (1 - alpha) * 100, so alpha 0.05 == 95% confidence
+that the desired number of failures will be observed.
+
+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 using:
+
+  (int)ceil(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]);
+
+*/
+
+/*`
+
+find_minimum_number_of_trials returns a double,
+so ceil rounds this up to ensure we have an integral minimum number of trials.
+
+*/
+  
 void find_number_of_trials(double failures, double p)
 {
    // trials = number of trials
    // failures = number of failures before achieving required success(es).
-   // p         = success ratio.
+   // p        = success fraction (0 <= p <= 1.).
    //
    // Calculate how many trials we need to ensure the
    // required number of failures DOES exceed "failures".
 
-   // Define a table of significance levels:
-   double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
-
   cout << "\n""Target number of failures = " << failures;
   cout << ",   Success fraction = " << 100 * p << "%" << endl;
    // Print table header:
@@ -41,16 +73,20 @@
            "Confidence        Min Number\n"
            " Value (%)        Of Trials \n"
            "____________________________\n";
-   // Now print out the data for the table rows.
+   // Now print out the data for the alpha table values.
   for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
    { // Confidence values %:
       cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]) << "      "
       // find_minimum_number_of_trials
-      << setw(6) << right << (int)ceil(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i])) << endl;
+      << setw(6) << right
+      << (int)ceil(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]))
+      << endl;
    }
    cout << endl;
-} // void find_number_of_trials(double fails, double p)
+} // void find_number_of_trials(double failures, double p)
 
+/*` finally we can produce some tables of minimum trials for the chosen confidence levels:
+*/
 
 int main()
 {
@@ -64,6 +100,7 @@
     return 0;
 } // int main()
 
+//]  [/neg_binomial_sample_sizes.cpp end of Quickbook in C++ markup]
 
 /*
 
@@ -162,5 +199,4 @@
     99.990          25
     99.999          28
 
-
 */