3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Complements are supported too - and when to use them</title>
5 <link rel="stylesheet" href="../../../math.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../../../index.html" title="Math Toolkit 2.11.0">
8 <link rel="up" href="../overview.html" title="Overview of Statistical Distributions">
9 <link rel="prev" href="generic.html" title="Generic operations common to all distributions are non-member functions">
10 <link rel="next" href="parameters.html" title="Parameters can be calculated">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="generic.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.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="parameters.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h4 class="title">
27 <a name="math_toolkit.stat_tut.overview.complements"></a><a class="link" href="complements.html" title="Complements are supported too - and when to use them">Complements
28 are supported too - and when to use them</a>
29 </h4></div></div></div>
31 Often you don't want the value of the CDF, but its complement, which is
32 to say <code class="computeroutput"><span class="number">1</span><span class="special">-</span><span class="identifier">p</span></code> rather than <code class="computeroutput"><span class="identifier">p</span></code>.
33 It is tempting to calculate the CDF and subtract it from <code class="computeroutput"><span class="number">1</span></code>, but if <code class="computeroutput"><span class="identifier">p</span></code>
34 is very close to <code class="computeroutput"><span class="number">1</span></code> then cancellation
35 error will cause you to lose accuracy, perhaps totally.
38 <a class="link" href="complements.html#why_complements">See below <span class="emphasis"><em>"Why and when
39 to use complements?"</em></span></a>
42 In this library, whenever you want to receive a complement, just wrap all
43 the function arguments in a call to <code class="computeroutput"><span class="identifier">complement</span><span class="special">(...)</span></code>, for example:
45 <pre class="programlisting"><span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
46 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"CDF at t = 1 is "</span> <span class="special"><<</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">1.0</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
47 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Complement of CDF at t = 1 is "</span> <span class="special"><<</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">1.0</span><span class="special">))</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
50 But wait, now that we have a complement, we have to be able to use it as
51 well. Any function that accepts a probability as an argument can also accept
52 a complement by wrapping all of its arguments in a call to <code class="computeroutput"><span class="identifier">complement</span><span class="special">(...)</span></code>,
55 <pre class="programlisting"><span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="number">5</span><span class="special">);</span>
57 <span class="keyword">for</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">1e10</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">*=</span> <span class="number">10</span><span class="special">)</span>
58 <span class="special">{</span>
59 <span class="comment">// Calculate the quantile for a 1 in i chance:</span>
60 <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="number">1</span><span class="special">/</span><span class="identifier">i</span><span class="special">));</span>
61 <span class="comment">// Print it out:</span>
62 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Quantile of students-t with 5 degrees of freedom\n"</span>
63 <span class="string">"for a 1 in "</span> <span class="special"><<</span> <span class="identifier">i</span> <span class="special"><<</span> <span class="string">" chance is "</span> <span class="special"><<</span> <span class="identifier">t</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
64 <span class="special">}</span>
66 <div class="tip"><table border="0" summary="Tip">
68 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
69 <th align="left">Tip</th>
71 <tr><td align="left" valign="top">
73 <span class="bold"><strong>Critical values are just quantiles</strong></span>
76 Some texts talk about quantiles, or percentiles or fractiles, others
77 about critical values, the basic rule is:
80 <span class="emphasis"><em>Lower critical values</em></span> are the same as the quantile.
83 <span class="emphasis"><em>Upper critical values</em></span> are the same as the quantile
84 from the complement of the probability.
87 For example, suppose we have a Bernoulli process, giving rise to a binomial
88 distribution with success ratio 0.1 and 100 trials in total. The <span class="emphasis"><em>lower
89 critical value</em></span> for a probability of 0.05 is given by:
92 <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="number">0.1</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span></code>
95 and the <span class="emphasis"><em>upper critical value</em></span> is given by:
98 <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="number">0.1</span><span class="special">),</span> <span class="number">0.05</span><span class="special">))</span></code>
101 which return 4.82 and 14.63 respectively.
105 <a name="why_complements"></a><div class="tip"><table border="0" summary="Tip">
107 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
108 <th align="left">Tip</th>
110 <tr><td align="left" valign="top">
112 <span class="bold"><strong>Why bother with complements anyway?</strong></span>
115 It's very tempting to dispense with complements, and simply subtract
116 the probability from 1 when required. However, consider what happens
117 when the probability is very close to 1: let's say the probability expressed
118 at float precision is <code class="computeroutput"><span class="number">0.999999940f</span></code>,
119 then <code class="computeroutput"><span class="number">1</span> <span class="special">-</span>
120 <span class="number">0.999999940f</span> <span class="special">=</span>
121 <span class="number">5.96046448e-008</span></code>, but the result
122 is actually accurate to just <span class="emphasis"><em>one single bit</em></span>: the
123 only bit that didn't cancel out!
126 Or to look at this another way: consider that we want the risk of falsely
127 rejecting the null-hypothesis in the Student's t test to be 1 in 1 billion,
128 for a sample size of 10,000. This gives a probability of 1 - 10<sup>-9</sup>, which
129 is exactly 1 when calculated at float precision. In this case calculating
130 the quantile from the complement neatly solves the problem, so for example:
133 <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">students_t</span><span class="special">(</span><span class="number">10000</span><span class="special">),</span> <span class="number">1e-9</span><span class="special">))</span></code>
136 returns the expected t-statistic <code class="computeroutput"><span class="number">6.00336</span></code>,
140 <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">students_t</span><span class="special">(</span><span class="number">10000</span><span class="special">),</span> <span class="number">1</span><span class="special">-</span><span class="number">1e-9f</span><span class="special">)</span></code>
143 raises an overflow error, since it is the same as:
146 <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">students_t</span><span class="special">(</span><span class="number">10000</span><span class="special">),</span> <span class="number">1</span><span class="special">)</span></code>
149 Which has no finite result.
152 With all distributions, even for more reasonable probability (unless
153 the value of p can be represented exactly in the floating-point type)
154 the loss of accuracy quickly becomes significant if you simply calculate
155 probability from 1 - p (because it will be mostly garbage digits for
159 So always avoid, for example, using a probability near to unity like
163 <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">my_distribution</span><span class="special">,</span>
164 <span class="number">0.99999</span><span class="special">)</span></code>
170 <code class="computeroutput"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">my_distribution</span><span class="special">,</span>
171 <span class="number">0.00001</span><span class="special">))</span></code>
174 since 1 - 0.99999 is not exactly equal to 0.00001 when using floating-point
178 This assumes that the 0.00001 value is either a constant, or can be computed
179 by some manner other than subtracting 0.99999 from 1.
184 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
185 <td align="left"></td>
186 <td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
187 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
188 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
189 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
190 Daryle Walker and Xiaogang Zhang<p>
191 Distributed under the Boost Software License, Version 1.0. (See accompanying
192 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>)
197 <div class="spirit-nav">
198 <a accesskey="p" href="generic.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../overview.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="parameters.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>