libs/math/doc/html/math_toolkit/stat_tut/overview/objects.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Distributions are Objects</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="headers.html" title="Headers and Namespaces">
  10 <link rel="next" href="generic.html" title="Generic operations common to all distributions are non-member functions">
  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="headers.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="generic.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="math_toolkit.stat_tut.overview.objects"></a><a class="link" href="objects.html" title="Distributions are Objects">Distributions
  28         are Objects</a>
  29 </h4></div></div></div>
  30 <p>
  31           Each kind of distribution in this library is a class type - an object,
  32           with member functions.
  33         </p>
  34 <div class="tip"><table border="0" summary="Tip">
  35 <tr>
  36 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
  37 <th align="left">Tip</th>
  38 </tr>
  39 <tr><td align="left" valign="top"><p>
  40             If you are familiar with statistics libraries using functions, and 'Distributions
  41             as Objects' seem alien, see <a class="link" href="../weg/nag_library.html" title="Comparison with C, R, FORTRAN-style Free Functions">the
  42             comparison to other statistics libraries.</a>
  43           </p></td></tr>
  44 </table></div>
  45 <p>
  46           <a class="link" href="../../../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policies</a> provide optional fine-grained control
  47           of the behaviour of these classes, allowing the user to customise behaviour
  48           such as how errors are handled, or how the quantiles of discrete distributions
  49           behave.
  50         </p>
  51 <p>
  52           Making distributions class types does two things:
  53         </p>
  54 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  55 <li class="listitem">
  56               It encapsulates the kind of distribution in the C++ type system; so,
  57               for example, Students-t distributions are always a different C++ type
  58               from Chi-Squared distributions.
  59             </li>
  60 <li class="listitem">
  61               The distribution objects store any parameters associated with the distribution:
  62               for example, the Students-t distribution has a <span class="emphasis"><em>degrees of
  63               freedom</em></span> parameter that controls the shape of the distribution.
  64               This <span class="emphasis"><em>degrees of freedom</em></span> parameter has to be provided
  65               to the Students-t object when it is constructed.
  66             </li>
  67 </ul></div>
  68 <p>
  69           Although the distribution classes in this library are templates, there
  70           are typedefs on type <span class="emphasis"><em>double</em></span> that mostly take the usual
  71           name of the distribution (except where there is a clash with a function
  72           of the same name: beta and gamma, in which case using the default template
  73           arguments - <code class="computeroutput"><span class="identifier">RealType</span> <span class="special">=</span>
  74           <span class="keyword">double</span></code> - is nearly as convenient).
  75           Probably 95% of uses are covered by these typedefs:
  76         </p>
  77 <pre class="programlisting"><span class="comment">// using namespace boost::math; // Avoid potential ambiguity with names in std &lt;random&gt;</span>
  78 <span class="comment">// Safer to declare specific functions with using statement(s):</span>
  79
  80 <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>
  81 <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">binomial_distribution</span><span class="special">;</span>
  82 <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">students_t</span><span class="special">;</span>
  83
  84 <span class="comment">// Construct a students_t distribution with 4 degrees of freedom:</span>
  85 <span class="identifier">students_t</span> <span class="identifier">d1</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
  86
  87 <span class="comment">// Construct a double-precision beta distribution</span>
  88 <span class="comment">// with parameters a = 10, b = 20</span>
  89 <span class="identifier">beta_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">d2</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">20</span><span class="special">);</span> <span class="comment">// Note: _distribution&lt;&gt; suffix !</span>
  90 </pre>
  91 <p>
  92           If you need to use the distributions with a type other than <code class="computeroutput"><span class="keyword">double</span></code>, then you can instantiate the template
  93           directly: the names of the templates are the same as the <code class="computeroutput"><span class="keyword">double</span></code> typedef but with <code class="computeroutput"><span class="identifier">_distribution</span></code>
  94           appended, for example: <a class="link" href="../../dist_ref/dists/students_t_dist.html" title="Students t Distribution">Students
  95           t Distribution</a> or <a class="link" href="../../dist_ref/dists/binomial_dist.html" title="Binomial Distribution">Binomial
  96           Distribution</a>:
  97         </p>
  98 <pre class="programlisting"><span class="comment">// Construct a students_t distribution, of float type,</span>
  99 <span class="comment">// with 4 degrees of freedom:</span>
 100 <span class="identifier">students_t_distribution</span><span class="special">&lt;</span><span class="keyword">float</span><span class="special">&gt;</span> <span class="identifier">d3</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
 101
 102 <span class="comment">// Construct a binomial distribution, of long double type,</span>
 103 <span class="comment">// with probability of success 0.3</span>
 104 <span class="comment">// and 20 trials in total:</span>
 105 <span class="identifier">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">d4</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.3</span><span class="special">);</span>
 106 </pre>
 107 <p>
 108           The parameters passed to the distributions can be accessed via getter member
 109           functions:
 110         </p>
 111 <pre class="programlisting"><span class="identifier">d1</span><span class="special">.</span><span class="identifier">degrees_of_freedom</span><span class="special">();</span>  <span class="comment">// returns 4.0</span>
 112 </pre>
 113 <p>
 114           This is all well and good, but not very useful so far. What we often want
 115           is to be able to calculate the <span class="emphasis"><em>cumulative distribution functions</em></span>
 116           and <span class="emphasis"><em>quantiles</em></span> etc for these distributions.
 117         </p>
 118 </div>
 119 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 120 <td align="left"></td>
 121 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 122       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 123       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 124       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 125       Daryle Walker and Xiaogang Zhang<p>
 126         Distributed under the Boost Software License, Version 1.0. (See accompanying
 127         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>)
 128       </p>
 129 </div></td>
 130 </tr></table>
 131 <hr>
 132 <div class="spirit-nav">
 133 <a accesskey="p" href="headers.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="generic.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 134 </div>
 135 </body>
 136 </html>