1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Discrete Quantile Policies</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.12.0"> 8<link rel="up" href="../pol_ref.html" title="Policy Reference"> 9<link rel="prev" href="assert_undefined.html" title="Mathematically Undefined Function Policies"> 10<link rel="next" href="precision_pol.html" title="Precision Policies"> 11</head> 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> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="assert_undefined.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.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="precision_pol.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="math_toolkit.pol_ref.discrete_quant_ref"></a><a class="link" href="discrete_quant_ref.html" title="Discrete Quantile Policies">Discrete Quantile 28 Policies</a> 29</h3></div></div></div> 30<p> 31 If a statistical distribution is <span class="emphasis"><em>discrete</em></span> then the random 32 variable can only have integer values - this leaves us with a problem when 33 calculating quantiles - we can either ignore the discreteness of the distribution 34 and return a real value, or we can round to an integer. As it happens, computing 35 integer values can be substantially faster than calculating a real value, 36 so there are definite advantages to returning an integer, but we do then 37 need to decide how best to round the result. The <code class="computeroutput"><span class="identifier">discrete_quantile</span></code> 38 policy defines how discrete quantiles work, and how integer results are rounded: 39 </p> 40<pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">discrete_quantile_policy_type</span> 41<span class="special">{</span> 42 <span class="identifier">real</span><span class="special">,</span> 43 <span class="identifier">integer_round_outwards</span><span class="special">,</span> <span class="comment">// default</span> 44 <span class="identifier">integer_round_inwards</span><span class="special">,</span> 45 <span class="identifier">integer_round_down</span><span class="special">,</span> 46 <span class="identifier">integer_round_up</span><span class="special">,</span> 47 <span class="identifier">integer_round_nearest</span> 48<span class="special">};</span> 49 50<span class="keyword">template</span> <span class="special"><</span><span class="identifier">discrete_quantile_policy_type</span><span class="special">></span> 51<span class="keyword">struct</span> <span class="identifier">discrete_quantile</span><span class="special">;</span> 52</pre> 53<p> 54 The values that <code class="computeroutput"><span class="identifier">discrete_quantile</span></code> 55 can take have the following meanings: 56 </p> 57<h6> 58<a name="math_toolkit.pol_ref.discrete_quant_ref.h0"></a> 59 <span class="phrase"><a name="math_toolkit.pol_ref.discrete_quant_ref.real"></a></span><a class="link" href="discrete_quant_ref.html#math_toolkit.pol_ref.discrete_quant_ref.real">real</a> 60 </h6> 61<p> 62 Ignores the discreteness of the distribution, and returns a real-valued result. 63 For example: 64 </p> 65<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> 66<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial_distribution</span><span class="special">;</span> 67 68<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span> 69 70<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><</span> 71 <span class="keyword">double</span><span class="special">,</span> 72 <span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">real</span><span class="special">></span> <span class="special">></span> 73 <span class="special">></span> <span class="identifier">dist_type</span><span class="special">;</span> 74 75<span class="comment">// Lower 5% quantile:</span> 76<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span> 77<span class="comment">// Upper 95% quantile:</span> 78<span class="keyword">double</span> <span class="identifier">y</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_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span> 79</pre> 80<p> 81 Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span> 82 <span class="number">27.3898</span></code> and <code class="computeroutput"><span class="identifier">y</span> 83 <span class="special">=</span> <span class="number">68.1584</span></code>. 84 </p> 85<h6> 86<a name="math_toolkit.pol_ref.discrete_quant_ref.h1"></a> 87 <span class="phrase"><a name="math_toolkit.pol_ref.discrete_quant_ref.integer_round_outwards"></a></span><a class="link" href="discrete_quant_ref.html#math_toolkit.pol_ref.discrete_quant_ref.integer_round_outwards">integer_round_outwards</a> 88 </h6> 89<p> 90 This is the default policy: an integer value is returned so that: 91 </p> 92<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 93<li class="listitem"> 94 Lower quantiles (where the probability is less than 0.5) are rounded 95 down. 96 </li> 97<li class="listitem"> 98 Upper quantiles (where the probability is greater than 0.5) are rounded 99 up. 100 </li> 101</ul></div> 102<p> 103 This is normally the safest rounding policy, since it ensures that both one 104 and two sided intervals are guaranteed to have <span class="emphasis"><em>at least</em></span> 105 the requested coverage. For example: 106 </p> 107<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> 108<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial</span><span class="special">;</span> 109 110<span class="comment">// Use the default rounding policy integer_round_outwards.</span> 111<span class="comment">// Lower quantile rounded down:</span> 112<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span> <span class="comment">// rounded up 27 from 27.3898</span> 113<span class="comment">// Upper quantile rounded up:</span> 114<span class="keyword">double</span> <span class="identifier">y</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">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span> <span class="comment">// rounded down to 69 from 68.1584</span> 115</pre> 116<p> 117 Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span> 118 <span class="number">27</span></code> (rounded down from 27.3898) and 119 <code class="computeroutput"><span class="identifier">y</span> <span class="special">=</span> 120 <span class="number">69</span></code> (rounded up from 68.1584). 121 </p> 122<p> 123 The variables x and y are now defined so that: 124 </p> 125<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special"><=</span> <span class="number">0.05</span> 126<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">>=</span> <span class="number">0.95</span> 127</pre> 128<p> 129 In other words we guarantee <span class="emphasis"><em>at least 90% coverage in the central 130 region overall</em></span>, and also <span class="emphasis"><em>no more than 5% coverage in 131 each tail</em></span>. 132 </p> 133<h6> 134<a name="math_toolkit.pol_ref.discrete_quant_ref.h2"></a> 135 <span class="phrase"><a name="math_toolkit.pol_ref.discrete_quant_ref.integer_round_inwards"></a></span><a class="link" href="discrete_quant_ref.html#math_toolkit.pol_ref.discrete_quant_ref.integer_round_inwards">integer_round_inwards</a> 136 </h6> 137<p> 138 This is the opposite of <span class="emphasis"><em>integer_round_outwards</em></span>: an integer 139 value is returned so that: 140 </p> 141<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 142<li class="listitem"> 143 Lower quantiles (where the probability is less than 0.5) are rounded 144 <span class="emphasis"><em>up</em></span>. 145 </li> 146<li class="listitem"> 147 Upper quantiles (where the probability is greater than 0.5) are rounded 148 <span class="emphasis"><em>down</em></span>. 149 </li> 150</ul></div> 151<p> 152 For example: 153 </p> 154<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> 155<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial_distribution</span><span class="special">;</span> 156 157<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span> 158 159<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><</span> 160 <span class="keyword">double</span><span class="special">,</span> 161 <span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_inwards</span><span class="special">></span> <span class="special">></span> 162 <span class="special">></span> <span class="identifier">dist_type</span><span class="special">;</span> 163 164<span class="comment">// Lower quantile rounded up:</span> 165<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span> <span class="comment">// 28 rounded up from 27.3898</span> 166<span class="comment">// Upper quantile rounded down:</span> 167<span class="keyword">double</span> <span class="identifier">y</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_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span> <span class="comment">// 68 rounded down from 68.1584</span> 168</pre> 169<p> 170 Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span> 171 <span class="number">28</span></code> (rounded up from 27.3898) and <code class="computeroutput"><span class="identifier">y</span> <span class="special">=</span> <span class="number">68</span></code> 172 (rounded down from 68.1584). 173 </p> 174<p> 175 The variables x and y are now defined so that: 176 </p> 177<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">>=</span> <span class="number">0.05</span> 178<span class="identifier">cdf</span><span class="special">(</span><span class="identifier">negative_binomial</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">y</span><span class="special">)</span> <span class="special"><=</span> <span class="number">0.95</span> 179</pre> 180<p> 181 In other words we guarantee <span class="emphasis"><em>at no more than 90% coverage in the 182 central region overall</em></span>, and also <span class="emphasis"><em>at least 5% coverage 183 in each tail</em></span>. 184 </p> 185<h6> 186<a name="math_toolkit.pol_ref.discrete_quant_ref.h3"></a> 187 <span class="phrase"><a name="math_toolkit.pol_ref.discrete_quant_ref.integer_round_down"></a></span><a class="link" href="discrete_quant_ref.html#math_toolkit.pol_ref.discrete_quant_ref.integer_round_down">integer_round_down</a> 188 </h6> 189<p> 190 Always rounds down to an integer value, no matter whether it's an upper or 191 a lower quantile. 192 </p> 193<h6> 194<a name="math_toolkit.pol_ref.discrete_quant_ref.h4"></a> 195 <span class="phrase"><a name="math_toolkit.pol_ref.discrete_quant_ref.integer_round_up"></a></span><a class="link" href="discrete_quant_ref.html#math_toolkit.pol_ref.discrete_quant_ref.integer_round_up">integer_round_up</a> 196 </h6> 197<p> 198 Always rounds up to an integer value, no matter whether it's an upper or 199 a lower quantile. 200 </p> 201<h6> 202<a name="math_toolkit.pol_ref.discrete_quant_ref.h5"></a> 203 <span class="phrase"><a name="math_toolkit.pol_ref.discrete_quant_ref.integer_round_nearest"></a></span><a class="link" href="discrete_quant_ref.html#math_toolkit.pol_ref.discrete_quant_ref.integer_round_nearest">integer_round_nearest</a> 204 </h6> 205<p> 206 Always rounds to the nearest integer value, no matter whether it's an upper 207 or a lower quantile. This will produce the requested coverage <span class="emphasis"><em>in 208 the average case</em></span>, but for any specific example may results in 209 either significantly more or less coverage than the requested amount. For 210 example: 211 </p> 212<p> 213 For example: 214 </p> 215<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> 216<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">negative_binomial_distribution</span><span class="special">;</span> 217 218<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span> 219 220<span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special"><</span> 221 <span class="keyword">double</span><span class="special">,</span> 222 <span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_nearest</span><span class="special">></span> <span class="special">></span> 223 <span class="special">></span> <span class="identifier">dist_type</span><span class="special">;</span> 224 225<span class="comment">// Lower quantile rounded (down) to nearest:</span> 226<span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">dist_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span> <span class="comment">// 27</span> 227<span class="comment">// Upper quantile rounded (down) to nearest:</span> 228<span class="keyword">double</span> <span class="identifier">y</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_type</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">),</span> <span class="number">0.05</span><span class="special">));</span> <span class="comment">// 68</span> 229</pre> 230<p> 231 Results in <code class="computeroutput"><span class="identifier">x</span> <span class="special">=</span> 232 <span class="number">27</span></code> (rounded from 27.3898) and <code class="computeroutput"><span class="identifier">y</span> <span class="special">=</span> <span class="number">68</span></code> 233 (rounded from 68.1584). 234 </p> 235</div> 236<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 237<td align="left"></td> 238<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 239 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 240 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 241 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 242 Daryle Walker and Xiaogang Zhang<p> 243 Distributed under the Boost Software License, Version 1.0. (See accompanying 244 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>) 245 </p> 246</div></td> 247</tr></table> 248<hr> 249<div class="spirit-nav"> 250<a accesskey="p" href="assert_undefined.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.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="precision_pol.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 251</div> 252</body> 253</html> 254
