← Back to branch summary

~ubuntu-branches/debian/sid/boost1.49/sid

« back to all changes in this revision

Viewing changes to libs/math/doc/sf_and_dist/distributions/negative_binomial_example.qbk

  • Committer: Package Import Robot
  • Author(s): Steve M. Robbins
  • Date: 2012-02-26 00:31:44 UTC
  • Revision ID: package-import@ubuntu.com-20120226003144-eaytp12cbf6ubpms
Tags: upstream-1.49.0
Import upstream version 1.49.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/math/doc/sf_and_dist/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