
BoostCommit : 
From: pbristow_at_[hidden]
Date: 20070805 10:05:27
Author: pbristow
Date: 20070805 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 20070805 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"
 "2Sided 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 twosided interval,
we must divide the value of alpha in two. Had we been calculating a
singlesided 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 * (1alpha[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'''___________________________________________
2Sided 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'''______________________________________________
+2Sided 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'''___________________________________________
2Sided 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'''______________________________________________
+2Sided 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]
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