ceph/src/boost/libs/math/doc/distributions/negative_binomial_example.qbk

   1 [section:neg_binom_eg Negative Binomial Distribution Examples]
   2
   3 (See also the reference documentation for the __negative_binomial_distrib.)
   4
   5 [section:neg_binom_conf Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution]
   6
   7 Imagine you have a process that follows a negative binomial distribution:
   8 for each trial conducted, an event either occurs or does it does not, referred
   9 to as "successes" and "failures". The frequency with which successes occur
  10 is variously referred to as the
  11 success fraction, success ratio, success percentage, occurrence frequency, or probability of occurrence.
  12
  13 If, by experiment, you want to measure the
  14  the best estimate of success fraction is given simply
  15 by /k/ \/ /N/, for /k/ successes out of /N/ trials.
  16
  17 However our confidence in that estimate will be shaped by how many trials were conducted,
  18 and how many successes were observed.  The static member functions
  19 `negative_binomial_distribution<>::find_lower_bound_on_p` and
  20 `negative_binomial_distribution<>::find_upper_bound_on_p`
  21 allow you to calculate the confidence intervals for your estimate of the success fraction.
  22
  23 The sample program [@../../example/neg_binom_confidence_limits.cpp
  24 neg_binom_confidence_limits.cpp] illustrates their use.
  25
  26 [import ../../example/neg_binom_confidence_limits.cpp]
  27
  28 [neg_binomial_confidence_limits]
  29 Let's see some sample output for a 1 in 10
  30 success ratio, first for a mere 20 trials:
  31
  32 [pre'''______________________________________________
  33 2-Sided Confidence Limits For Success Fraction
  34 ______________________________________________
  35 Number of trials                         =  20
  36 Number of successes                      =  2
  37 Number of failures                       =  18
  38 Observed frequency of occurrence         =  0.1
  39 ___________________________________________
  40 Confidence        Lower          Upper
  41  Value (%)        Limit          Limit
  42 ___________________________________________
  43     50.000        0.04812        0.13554
  44     75.000        0.03078        0.17727
  45     90.000        0.01807        0.22637
  46     95.000        0.01235        0.26028
  47     99.000        0.00530        0.33111
  48     99.900        0.00164        0.41802
  49     99.990        0.00051        0.49202
  50     99.999        0.00016        0.55574
  51 ''']
  52
  53 As you can see, even at the 95% confidence level the bounds (0.012 to 0.26) are
  54 really very wide, and very asymmetric about the observed value 0.1.
  55
  56 Compare that with the program output for a mass
  57 2000 trials:
  58
  59 [pre'''______________________________________________
  60 2-Sided Confidence Limits For Success Fraction
  61 ______________________________________________
  62 Number of trials                         =  2000
  63 Number of successes                      =  200
  64 Number of failures                       =  1800
  65 Observed frequency of occurrence         =  0.1
  66 ___________________________________________
  67 Confidence        Lower          Upper
  68  Value (%)        Limit          Limit
  69 ___________________________________________
  70     50.000        0.09536        0.10445
  71     75.000        0.09228        0.10776
  72     90.000        0.08916        0.11125
  73     95.000        0.08720        0.11352
  74     99.000        0.08344        0.11802
  75     99.900        0.07921        0.12336
  76     99.990        0.07577        0.12795
  77     99.999        0.07282        0.13206
  78 ''']
  79
  80 Now even when the confidence level is very high, the limits (at 99.999%, 0.07 to 0.13) are really
  81 quite close and nearly symmetric to the observed value of 0.1.
  82
  83 [endsect][/section:neg_binom_conf Calculating Confidence Limits on the Frequency of Occurrence]
  84
  85 [section:neg_binom_size_eg Estimating Sample Sizes for the Negative Binomial.]
  86
  87 Imagine you have an event
  88 (let's call it a "failure" - though we could equally well call it a success if we felt it was a 'good' event)
  89 that you know will occur in 1 in N trials.  You may want to know how many trials you need to
  90 conduct to be P% sure of observing at least k such failures.
  91 If the failure events follow a negative binomial
  92 distribution (each trial either succeeds or fails)
  93 then the static member function `negative_binomial_distibution<>::find_minimum_number_of_trials`
  94 can be used to estimate the minimum number of trials required to be P% sure
  95 of observing the desired number of failures.
  96
  97 The example program
  98 [@../../example/neg_binomial_sample_sizes.cpp neg_binomial_sample_sizes.cpp]
  99 demonstrates its usage.
 100
 101 [import ../../example/neg_binomial_sample_sizes.cpp]
 102 [neg_binomial_sample_sizes]
 103
 104 [note Since we're calculating the /minimum/ number of trials required,
 105 we'll err on the safe side and take the ceiling of the result.
 106 Had we been calculating the
 107 /maximum/ number of trials permitted to observe less than a certain
 108 number of /failures/ then we would have taken the floor instead.  We
 109 would also have called `find_minimum_number_of_trials` like this:
 110 ``
 111    floor(negative_binomial::find_minimum_number_of_trials(failures, p, alpha[i]))
 112 ``
 113 which would give us the largest number of trials we could conduct and
 114 still be P% sure of observing /failures or less/ failure events, when the
 115 probability of success is /p/.]
 116
 117 We'll finish off by looking at some sample output, firstly suppose
 118 we wish to observe at least 5 "failures" with a 50/50 (0.5) chance of
 119 success or failure:
 120
 121 [pre
 122 '''Target number of failures = 5,   Success fraction = 50%
 123
 124 ____________________________
 125 Confidence        Min Number
 126  Value (%)        Of Trials
 127 ____________________________
 128     50.000          11
 129     75.000          14
 130     90.000          17
 131     95.000          18
 132     99.000          22
 133     99.900          27
 134     99.990          31
 135     99.999          36
 136 '''
 137 ]
 138
 139 So 18 trials or more would yield a 95% chance that at least our 5
 140 required failures would be observed.
 141
 142 Compare that to what happens if the success ratio is 90%:
 143
 144 [pre'''Target number of failures = 5.000,   Success fraction = 90.000%
 145
 146 ____________________________
 147 Confidence        Min Number
 148  Value (%)        Of Trials
 149 ____________________________
 150     50.000          57
 151     75.000          73
 152     90.000          91
 153     95.000         103
 154     99.000         127
 155     99.900         159
 156     99.990         189
 157     99.999         217
 158 ''']
 159
 160 So now 103 trials are required to observe at least 5 failures with
 161 95% certainty.
 162
 163 [endsect] [/section:neg_binom_size_eg Estimating Sample Sizes.]
 164
 165 [section:negative_binomial_example1 Negative Binomial Sales Quota Example.]
 166
 167 This example program
 168 [@../../example/negative_binomial_example1.cpp negative_binomial_example1.cpp (full source code)]
 169 demonstrates a simple use to find the probability of meeting a sales quota.
 170
 171 [import ../../example/negative_binomial_example1.cpp]
 172 [negative_binomial_eg1_1]
 173 [negative_binomial_eg1_2]
 174
 175 [endsect] [/section:negative_binomial_example1]
 176
 177 [section:negative_binomial_example2 Negative Binomial Table Printing Example.]
 178 Example program showing output of a table of values of cdf and pdf for various k failures.
 179 [import ../../example/negative_binomial_example2.cpp]
 180 [neg_binomial_example2]
 181 [neg_binomial_example2_1]
 182 [endsect] [/section:negative_binomial_example1 Negative Binomial example 2.]
 183
 184 [endsect] [/section:neg_binom_eg Negative Binomial Distribution Examples]
 185
 186 [/
 187   Copyright 2006 John Maddock and Paul A. Bristow.
 188   Distributed under the Boost Software License, Version 1.0.
 189   (See accompanying file LICENSE_1_0.txt or copy at
 190   http://www.boost.org/LICENSE_1_0.txt).
 191 ]
 192