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

From: pbristow_at_[hidden]
Date: 2007-08-05 10:05:27

Author: pbristow
Date: 2007-08-05 10:05:22 EDT (Sun, 05 Aug 2007)
New Revision: 38449
URL: http://svn.boost.org/trac/boost/changeset/38449

Log:
update to use Quickbook in C++ system
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/distributions/negative_binomial_example.qbk |   171 ++++++++++++--------------------------- 
   1 files changed, 55 insertions(+), 116 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-05 10:05:22 EDT (Sun, 05 Aug 2007)
@@ -6,140 +6,79 @@
 
 Imagine you have a process that follows a negative binomial distribution:
 for each trial conducted, an event either occurs or does it does not, referred
-to as "successes" and "failures".  If, by experiment, you want to measure the
-frequency with which successes occur, the best estimate of success fraction is given simply
-by /k/ \/ /N/, for /k/ successes out of /N/ trials.  However our confidence in that
-estimate will be shaped by how many trials were conducted, and how many successes
-were observed.  The static member functions 
-`negative_binomial_distribution<>::estimate_lower_bound_on_p` and
-`negative_binomial_distribution<>::estimate_upper_bound_on_p` allow you to calculate
-the confidence intervals for your estimate of the occurrence frequency.
+to as "successes" and "failures". The frequency with which successes occur
+is variously referred to as the
+success fraction, success ratio, success percentage, occurrence frequency, or probability of occurrence.
+
+If, by experiment, you want to measure the
+ the best estimate of success fraction is given simply
+by /k/ \/ /N/, for /k/ successes out of /N/ trials.
+
+However our confidence in that estimate will be shaped by how many trials were conducted,
+and how many successes were observed.  The static member functions 
+`negative_binomial_distribution<>::find_lower_bound_on_p` and
+`negative_binomial_distribution<>::find_upper_bound_on_p`
+allow you to calculate the confidence intervals for your estimate of the success fraction.
 
 The sample program [@../../example/neg_binomial_confidence_limits.cpp 
-neg_binomial_confidence_limits.cpp] illustrates their use.  It begins by defining
-a procedure that will print a table of confidence limits for various degrees
-of certainty:
-
-   #include <iostream>
-   #include <iomanip>
-   #include <boost/math/distributions/negative_binomial.hpp>
-
-   void confidence_limits_on_frequency(unsigned trials, unsigned successes)
-   {
-      //
-      // trials = Total number of trials.
-      // successes = Total number of observed successes.
-      //
-      // Calculate confidence limits for an observed
-      // frequency of occurrence that follows a negative binomial
-      // distribution.
-      //
-      using namespace std;
-      using namespace boost::math;
-
-      // Print out general info:
-      cout <<
-         "___________________________________________\n"
-         "2-Sided Confidence Limits For Success Ratio\n"
-         "___________________________________________\n\n";
-      cout << setprecision(7);
-      cout << setw(40) << left << "Number of Observations" << "=  " << trials << "\n";
-      cout << setw(40) << left << "Number of successes" << "=  " << successes << "\n";
-      cout << setw(40) << left << "Sample frequency of occurrence" << "=  " << double(successes) / trials << "\n";
-
-The procedure now defines a table of significance levels: these are the 
-probabilities that the true occurrence frequency lies outside the calculated
-interval:
-
-      double alpha[] = { 0.5, 0.25, 0.1, 0.05, 0.01, 0.001, 0.0001, 0.00001 };
-
-Some pretty printing of the table header follows:
-
-      cout << "\n\n"
-              "___________________________________________\n"
-              "Confidence        Lower          Upper\n"
-              " Value (%)        Limit          Limit\n"
-              "___________________________________________\n";
-
-
-And now for the important part - the intervals themselves - for each
-value of /alpha/, we call `estimate_lower_bound_on_p` and 
-`estimate_upper_bound_on_p` to obtain lower and upper bounds
-respectively.  Note that since we are calculating a two-sided interval,
-we must divide the value of alpha in two.  Had we been calculating a 
-single-sided interval, for example: ['"Calculate a lower bound so that we are P%
-sure that the true occurrence frequency is greater than some value"]
-then we would *not* have divided by two.
-
-      for(unsigned i = 0; i < sizeof(alpha)/sizeof(alpha[0]); ++i)
-      {
-         // Confidence value:
-         cout << fixed << setprecision(3) << setw(10) << right << 100 * (1-alpha[i]);
-         // calculate bounds:
-         double l = binomial::estimate_lower_bound_on_p(trials, successes, alpha[i]/2);
-         double u = binomial::estimate_upper_bound_on_p(trials, successes, alpha[i]/2);
-         // Print Limits:
-         cout << fixed << setprecision(5) << setw(15) << right << l;
-         cout << fixed << setprecision(5) << setw(15) << right << u << endl;
-      }
-      cout << endl;
-   }
-
-And that's all there is to it.  Let's see some sample output for a 1 in 10
-success ratio, first for 20 trials:
-
-[pre'''___________________________________________
-2-Sided Confidence Limits For Success Ratio
-___________________________________________
-
-Number of Observations                  =  20
-Number of successes                     =  2
-Sample frequency of occurrence          =  0.1
+neg_binomial_confidence_limits.cpp] illustrates their use.
 
+[import ../../example/neg_binomial_confidence_limits.cpp]
 
+[neg_binomial_confidence_limits]
+Let's see some sample output for a 1 in 10
+success ratio, first for a mere 20 trials:
+
+[pre'''______________________________________________
+2-Sided Confidence Limits For Success Fraction
+______________________________________________
+Number of trials                         =  20
+Number of successes                      =  2
+Number of failures                       =  18
+Observed frequency of occurrence         =  0.1
 ___________________________________________
 Confidence        Lower          Upper
  Value (%)        Limit          Limit
 ___________________________________________
-    50.000        0.08701        0.18675
-    75.000        0.06229        0.23163
-    90.000        0.04217        0.28262
-    95.000        0.03207        0.31698
-    99.000        0.01764        0.38713
-    99.900        0.00786        0.47093
-    99.990        0.00358        0.54084
-    99.999        0.00165        0.60020
+    50.000        0.04812        0.13554
+    75.000        0.03078        0.17727
+    90.000        0.01807        0.22637
+    95.000        0.01235        0.26028
+    99.000        0.00530        0.33111
+    99.900        0.00164        0.41802
+    99.990        0.00051        0.49202
+    99.999        0.00016        0.55574
 ''']
 
-As you can see, even at the 95% confidence level the bounds are
-really quite wide.  Compare that with the program output for
-2000 trials:
-
-[pre'''___________________________________________
-2-Sided Confidence Limits For Success Ratio
-___________________________________________
-
-Number of Observations                  =  2000
-Number of successes                     =  200
-Sample frequency of occurrence          =  0.1000000
+As you can see, even at the 95% confidence level the bounds (0.012 to 0.26) are
+really very wide, and very asymmetric about the observed value 0.1.
 
+Compare that with the program output for a mass
+2000 trials:
 
+[pre'''______________________________________________
+2-Sided Confidence Limits For Success Fraction
+______________________________________________
+Number of trials                         =  2000
+Number of successes                      =  200
+Number of failures                       =  1800
+Observed frequency of occurrence         =  0.1
 ___________________________________________
 Confidence        Lower          Upper
  Value (%)        Limit          Limit
 ___________________________________________
-    50.000        0.09585        0.10491
-    75.000        0.09277        0.10822
-    90.000        0.08963        0.11172
-    95.000        0.08767        0.11399
-    99.000        0.08390        0.11850
-    99.900        0.07966        0.12385
-    99.990        0.07621        0.12845
-    99.999        0.07325        0.13256
+    50.000        0.09536        0.10445
+    75.000        0.09228        0.10776
+    90.000        0.08916        0.11125
+    95.000        0.08720        0.11352
+    99.000        0.08344        0.11802
+    99.900        0.07921        0.12336
+    99.990        0.07577        0.12795
+    99.999        0.07282        0.13206
 ''']
 
-Now even when the confidence level is very high, the limits are really
-quite close to the experimentally calculated value of 0.1.
+Now even when the confidence level is very high, the limits (at 99.999%, 0.07 to 0.13) are really
+quite close and nearly symmetric to the observed value of 0.1.
 
 [endsect][/section:neg_binom_conf Calculating Confidence Limits on the Frequency of Occurrence]