Boost logo

Boost-Commit :

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]
 


Boost-Commit 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