ceph/src/boost/libs/math/doc/html/math_toolkit/pol_ref/discrete_quant_ref.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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.77.1">
   7 <link rel="home" href="../../index.html" title="Math Toolkit 2.5.1">
   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">&lt;</span><span class="identifier">discrete_quantile_policy_type</span><span class="special">&gt;</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">&lt;</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">&gt;</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">&lt;</span>
  71       <span class="keyword">double</span><span class="special">,</span>
  72       <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">real</span><span class="special">&gt;</span> <span class="special">&gt;</span>
  73    <span class="special">&gt;</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">&lt;</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">&gt;</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">&lt;=</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">&gt;=</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">&lt;</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">&gt;</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">&lt;</span>
 160       <span class="keyword">double</span><span class="special">,</span>
 161       <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_inwards</span><span class="special">&gt;</span> <span class="special">&gt;</span>
 162    <span class="special">&gt;</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">&gt;=</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">&lt;=</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">&lt;</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">&gt;</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">&lt;</span>
 221       <span class="keyword">double</span><span class="special">,</span>
 222       <span class="identifier">policy</span><span class="special">&lt;</span><span class="identifier">discrete_quantile</span><span class="special">&lt;</span><span class="identifier">integer_round_nearest</span><span class="special">&gt;</span> <span class="special">&gt;</span>
 223    <span class="special">&gt;</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 &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 239       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 240       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 241       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 242         Distributed under the Boost Software License, Version 1.0. (See accompanying
 243         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>)
 244       </p>
 245 </div></td>
 246 </tr></table>
 247 <hr>
 248 <div class="spirit-nav">
 249 <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>
 250 </div>
 251 </body>
 252 </html>