libs/math/doc/html/math_toolkit/dist_ref/dists/students_t_dist.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Students t Distribution</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.5.2">
   8 <link rel="up" href="../dists.html" title="Distributions">
   9 <link rel="prev" href="skew_normal_dist.html" title="Skew Normal Distribution">
  10 <link rel="next" href="triangular_dist.html" title="Triangular Distribution">
  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="skew_normal_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.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="triangular_dist.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.dist_ref.dists.students_t_dist"></a><a class="link" href="students_t_dist.html" title="Students t Distribution">Students
  28         t Distribution</a>
  29 </h4></div></div></div>
  30 <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">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
  31 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  32
  33 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
  34           <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>   <span class="special">=</span> <a class="link" href="../../pol_ref/pol_ref_ref.html" title="Policy Class Reference">policies::policy&lt;&gt;</a> <span class="special">&gt;</span>
  35 <span class="keyword">class</span> <span class="identifier">students_t_distribution</span><span class="special">;</span>
  36
  37 <span class="keyword">typedef</span> <span class="identifier">students_t_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">students_t</span><span class="special">;</span>
  38
  39 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
  40 <span class="keyword">class</span> <span class="identifier">students_t_distribution</span>
  41 <span class="special">{</span>
  42    <span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
  43    <span class="keyword">typedef</span> <span class="identifier">Policy</span>   <span class="identifier">policy_type</span><span class="special">;</span>
  44
  45    <span class="comment">// Construct:</span>
  46    <span class="identifier">students_t_distribution</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">);</span>
  47
  48    <span class="comment">// Accessor:</span>
  49    <span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
  50
  51    <span class="comment">// degrees of freedom estimation:</span>
  52    <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
  53       <span class="identifier">RealType</span> <span class="identifier">difference_from_mean</span><span class="special">,</span>
  54       <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
  55       <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
  56       <span class="identifier">RealType</span> <span class="identifier">sd</span><span class="special">,</span>
  57       <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
  58 <span class="special">};</span>
  59
  60 <span class="special">}}</span> <span class="comment">// namespaces</span>
  61 </pre>
  62 <p>
  63           A statistical distribution published by William Gosset in 1908. His employer,
  64           Guinness Breweries, required him to publish under a pseudonym (possibly
  65           to hide that they were using statistics), so he chose "Student".
  66           Given N independent measurements, let
  67         </p>
  68 <p>
  69           <span class="inlinemediaobject"><img src="../../../../equations/students_t_dist.svg"></span>
  70         </p>
  71 <p>
  72           where <span class="emphasis"><em>M</em></span> is the population mean,<span class="emphasis"><em>&#956;</em></span>
  73           is the sample mean, and <span class="emphasis"><em>s</em></span> is the sample variance.
  74         </p>
  75 <p>
  76           Student's t-distribution is defined as the distribution of the random variable
  77           t which is - very loosely - the "best" that we can do not knowing
  78           the true standard deviation of the sample. It has the PDF:
  79         </p>
  80 <p>
  81           <span class="inlinemediaobject"><img src="../../../../equations/students_t_ref1.svg"></span>
  82         </p>
  83 <p>
  84           The Student's t-distribution takes a single parameter: the number of degrees
  85           of freedom of the sample. When the degrees of freedom is <span class="emphasis"><em>one</em></span>
  86           then this distribution is the same as the Cauchy-distribution. As the number
  87           of degrees of freedom tends towards infinity, then this distribution approaches
  88           the normal-distribution. The following graph illustrates how the PDF varies
  89           with the degrees of freedom &#957;:
  90         </p>
  91 <p>
  92           <span class="inlinemediaobject"><img src="../../../../graphs/students_t_pdf.svg" align="middle"></span>
  93         </p>
  94 <h5>
  95 <a name="math_toolkit.dist_ref.dists.students_t_dist.h0"></a>
  96           <span class="phrase"><a name="math_toolkit.dist_ref.dists.students_t_dist.member_functions"></a></span><a class="link" href="students_t_dist.html#math_toolkit.dist_ref.dists.students_t_dist.member_functions">Member
  97           Functions</a>
  98         </h5>
  99 <pre class="programlisting"><span class="identifier">students_t_distribution</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">RealType</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">);</span>
 100 </pre>
 101 <p>
 102           Constructs a Student's t-distribution with <span class="emphasis"><em>v</em></span> degrees
 103           of freedom.
 104         </p>
 105 <p>
 106           Requires <span class="emphasis"><em>v</em></span> &gt; 0, otherwise calls <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
 107           Note that non-integral degrees of freedom are supported, and are meaningful
 108           under certain circumstances.
 109         </p>
 110 <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">degrees_of_freedom</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
 111 </pre>
 112 <p>
 113           Returns the number of degrees of freedom of this distribution.
 114         </p>
 115 <pre class="programlisting"><span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
 116    <span class="identifier">RealType</span> <span class="identifier">difference_from_mean</span><span class="special">,</span>
 117    <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
 118    <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
 119    <span class="identifier">RealType</span> <span class="identifier">sd</span><span class="special">,</span>
 120    <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
 121 </pre>
 122 <p>
 123           Returns the number of degrees of freedom required to observe a significant
 124           result in the Student's t test when the mean differs from the "true"
 125           mean by <span class="emphasis"><em>difference_from_mean</em></span>.
 126         </p>
 127 <div class="variablelist">
 128 <p class="title"><b></b></p>
 129 <dl class="variablelist">
 130 <dt><span class="term">difference_from_mean</span></dt>
 131 <dd><p>
 132                 The difference between the true mean and the sample mean that we
 133                 wish to show is significant.
 134               </p></dd>
 135 <dt><span class="term">alpha</span></dt>
 136 <dd><p>
 137                 The maximum acceptable probability of rejecting the null hypothesis
 138                 when it is in fact true.
 139               </p></dd>
 140 <dt><span class="term">beta</span></dt>
 141 <dd><p>
 142                 The maximum acceptable probability of failing to reject the null
 143                 hypothesis when it is in fact false.
 144               </p></dd>
 145 <dt><span class="term">sd</span></dt>
 146 <dd><p>
 147                 The sample standard deviation.
 148               </p></dd>
 149 <dt><span class="term">hint</span></dt>
 150 <dd><p>
 151                 A hint for the location to start looking for the result, a good choice
 152                 for this would be the sample size of a previous borderline Student's
 153                 t test.
 154               </p></dd>
 155 </dl>
 156 </div>
 157 <div class="note"><table border="0" summary="Note">
 158 <tr>
 159 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 160 <th align="left">Note</th>
 161 </tr>
 162 <tr><td align="left" valign="top"><p>
 163             Remember that for a two-sided test, you must divide alpha by two before
 164             calling this function.
 165           </p></td></tr>
 166 </table></div>
 167 <p>
 168           For more information on this function see the <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc222.htm" target="_top">NIST
 169           Engineering Statistics Handbook</a>.
 170         </p>
 171 <h5>
 172 <a name="math_toolkit.dist_ref.dists.students_t_dist.h1"></a>
 173           <span class="phrase"><a name="math_toolkit.dist_ref.dists.students_t_dist.non_member_accessors"></a></span><a class="link" href="students_t_dist.html#math_toolkit.dist_ref.dists.students_t_dist.non_member_accessors">Non-member
 174           Accessors</a>
 175         </h5>
 176 <p>
 177           All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
 178           functions</a> that are generic to all distributions are supported:
 179           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
 180           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
 181           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.hazard">Hazard Function</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.chf">Cumulative Hazard Function</a>,
 182           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.median">median</a>,
 183           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mode">mode</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>,
 184           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
 185           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.skewness">skewness</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis">kurtosis</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>,
 186           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.range">range</a> and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.support">support</a>.
 187         </p>
 188 <p>
 189           The domain of the random variable is [-&#8734;, +&#8734;].
 190         </p>
 191 <h5>
 192 <a name="math_toolkit.dist_ref.dists.students_t_dist.h2"></a>
 193           <span class="phrase"><a name="math_toolkit.dist_ref.dists.students_t_dist.examples"></a></span><a class="link" href="students_t_dist.html#math_toolkit.dist_ref.dists.students_t_dist.examples">Examples</a>
 194         </h5>
 195 <p>
 196           Various <a class="link" href="../../stat_tut/weg/st_eg.html" title="Student's t Distribution Examples">worked examples</a>
 197           are available illustrating the use of the Student's t distribution.
 198         </p>
 199 <h5>
 200 <a name="math_toolkit.dist_ref.dists.students_t_dist.h3"></a>
 201           <span class="phrase"><a name="math_toolkit.dist_ref.dists.students_t_dist.accuracy"></a></span><a class="link" href="students_t_dist.html#math_toolkit.dist_ref.dists.students_t_dist.accuracy">Accuracy</a>
 202         </h5>
 203 <p>
 204           The normal distribution is implemented in terms of the <a class="link" href="../../sf_beta/ibeta_function.html" title="Incomplete Beta Functions">incomplete
 205           beta function</a> and <a class="link" href="../../sf_beta/ibeta_inv_function.html" title="The Incomplete Beta Function Inverses">its
 206           inverses</a>, refer to accuracy data on those functions for more information.
 207         </p>
 208 <h5>
 209 <a name="math_toolkit.dist_ref.dists.students_t_dist.h4"></a>
 210           <span class="phrase"><a name="math_toolkit.dist_ref.dists.students_t_dist.implementation"></a></span><a class="link" href="students_t_dist.html#math_toolkit.dist_ref.dists.students_t_dist.implementation">Implementation</a>
 211         </h5>
 212 <p>
 213           In the following table <span class="emphasis"><em>v</em></span> is the degrees of freedom
 214           of the distribution, <span class="emphasis"><em>t</em></span> is the random variate, <span class="emphasis"><em>p</em></span>
 215           is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
 216         </p>
 217 <div class="informaltable"><table class="table">
 218 <colgroup>
 219 <col>
 220 <col>
 221 </colgroup>
 222 <thead><tr>
 223 <th>
 224                   <p>
 225                     Function
 226                   </p>
 227                 </th>
 228 <th>
 229                   <p>
 230                     Implementation Notes
 231                   </p>
 232                 </th>
 233 </tr></thead>
 234 <tbody>
 235 <tr>
 236 <td>
 237                   <p>
 238                     pdf
 239                   </p>
 240                 </td>
 241 <td>
 242                   <p>
 243                     Using the relation: pdf = (v / (v + t<sup>2</sup>))<sup>(1+v)/2 </sup> / (sqrt(v) *
 244                     <a class="link" href="../../sf_beta/beta_function.html" title="Beta">beta</a>(v/2,
 245                     0.5))
 246                   </p>
 247                 </td>
 248 </tr>
 249 <tr>
 250 <td>
 251                   <p>
 252                     cdf
 253                   </p>
 254                 </td>
 255 <td>
 256                   <p>
 257                     Using the relations:
 258                   </p>
 259                   <p>
 260                     p = 1 - z <span class="emphasis"><em>iff t &gt; 0</em></span>
 261                   </p>
 262                   <p>
 263                     p = z <span class="emphasis"><em>otherwise</em></span>
 264                   </p>
 265                   <p>
 266                     where z is given by:
 267                   </p>
 268                   <p>
 269                     <a class="link" href="../../sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibeta</a>(v
 270                     / 2, 0.5, v / (v + t<sup>2</sup>)) / 2 <span class="emphasis"><em>iff v &lt; 2t<sup>2</sup></em></span>
 271                   </p>
 272                   <p>
 273                     <a class="link" href="../../sf_beta/ibeta_function.html" title="Incomplete Beta Functions">ibetac</a>(0.5,
 274                     v / 2, t<sup>2 </sup> / (v + t<sup>2</sup>) / 2 <span class="emphasis"><em>otherwise</em></span>
 275                   </p>
 276                 </td>
 277 </tr>
 278 <tr>
 279 <td>
 280                   <p>
 281                     cdf complement
 282                   </p>
 283                 </td>
 284 <td>
 285                   <p>
 286                     Using the relation: q = cdf(-t)
 287                   </p>
 288                 </td>
 289 </tr>
 290 <tr>
 291 <td>
 292                   <p>
 293                     quantile
 294                   </p>
 295                 </td>
 296 <td>
 297                   <p>
 298                     Using the relation: t = sign(p - 0.5) * sqrt(v * y / x)
 299                   </p>
 300                   <p>
 301                     where:
 302                   </p>
 303                   <p>
 304                     x = <a class="link" href="../../sf_beta/ibeta_inv_function.html" title="The Incomplete Beta Function Inverses">ibeta_inv</a>(v
 305                     / 2, 0.5, 2 * min(p, q))
 306                   </p>
 307                   <p>
 308                     y = 1 - x
 309                   </p>
 310                   <p>
 311                     The quantities <span class="emphasis"><em>x</em></span> and <span class="emphasis"><em>y</em></span>
 312                     are both returned by <a class="link" href="../../sf_beta/ibeta_inv_function.html" title="The Incomplete Beta Function Inverses">ibeta_inv</a>
 313                     without the subtraction implied above.
 314                   </p>
 315                 </td>
 316 </tr>
 317 <tr>
 318 <td>
 319                   <p>
 320                     quantile from the complement
 321                   </p>
 322                 </td>
 323 <td>
 324                   <p>
 325                     Using the relation: t = -quantile(q)
 326                   </p>
 327                 </td>
 328 </tr>
 329 <tr>
 330 <td>
 331                   <p>
 332                     mode
 333                   </p>
 334                 </td>
 335 <td>
 336                   <p>
 337                     0
 338                   </p>
 339                 </td>
 340 </tr>
 341 <tr>
 342 <td>
 343                   <p>
 344                     mean
 345                   </p>
 346                 </td>
 347 <td>
 348                   <p>
 349                     0
 350                   </p>
 351                 </td>
 352 </tr>
 353 <tr>
 354 <td>
 355                   <p>
 356                     variance
 357                   </p>
 358                 </td>
 359 <td>
 360                   <p>
 361                     if (v &gt; 2) v / (v - 2) else NaN
 362                   </p>
 363                 </td>
 364 </tr>
 365 <tr>
 366 <td>
 367                   <p>
 368                     skewness
 369                   </p>
 370                 </td>
 371 <td>
 372                   <p>
 373                     if (v &gt; 3) 0 else NaN
 374                   </p>
 375                 </td>
 376 </tr>
 377 <tr>
 378 <td>
 379                   <p>
 380                     kurtosis
 381                   </p>
 382                 </td>
 383 <td>
 384                   <p>
 385                     if (v &gt; 4) 3 * (v - 2) / (v - 4) else NaN
 386                   </p>
 387                 </td>
 388 </tr>
 389 <tr>
 390 <td>
 391                   <p>
 392                     kurtosis excess
 393                   </p>
 394                 </td>
 395 <td>
 396                   <p>
 397                     if (v &gt; 4) 6 / (df - 4) else NaN
 398                   </p>
 399                 </td>
 400 </tr>
 401 </tbody>
 402 </table></div>
 403 <p>
 404           If the moment index <span class="emphasis"><em>k</em></span> is less than <span class="emphasis"><em>v</em></span>,
 405           then the moment is undefined. Evaluating the moment will throw a <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>
 406           unless ignored by a policy, when it will return <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">();</span></code>
 407         </p>
 408 <p>
 409           (For simplicity, we have not implemented the return of infinity in some
 410           cases as suggested by <a href="http://en.wikipedia.org/wiki/Student%27s_t-distribution" target="_top">Wikipedia
 411           Student's t</a>. See also <a href="https://svn.boost.org/trac/boost/ticket/7177" target="_top">https://svn.boost.org/trac/boost/ticket/7177</a>.)
 412         </p>
 413 </div>
 414 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 415 <td align="left"></td>
 416 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 417       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 418       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 419       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 420         Distributed under the Boost Software License, Version 1.0. (See accompanying
 421         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>)
 422       </p>
 423 </div></td>
 424 </tr></table>
 425 <hr>
 426 <div class="spirit-nav">
 427 <a accesskey="p" href="skew_normal_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.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="triangular_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 428 </div>
 429 </body>
 430 </html>