| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Negative Binomial Distribution</title> |
| <link rel="stylesheet" href="../../../../../../../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.74.0"> |
| <link rel="home" href="../../../../index.html" title="Math Toolkit"> |
| <link rel="up" href="../dists.html" title="Distributions"> |
| <link rel="prev" href="lognormal_dist.html" title="Log Normal Distribution"> |
| <link rel="next" href="nc_beta_dist.html" title="Noncentral Beta Distribution"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../../boost.png"></td> |
| <td align="center"><a href="../../../../../../../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../../../../../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../../../../../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="lognormal_dist.html"><img src="../../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nc_beta_dist.html"><img src="../../../../../../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section" lang="en"> |
| <div class="titlepage"><div><div><h5 class="title"> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist"></a><a class="link" href="negative_binomial_dist.html" title="Negative Binomial Distribution"> |
| Negative Binomial Distribution</a> |
| </h5></div></div></div> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">negative_binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></pre> |
| <p> |
| </p> |
| <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> |
| |
| <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span> |
| <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Policies">Policy</a> <span class="special">=</span> <a class="link" href="../../../policy/pol_ref/pol_ref_ref.html" title="Policy Class Reference">policies::policy<></a> <span class="special">></span> |
| <span class="keyword">class</span> <span class="identifier">negative_binomial_distribution</span><span class="special">;</span> |
| |
| <span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><></span> <span class="identifier">negative_binomial</span><span class="special">;</span> |
| |
| <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Policies">Policy</a><span class="special">></span> |
| <span class="keyword">class</span> <span class="identifier">negative_binomial_distribution</span> |
| <span class="special">{</span> |
| <span class="keyword">public</span><span class="special">:</span> |
| <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span> |
| <span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span> |
| <span class="comment">// Constructor from successes and success_fraction: |
| </span> <span class="identifier">negative_binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span> |
| |
| <span class="comment">// Parameter accessors: |
| </span> <span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> |
| <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> |
| |
| <span class="comment">// Bounds on success fraction: |
| </span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha |
| </span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// alpha |
| </span> |
| <span class="comment">// Estimate min/max number of trials: |
| </span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// Number of failures. |
| </span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// Success fraction. |
| </span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha. |
| </span> <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// Number of failures. |
| </span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// Success fraction. |
| </span> <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">);</span> <span class="comment">// Probability threshold alpha. |
| </span><span class="special">};</span> |
| |
| <span class="special">}}</span> <span class="comment">// namespaces |
| </span></pre> |
| <p> |
| The class type <code class="computeroutput"><span class="identifier">negative_binomial_distribution</span></code> |
| represents a <a href="http://en.wikipedia.org/wiki/Negative_binomial_distribution" target="_top">negative_binomial |
| distribution</a>: it is used when there are exactly two mutually |
| exclusive outcomes of a <a href="http://en.wikipedia.org/wiki/Bernoulli_trial" target="_top">Bernoulli |
| trial</a>: these outcomes are labelled "success" and "failure". |
| </p> |
| <p> |
| For k + r Bernoulli trials each with success fraction p, the negative_binomial |
| distribution gives the probability of observing k failures and r successes |
| with success on the last trial. The negative_binomial distribution assumes |
| that success_fraction p is fixed for all (k + r) trials. |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| The random variable for the negative binomial distribution is the number |
| of trials, (the number of successes is a fixed property of the distribution) |
| whereas for the binomial, the random variable is the number of successes, |
| for a fixed number of trials. |
| </p></td></tr> |
| </table></div> |
| <p> |
| It has the PDF: |
| </p> |
| <p> |
| <span class="inlinemediaobject"><img src="../../../../../equations/neg_binomial_ref.png"></span> |
| </p> |
| <p> |
| The following graph illustrate how the PDF varies as the success fraction |
| <span class="emphasis"><em>p</em></span> changes: |
| </p> |
| <p> |
| <span class="inlinemediaobject"><img src="../../../../../graphs/negative_binomial_pdf_1.png" align="middle"></span> |
| </p> |
| <p> |
| Alternatively, this graph shows how the shape of the PDF varies as the |
| number of successes changes: |
| </p> |
| <p> |
| <span class="inlinemediaobject"><img src="../../../../../graphs/negative_binomial_pdf_2.png" align="middle"></span> |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.related_distributions"></a><h5> |
| <a name="id1038389"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.related_distributions">Related |
| Distributions</a> |
| </h5> |
| <p> |
| The name negative binomial distribution is reserved by some to the case |
| where the successes parameter r is an integer. This integer version is |
| also called the <a href="http://mathworld.wolfram.com/PascalDistribution.html" target="_top">Pascal |
| distribution</a>. |
| </p> |
| <p> |
| This implementation uses real numbers for the computation throughout |
| (because it uses the <span class="bold"><strong>real-valued</strong></span> incomplete |
| beta function family of functions). This real-valued version is also |
| called the Polya Distribution. |
| </p> |
| <p> |
| The Poisson distribution is a generalization of the Pascal distribution, |
| where the success parameter r is an integer: to obtain the Pascal distribution |
| you must ensure that an integer value is provided for r, and take integer |
| values (floor or ceiling) from functions that return a number of successes. |
| </p> |
| <p> |
| For large values of r (successes), the negative binomial distribution |
| converges to the Poisson distribution. |
| </p> |
| <p> |
| The geometric distribution is a special case where the successes parameter |
| r = 1, so only a first and only success is required. geometric(p) = negative_binomial(1, |
| p). |
| </p> |
| <p> |
| The Poisson distribution is a special case for large successes |
| </p> |
| <p> |
| poisson(λ) = lim <sub>r → ∞</sub> ​ negative_binomial(r, r / (λ + r))) |
| </p> |
| <p> |
| </p> |
| <div class="caution"><table border="0" summary="Caution"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../doc/src/images/caution.png"></td> |
| <th align="left">Caution</th> |
| </tr> |
| <tr><td align="left" valign="top"> |
| <p> |
| The Negative Binomial distribution is a discrete distribution: internally |
| functions like the <code class="computeroutput"><span class="identifier">cdf</span></code> |
| and <code class="computeroutput"><span class="identifier">pdf</span></code> are treated |
| "as if" they are continuous functions, but in reality the |
| results returned from these functions only have meaning if an integer |
| value is provided for the random variate argument. |
| </p> |
| <p> |
| The quantile function will by default return an integer result that |
| has been <span class="emphasis"><em>rounded outwards</em></span>. That is to say lower |
| quantiles (where the probability is less than 0.5) are rounded downward, |
| and upper quantiles (where the probability is greater than 0.5) are |
| rounded upwards. This behaviour ensures that if an X% quantile is |
| requested, then <span class="emphasis"><em>at least</em></span> the requested coverage |
| will be present in the central region, and <span class="emphasis"><em>no more than</em></span> |
| the requested coverage will be present in the tails. |
| </p> |
| <p> |
| This behaviour can be changed so that the quantile functions are |
| rounded differently, or even return a real-valued result using <a class="link" href="../../../policy/pol_overview.html" title="Policy Overview">Policies</a>. It is |
| strongly recommended that you read the tutorial <a class="link" href="../../../policy/pol_tutorial/understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding |
| Quantiles of Discrete Distributions</a> before using the quantile |
| function on the Negative Binomial distribution. The <a class="link" href="../../../policy/pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference |
| docs</a> describe how to change the rounding policy for these |
| distributions. |
| </p> |
| </td></tr> |
| </table></div> |
| <p> |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.member_functions"></a><h5> |
| <a name="id1038500"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.member_functions">Member |
| Functions</a> |
| </h5> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.construct"></a><h6> |
| <a name="id1038513"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.construct">Construct</a> |
| </h6> |
| <pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">);</span> |
| </pre> |
| <p> |
| Constructor: <span class="emphasis"><em>r</em></span> is the total number of successes, |
| <span class="emphasis"><em>p</em></span> is the probability of success of a single trial. |
| </p> |
| <p> |
| Requires: <code class="computeroutput"><span class="identifier">r</span> <span class="special">></span> |
| <span class="number">0</span></code> and <code class="computeroutput"><span class="number">0</span> |
| <span class="special"><=</span> <span class="identifier">p</span> |
| <span class="special"><=</span> <span class="number">1</span></code>. |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accessors"></a><h6> |
| <a name="id1038622"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accessors">Accessors</a> |
| </h6> |
| <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">success_fraction</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// successes / trials (0 <= p <= 1) |
| </span></pre> |
| <p> |
| Returns the parameter <span class="emphasis"><em>p</em></span> from which this distribution |
| was constructed. |
| </p> |
| <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="comment">// required successes (r > 0) |
| </span></pre> |
| <p> |
| Returns the parameter <span class="emphasis"><em>r</em></span> from which this distribution |
| was constructed. |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p"></a><h6> |
| <a name="id1038707"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.lower_bound_on_parameter_p">Lower |
| Bound on Parameter p</a> |
| </h6> |
| <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_lower_bound_on_p</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">failures</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">probability</span><span class="special">)</span> <span class="comment">// (0 <= alpha <= 1), 0.05 equivalent to 95% confidence. |
| </span></pre> |
| <p> |
| Returns a <span class="bold"><strong>lower bound</strong></span> on the success |
| fraction: |
| </p> |
| <div class="variablelist"> |
| <p class="title"><b></b></p> |
| <dl> |
| <dt><span class="term">failures</span></dt> |
| <dd><p> |
| The total number of failures before the r th success. |
| </p></dd> |
| <dt><span class="term">successes</span></dt> |
| <dd><p> |
| The number of successes required. |
| </p></dd> |
| <dt><span class="term">alpha</span></dt> |
| <dd><p> |
| The largest acceptable probability that the true value of the success |
| fraction is <span class="bold"><strong>less than</strong></span> the value |
| returned. |
| </p></dd> |
| </dl> |
| </div> |
| <p> |
| For example, if you observe <span class="emphasis"><em>k</em></span> failures and <span class="emphasis"><em>r</em></span> |
| successes from <span class="emphasis"><em>n</em></span> = k + r trials the best estimate |
| for the success fraction is simply <span class="emphasis"><em>r/n</em></span>, but if you |
| want to be 95% sure that the true value is <span class="bold"><strong>greater |
| than</strong></span> some value, <span class="emphasis"><em>p<sub>min</sub></em></span>, then: |
| </p> |
| <pre class="programlisting"><span class="identifier">p</span><sub>min</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</span><span class="identifier">find_lower_bound_on_p</span><span class="special">(</span> |
| <span class="identifier">failures</span><span class="special">,</span> <span class="identifier">successes</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span> |
| </pre> |
| <p> |
| <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See |
| negative binomial confidence interval example.</a> |
| </p> |
| <p> |
| This function uses the Clopper-Pearson method of computing the lower |
| bound on the success fraction, whilst many texts refer to this method |
| as giving an "exact" result in practice it produces an interval |
| that guarantees <span class="emphasis"><em>at least</em></span> the coverage required, |
| and may produce pessimistic estimates for some combinations of <span class="emphasis"><em>failures</em></span> |
| and <span class="emphasis"><em>successes</em></span>. See: |
| </p> |
| <p> |
| <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong |
| Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some |
| Discrete Distributions. Computational statistics and data analysis, 2005, |
| vol. 48, no3, 605-621</a>. |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p"></a><h6> |
| <a name="id1038975"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.upper_bound_on_parameter_p">Upper |
| Bound on Parameter p</a> |
| </h6> |
| <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_upper_bound_on_p</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">trials</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">successes</span><span class="special">,</span> |
| <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// (0 <= alpha <= 1), 0.05 equivalent to 95% confidence. |
| </span></pre> |
| <p> |
| Returns an <span class="bold"><strong>upper bound</strong></span> on the success |
| fraction: |
| </p> |
| <div class="variablelist"> |
| <p class="title"><b></b></p> |
| <dl> |
| <dt><span class="term">trials</span></dt> |
| <dd><p> |
| The total number of trials conducted. |
| </p></dd> |
| <dt><span class="term">successes</span></dt> |
| <dd><p> |
| The number of successes that occurred. |
| </p></dd> |
| <dt><span class="term">alpha</span></dt> |
| <dd><p> |
| The largest acceptable probability that the true value of the success |
| fraction is <span class="bold"><strong>greater than</strong></span> the value |
| returned. |
| </p></dd> |
| </dl> |
| </div> |
| <p> |
| For example, if you observe <span class="emphasis"><em>k</em></span> successes from <span class="emphasis"><em>n</em></span> |
| trials the best estimate for the success fraction is simply <span class="emphasis"><em>k/n</em></span>, |
| but if you want to be 95% sure that the true value is <span class="bold"><strong>less |
| than</strong></span> some value, <span class="emphasis"><em>p<sub>max</sub></em></span>, then: |
| </p> |
| <pre class="programlisting"><span class="identifier">p</span><sub>max</sub> <span class="special">=</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</span><span class="identifier">find_upper_bound_on_p</span><span class="special">(</span> |
| <span class="identifier">r</span><span class="special">,</span> <span class="identifier">k</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span> |
| </pre> |
| <p> |
| <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_conf.html" title="Calculating Confidence Limits on the Frequency of Occurrence for the Negative Binomial Distribution">See |
| negative binomial confidence interval example.</a> |
| </p> |
| <p> |
| This function uses the Clopper-Pearson method of computing the lower |
| bound on the success fraction, whilst many texts refer to this method |
| as giving an "exact" result in practice it produces an interval |
| that guarantees <span class="emphasis"><em>at least</em></span> the coverage required, |
| and may produce pessimistic estimates for some combinations of <span class="emphasis"><em>failures</em></span> |
| and <span class="emphasis"><em>successes</em></span>. See: |
| </p> |
| <p> |
| <a href="http://www.ucs.louisiana.edu/~kxk4695/Discrete_new.pdf" target="_top">Yong |
| Cai and K. Krishnamoorthy, A Simple Improved Inferential Method for Some |
| Discrete Distributions. Computational statistics and data analysis, 2005, |
| vol. 48, no3, 605-621</a>. |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_at_least_a_certain_number_of_failures"></a><h6> |
| <a name="id1039239"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_at_least_a_certain_number_of_failures">Estimating |
| Number of Trials to Ensure at Least a Certain Number of Failures</a> |
| </h6> |
| <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of failures. |
| </span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction. |
| </span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%). |
| </span></pre> |
| <p> |
| This functions estimates the number of trials required to achieve a certain |
| probability that <span class="bold"><strong>more than k failures will be observed</strong></span>. |
| </p> |
| <div class="variablelist"> |
| <p class="title"><b></b></p> |
| <dl> |
| <dt><span class="term">k</span></dt> |
| <dd><p> |
| The target number of failures to be observed. |
| </p></dd> |
| <dt><span class="term">p</span></dt> |
| <dd><p> |
| The probability of <span class="emphasis"><em>success</em></span> for each trial. |
| </p></dd> |
| <dt><span class="term">alpha</span></dt> |
| <dd><p> |
| The maximum acceptable risk that only k failures or fewer will |
| be observed. |
| </p></dd> |
| </dl> |
| </div> |
| <p> |
| For example: |
| </p> |
| <pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</span><span class="identifier">find_minimum_number_of_trials</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">0.5</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span> |
| </pre> |
| <p> |
| Returns the smallest number of trials we must conduct to be 95% sure |
| of seeing 10 failures that occur with frequency one half. |
| </p> |
| <p> |
| <a class="link" href="../../stat_tut/weg/neg_binom_eg/neg_binom_size_eg.html" title="Estimating Sample Sizes for the Negative Binomial.">Worked |
| Example.</a> |
| </p> |
| <p> |
| This function uses numeric inversion of the negative binomial distribution |
| to obtain the result: another interpretation of the result, is that it |
| finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span> |
| probability of observing k failures or fewer. |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_a_maximum_number_of_failures_or_less"></a><h6> |
| <a name="id1039463"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.estimating_number_of_trials_to_ensure_a_maximum_number_of_failures_or_less">Estimating |
| Number of Trials to Ensure a Maximum Number of Failures or Less</a> |
| </h6> |
| <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span> |
| <span class="identifier">RealType</span> <span class="identifier">k</span><span class="special">,</span> <span class="comment">// number of failures. |
| </span> <span class="identifier">RealType</span> <span class="identifier">p</span><span class="special">,</span> <span class="comment">// success fraction. |
| </span> <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">);</span> <span class="comment">// probability threshold (0.05 equivalent to 95%). |
| </span></pre> |
| <p> |
| This functions estimates the maximum number of trials we can conduct |
| and achieve a certain probability that <span class="bold"><strong>k failures |
| or fewer will be observed</strong></span>. |
| </p> |
| <div class="variablelist"> |
| <p class="title"><b></b></p> |
| <dl> |
| <dt><span class="term">k</span></dt> |
| <dd><p> |
| The maximum number of failures to be observed. |
| </p></dd> |
| <dt><span class="term">p</span></dt> |
| <dd><p> |
| The probability of <span class="emphasis"><em>success</em></span> for each trial. |
| </p></dd> |
| <dt><span class="term">alpha</span></dt> |
| <dd><p> |
| The maximum acceptable <span class="emphasis"><em>risk</em></span> that more than |
| k failures will be observed. |
| </p></dd> |
| </dl> |
| </div> |
| <p> |
| For example: |
| </p> |
| <pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special"><</span><span class="identifier">RealType</span><span class="special">>::</span><span class="identifier">find_maximum_number_of_trials</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">1.0</span><span class="special">-</span><span class="number">1.0</span><span class="special">/</span><span class="number">1000000</span><span class="special">,</span> <span class="number">0.05</span><span class="special">);</span> |
| </pre> |
| <p> |
| Returns the largest number of trials we can conduct and still be 95% |
| sure of seeing no failures that occur with frequency one in one million. |
| </p> |
| <p> |
| This function uses numeric inversion of the negative binomial distribution |
| to obtain the result: another interpretation of the result, is that it |
| finds the number of trials (success+failures) that will lead to an <span class="emphasis"><em>alpha</em></span> |
| probability of observing more than k failures. |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.non_member_accessors"></a><h5> |
| <a name="id1039695"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.non_member_accessors">Non-member |
| Accessors</a> |
| </h5> |
| <p> |
| All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member |
| accessor functions</a> that are generic to all distributions are supported: |
| <a class="link" href="../nmp.html#math.dist.cdf">Cumulative Distribution Function</a>, |
| <a class="link" href="../nmp.html#math.dist.pdf">Probability Density Function</a>, <a class="link" href="../nmp.html#math.dist.quantile">Quantile</a>, <a class="link" href="../nmp.html#math.dist.hazard">Hazard |
| Function</a>, <a class="link" href="../nmp.html#math.dist.chf">Cumulative Hazard Function</a>, |
| <a class="link" href="../nmp.html#math.dist.mean">mean</a>, <a class="link" href="../nmp.html#math.dist.median">median</a>, |
| <a class="link" href="../nmp.html#math.dist.mode">mode</a>, <a class="link" href="../nmp.html#math.dist.variance">variance</a>, |
| <a class="link" href="../nmp.html#math.dist.sd">standard deviation</a>, <a class="link" href="../nmp.html#math.dist.skewness">skewness</a>, |
| <a class="link" href="../nmp.html#math.dist.kurtosis">kurtosis</a>, <a class="link" href="../nmp.html#math.dist.kurtosis_excess">kurtosis_excess</a>, |
| <a class="link" href="../nmp.html#math.dist.range">range</a> and <a class="link" href="../nmp.html#math.dist.support">support</a>. |
| </p> |
| <p> |
| However it's worth taking a moment to define what these actually mean |
| in the context of this distribution: |
| </p> |
| <div class="table"> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.meaning_of_the_non_member_accessors_"></a><p class="title"><b>Table 12. Meaning of the non-member accessors.</b></p> |
| <div class="table-contents"><table class="table" summary="Meaning of the non-member accessors."> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Function |
| </p> |
| </th> |
| <th> |
| <p> |
| Meaning |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="../nmp.html#math.dist.pdf">Probability Density Function</a> |
| </p> |
| </td> |
| <td> |
| <p> |
| The probability of obtaining <span class="bold"><strong>exactly |
| k failures</strong></span> from k+r trials with success fraction |
| p. For example: |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="identifier">pdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre> |
| <p> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="../nmp.html#math.dist.cdf">Cumulative Distribution Function</a> |
| </p> |
| </td> |
| <td> |
| <p> |
| The probability of obtaining <span class="bold"><strong>k failures |
| or fewer</strong></span> from k+r trials with success fraction p |
| and success on the last trial. For example: |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">)</span></pre> |
| <p> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="../nmp.html#math.dist.ccdf">Complement of the Cumulative |
| Distribution Function</a> |
| </p> |
| </td> |
| <td> |
| <p> |
| The probability of obtaining <span class="bold"><strong>more than |
| k failures</strong></span> from k+r trials with success fraction |
| p and success on the last trial. For example: |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">k</span><span class="special">))</span></pre> |
| <p> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="../nmp.html#math.dist.quantile">Quantile</a> |
| </p> |
| </td> |
| <td> |
| <p> |
| The <span class="bold"><strong>greatest</strong></span> number of failures |
| k expected to be observed from k+r trials with success fraction |
| p, at probability P. Note that the value returned is a real-number, |
| and not an integer. Depending on the use case you may want |
| to take either the floor or ceiling of the real result. For |
| example: |
| </p> |
| <p> |
| |
| </p> |
| <pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">)</span></pre> |
| <p> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <a class="link" href="../nmp.html#math.dist.quantile_c">Quantile from the complement |
| of the probability</a> |
| </p> |
| </td> |
| <td> |
| <p> |
| The <span class="bold"><strong>smallest</strong></span> number of failures |
| k expected to be observed from k+r trials with success fraction |
| p, at probability P. Note that the value returned is a real-number, |
| and not an integer. Depending on the use case you may want |
| to take either the floor or ceiling of the real result. For |
| example: |
| </p> |
| <pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">p</span><span class="special">),</span> <span class="identifier">P</span><span class="special">))</span></pre> |
| <p> |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"><a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accuracy"></a><h5> |
| <a name="id1041456"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.accuracy">Accuracy</a> |
| </h5> |
| <p> |
| This distribution is implemented using the incomplete beta functions |
| <a class="link" href="../../../special/sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibeta</a> |
| and <a class="link" href="../../../special/sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibetac</a>: |
| please refer to these functions for information on accuracy. |
| </p> |
| <a name="math_toolkit.dist.dist_ref.dists.negative_binomial_dist.implementation"></a><h5> |
| <a name="id1041482"></a> |
| <a class="link" href="negative_binomial_dist.html#math_toolkit.dist.dist_ref.dists.negative_binomial_dist.implementation">Implementation</a> |
| </h5> |
| <p> |
| In the following table, <span class="emphasis"><em>p</em></span> is the probability that |
| any one trial will be successful (the success fraction), <span class="emphasis"><em>r</em></span> |
| is the number of successes, <span class="emphasis"><em>k</em></span> is the number of failures, |
| <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>. |
| </p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| Function |
| </p> |
| </th> |
| <th> |
| <p> |
| Implementation Notes |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| pdf |
| </p> |
| </td> |
| <td> |
| <p> |
| pdf = exp(lgamma(r + k) - lgamma(r) - lgamma(k+1)) * pow(p, |
| r) * pow((1-p), k) |
| </p> |
| <p> |
| Implementation is in terms of <a class="link" href="../../../special/sf_beta/beta_derivative.html" title="Derivative of the Incomplete Beta Function">ibeta_derivative</a>: |
| </p> |
| <p> |
| (p/(r + k)) * ibeta_derivative(r, static_cast<RealType>(k+1), |
| p) The function <a class="link" href="../../../special/sf_beta/beta_derivative.html" title="Derivative of the Incomplete Beta Function">ibeta_derivative</a> |
| is used here, since it has already been optimised for the lowest |
| possible error - indeed this is really just a thin wrapper |
| around part of the internals of the incomplete beta function. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| cdf |
| </p> |
| </td> |
| <td> |
| <p> |
| Using the relation: |
| </p> |
| <p> |
| cdf = I<sub>p</sub>(r, k+1) = ibeta(r, k+1, p) |
| </p> |
| <p> |
| = ibeta(r, static_cast<RealType>(k+1), p) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| cdf complement |
| </p> |
| </td> |
| <td> |
| <p> |
| Using the relation: |
| </p> |
| <p> |
| 1 - cdf = I<sub>p</sub>(k+1, r) |
| </p> |
| <p> |
| = ibetac(r, static_cast<RealType>(k+1), p) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| quantile |
| </p> |
| </td> |
| <td> |
| <p> |
| ibeta_invb(r, p, P) - 1 |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| quantile from the complement |
| </p> |
| </td> |
| <td> |
| <p> |
| ibetac_invb(r, p, Q) -1) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| mean |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="identifier">r</span><span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span></code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| variance |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="identifier">r</span> <span class="special">(</span><span class="number">1</span><span class="special">-</span><span class="identifier">p</span><span class="special">)</span> |
| <span class="special">/</span> <span class="identifier">p</span> |
| <span class="special">*</span> <span class="identifier">p</span></code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| mode |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="identifier">floor</span><span class="special">((</span><span class="identifier">r</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> |
| <span class="special">*</span> <span class="special">(</span><span class="number">1</span> <span class="special">-</span> |
| <span class="identifier">p</span><span class="special">)/</span><span class="identifier">p</span><span class="special">)</span></code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| skewness |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="special">(</span><span class="number">2</span> |
| <span class="special">-</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span> |
| <span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">r</span> <span class="special">*</span> |
| <span class="special">(</span><span class="number">1</span> |
| <span class="special">-</span> <span class="identifier">p</span><span class="special">))</span></code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| kurtosis |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="number">6</span> <span class="special">/</span> |
| <span class="identifier">r</span> <span class="special">+</span> |
| <span class="special">(</span><span class="identifier">p</span> |
| <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span> |
| <span class="identifier">r</span> <span class="special">*</span> |
| <span class="special">(</span><span class="number">1</span> |
| <span class="special">-</span> <span class="identifier">p</span> |
| <span class="special">)</span></code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| kurtosis excess |
| </p> |
| </td> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="number">6</span> <span class="special">/</span> |
| <span class="identifier">r</span> <span class="special">+</span> |
| <span class="special">(</span><span class="identifier">p</span> |
| <span class="special">*</span> <span class="identifier">p</span><span class="special">)</span> <span class="special">/</span> |
| <span class="identifier">r</span> <span class="special">*</span> |
| <span class="special">(</span><span class="number">1</span> |
| <span class="special">-</span> <span class="identifier">p</span> |
| <span class="special">)</span> <span class="special">-</span><span class="number">3</span></code> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| parameter estimation member functions |
| </p> |
| </td> |
| <td> |
| <p> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="identifier">find_lower_bound_on_p</span></code> |
| </p> |
| </td> |
| <td> |
| <p> |
| ibeta_inv(successes, failures + 1, alpha) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="identifier">find_upper_bound_on_p</span></code> |
| </p> |
| </td> |
| <td> |
| <p> |
| ibetac_inv(successes, failures, alpha) plus see comments in |
| code. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="identifier">find_minimum_number_of_trials</span></code> |
| </p> |
| </td> |
| <td> |
| <p> |
| ibeta_inva(k + 1, p, alpha) |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| <code class="computeroutput"><span class="identifier">find_maximum_number_of_trials</span></code> |
| </p> |
| </td> |
| <td> |
| <p> |
| ibetac_inva(k + 1, p, alpha) |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p> |
| Implementation notes: |
| </p> |
| <div class="itemizedlist"><ul type="disc"> |
| <li> |
| The real concept type (that deliberately lacks the Lanczos approximation), |
| was found to take several minutes to evaluate some extreme test values, |
| so the test has been disabled for this type. |
| </li> |
| <li> |
| Much greater speed, and perhaps greater accuracy, might be achieved |
| for extreme values by using a normal approximation. This is NOT been |
| tested or implemented. |
| </li> |
| </ul></div> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2006 , 2007, 2008, 2009, 2010 John Maddock, Paul A. Bristow, |
| Hubert Holin, Xiaogang Zhang, Bruno Lalande, Johan Råde, Gautam Sewani and |
| Thijs van den Berg<p> |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="lognormal_dist.html"><img src="../../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nc_beta_dist.html"><img src="../../../../../../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |
