libs/math/doc/sf_and_dist/html/math_toolkit/dist/stat_tut/weg/dist_construct_eg.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Distribution Construction Example</title>
   5 <link rel="stylesheet" href="../../../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="../../../../index.html" title="Math Toolkit">
   8 <link rel="up" href="../weg.html" title="Worked Examples">
   9 <link rel="prev" href="../weg.html" title="Worked Examples">
  10 <link rel="next" href="st_eg.html" title="Student's t Distribution Examples">
  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="../weg.html"><img src="../../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.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="st_eg.html"><img src="../../../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section math_toolkit_dist_stat_tut_weg_dist_construct_eg">
  26 <div class="titlepage"><div><div><h5 class="title">
  27 <a name="math_toolkit.dist.stat_tut.weg.dist_construct_eg"></a><a class="link" href="dist_construct_eg.html" title="Distribution Construction Example">Distribution
  28           Construction Example</a>
  29 </h5></div></div></div>
  30 <p>
  31             See <a href="../../../../../../../example/distribution_construction.cpp" target="_top">distribution_construction.cpp</a>
  32             for full source code.
  33           </p>
  34 <p>
  35             The structure of distributions is rather different from some other statistical
  36             libraries, for example in less object-oriented language like FORTRAN
  37             and C, that provide a few arguments to each free function. This library
  38             provides each distribution as a template C++ class. A distribution is
  39             constructed with a few arguments, and then member and non-member functions
  40             are used to find values of the distribution, often a function of a random
  41             variate.
  42           </p>
  43 <p>
  44             First we need some includes to access the negative binomial distribution
  45             (and the binomial, beta and gamma too).
  46           </p>
  47 <p>
  48 </p>
  49 <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> <span class="comment">// for negative_binomial_distribution</span>
  50   <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> <span class="comment">// default type is double.</span>
  51   <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> <span class="comment">// typedef provides default type is double.</span>
  52 <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">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for binomial_distribution.</span>
  53 <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">beta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for beta_distribution.</span>
  54 <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">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for gamma_distribution.</span>
  55 <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">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// for normal_distribution.</span>
  56 </pre>
  57 <p>
  58           </p>
  59 <p>
  60             Several examples of constructing distributions follow:
  61           </p>
  62 <p>
  63             First, a negative binomial distribution with 8 successes and a success
  64             fraction 0.25, 25% or 1 in 4, is constructed like this:
  65           </p>
  66 <p>
  67 </p>
  68 <pre class="programlisting"><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">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">mydist0</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
  69 </pre>
  70 <p>
  71           </p>
  72 <p>
  73             But this is inconveniently long, so we might be tempted to write
  74           </p>
  75 <p>
  76 </p>
  77 <pre class="programlisting"><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>
  78 </pre>
  79 <p>
  80           </p>
  81 <p>
  82             but this might risk ambiguity with names in std random so *much better
  83             is explicit <code class="computeroutput"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span> </code> * ... statements like
  84           </p>
  85 <p>
  86 </p>
  87 <pre class="programlisting"><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>
  88 </pre>
  89 <p>
  90           </p>
  91 <p>
  92             and we can still reduce typing.
  93           </p>
  94 <p>
  95             Since the vast majority of applications use will be using double precision,
  96             the template argument to the distribution (RealType) defaults to type
  97             double, so we can also write:
  98           </p>
  99 <p>
 100 </p>
 101 <pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mydist9</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span> <span class="comment">// Uses default RealType = double.</span>
 102 </pre>
 103 <p>
 104           </p>
 105 <p>
 106             But the name "negative_binomial_distribution" is still inconveniently
 107             long, so for most distributions, a convenience typedef is provided, for
 108             example:
 109           </p>
 110 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">negative_binomial</span><span class="special">;</span> <span class="comment">// Reserved name of type double.</span>
 111 </pre>
 112 <div class="caution"><table border="0" summary="Caution">
 113 <tr>
 114 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../../doc/src/images/caution.png"></td>
 115 <th align="left">Caution</th>
 116 </tr>
 117 <tr><td align="left" valign="top"><p>
 118               This convenience typedef is <span class="emphasis"><em>not</em></span> provided if a
 119               clash would occur with the name of a function: currently only "beta"
 120               and "gamma" fall into this category.
 121             </p></td></tr>
 122 </table></div>
 123 <p>
 124             So, after a using statement,
 125           </p>
 126 <p>
 127 </p>
 128 <pre class="programlisting"><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>
 129 </pre>
 130 <p>
 131           </p>
 132 <p>
 133             we have a convenient typedef to <code class="computeroutput"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span></code>:
 134           </p>
 135 <p>
 136 </p>
 137 <pre class="programlisting"><span class="identifier">negative_binomial</span> <span class="identifier">mydist</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
 138 </pre>
 139 <p>
 140           </p>
 141 <p>
 142             Some more examples using the convenience typedef:
 143           </p>
 144 <p>
 145 </p>
 146 <pre class="programlisting"><span class="identifier">negative_binomial</span> <span class="identifier">mydist10</span><span class="special">(</span><span class="number">5.</span><span class="special">,</span> <span class="number">0.4</span><span class="special">);</span> <span class="comment">// Both arguments double.</span>
 147 </pre>
 148 <p>
 149           </p>
 150 <p>
 151             And automatic conversion takes place, so you can use integers and floats:
 152           </p>
 153 <p>
 154 </p>
 155 <pre class="programlisting"><span class="identifier">negative_binomial</span> <span class="identifier">mydist11</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">0.4</span><span class="special">);</span> <span class="comment">// Using provided typedef double, int and double arguments.</span>
 156 </pre>
 157 <p>
 158           </p>
 159 <p>
 160             This is probably the most common usage.
 161           </p>
 162 <p>
 163 </p>
 164 <pre class="programlisting"><span class="identifier">negative_binomial</span> <span class="identifier">mydist12</span><span class="special">(</span><span class="number">5.</span><span class="special">,</span> <span class="number">0.4F</span><span class="special">);</span> <span class="comment">// Double and float arguments.</span>
 165 <span class="identifier">negative_binomial</span> <span class="identifier">mydist13</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// Both arguments integer.</span>
 166 </pre>
 167 <p>
 168           </p>
 169 <p>
 170             Similarly for most other distributions like the binomial.
 171           </p>
 172 <p>
 173 </p>
 174 <pre class="programlisting"><span class="identifier">binomial</span> <span class="identifier">mybinomial</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span> <span class="comment">// is more concise than</span>
 175 <span class="identifier">binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mybinomd1</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span>
 176 </pre>
 177 <p>
 178           </p>
 179 <p>
 180             For cases when the typdef distribution name would clash with a math special
 181             function (currently only beta and gamma) the typedef is deliberately
 182             not provided, and the longer version of the name must be used. For example
 183             do not use:
 184           </p>
 185 <pre class="programlisting"><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">beta</span><span class="special">;</span>
 186 <span class="identifier">beta</span> <span class="identifier">mybetad0</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span> <span class="comment">// Error beta is a math FUNCTION!</span>
 187 </pre>
 188 <p>
 189             Which produces the error messages:
 190           </p>
 191 <pre class="programlisting">error C2146: syntax error : missing ';' before identifier 'mybetad0'
 192 warning C4551: function call missing argument list
 193 error C3861: 'mybetad0': identifier not found
 194 </pre>
 195 <p>
 196             Instead you should use:
 197           </p>
 198 <p>
 199 </p>
 200 <pre class="programlisting"><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">beta_distribution</span><span class="special">;</span>
 201 <span class="identifier">beta_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mybetad1</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span>
 202 </pre>
 203 <p>
 204           </p>
 205 <p>
 206             or for the gamma distribution:
 207           </p>
 208 <p>
 209 </p>
 210 <pre class="programlisting"><span class="identifier">gamma_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mygammad1</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">0.5</span><span class="special">);</span>
 211 </pre>
 212 <p>
 213           </p>
 214 <p>
 215             We can, of course, still provide the type explicitly thus:
 216           </p>
 217 <p>
 218 </p>
 219 <pre class="programlisting"><span class="comment">// Explicit double precision:</span>
 220 <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span>        <span class="identifier">mydist1</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
 221
 222 <span class="comment">// Explicit float precision, double arguments are truncated to float:</span>
 223 <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span>         <span class="identifier">mydist2</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
 224
 225 <span class="comment">// Explicit float precision, integer &amp; double arguments converted to float.</span>
 226 <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span>         <span class="identifier">mydist3</span><span class="special">(</span><span class="number">8</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
 227
 228 <span class="comment">// Explicit float precision, float arguments, so no conversion:</span>
 229 <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span>         <span class="identifier">mydist4</span><span class="special">(</span><span class="number">8.F</span><span class="special">,</span> <span class="number">0.25F</span><span class="special">);</span>
 230
 231 <span class="comment">// Explicit float precision, integer arguments promoted to float.</span>
 232 <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span>         <span class="identifier">mydist5</span><span class="special">(</span><span class="number">8</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span>
 233
 234 <span class="comment">// Explicit double precision:</span>
 235 <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span>        <span class="identifier">mydist6</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
 236
 237 <span class="comment">// Explicit long double precision:</span>
 238 <span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="keyword">long</span> <span class="keyword">double</span><span class="special">&gt;</span>   <span class="identifier">mydist7</span><span class="special">(</span><span class="number">8.</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
 239 </pre>
 240 <p>
 241           </p>
 242 <p>
 243             And if you have your own RealType called MyFPType, for example NTL RR
 244             (an arbitrary precision type), then we can write:
 245           </p>
 246 <pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;</span><span class="identifier">MyFPType</span><span class="special">&gt;</span>  <span class="identifier">mydist6</span><span class="special">(</span><span class="number">8</span><span class="special">,</span> <span class="number">1</span><span class="special">);</span> <span class="comment">// Integer arguments -&gt; MyFPType.</span>
 247 </pre>
 248 <h6>
 249 <a name="math_toolkit.dist.stat_tut.weg.dist_construct_eg.h0"></a>
 250             <span><a name="math_toolkit.dist.stat_tut.weg.dist_construct_eg.default_arguments_to_distribution_constructors_"></a></span><a class="link" href="dist_construct_eg.html#math_toolkit.dist.stat_tut.weg.dist_construct_eg.default_arguments_to_distribution_constructors_">Default
 251             arguments to distribution constructors.</a>
 252           </h6>
 253 <p>
 254             Note that default constructor arguments are only provided for some distributions.
 255             So if you wrongly assume a default argument you will get an error message,
 256             for example:
 257           </p>
 258 <pre class="programlisting"><span class="identifier">negative_binomial_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">mydist8</span><span class="special">;</span>
 259 </pre>
 260 <pre class="programlisting">error C2512 no appropriate default constructor available.</pre>
 261 <p>
 262             No default constructors are provided for the negative binomial, because
 263             it is difficult to chose any sensible default values for this distribution.
 264             For other distributions, like the normal distribution, it is obviously
 265             very useful to provide 'standard' defaults for the mean and standard
 266             deviation thus:
 267           </p>
 268 <pre class="programlisting"><span class="identifier">normal_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">mean</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">sd</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
 269 </pre>
 270 <p>
 271             So in this case we can write:
 272           </p>
 273 <p>
 274 </p>
 275 <pre class="programlisting">  <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">normal</span><span class="special">;</span>
 276
 277   <span class="identifier">normal</span> <span class="identifier">norm1</span><span class="special">;</span>       <span class="comment">// Standard normal distribution.</span>
 278   <span class="identifier">normal</span> <span class="identifier">norm2</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>    <span class="comment">// Mean = 2, std deviation = 1.</span>
 279   <span class="identifier">normal</span> <span class="identifier">norm3</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">);</span> <span class="comment">// Mean = 2, std deviation = 3.</span>
 280
 281   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 282 <span class="special">}</span>  <span class="comment">// int main()</span>
 283 </pre>
 284 <p>
 285           </p>
 286 <p>
 287             There is no useful output from this program, of course.
 288           </p>
 289 </div>
 290 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 291 <td align="left"></td>
 292 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010 John Maddock, Paul A. Bristow, Hubert Holin, Xiaogang Zhang, Bruno
 293       Lalande, Johan R&#229;de, Gautam Sewani, Thijs van den Berg and Benjamin Sobotta<p>
 294         Distributed under the Boost Software License, Version 1.0. (See accompanying
 295         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>)
 296       </p>
 297 </div></td>
 298 </tr></table>
 299 <hr>
 300 <div class="spirit-nav">
 301 <a accesskey="p" href="../weg.html"><img src="../../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../weg.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="st_eg.html"><img src="../../../../../../../../../doc/src/images/next.png" alt="Next"></a>
 302 </div>
 303 </body>
 304 </html>