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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Chi Squared 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.11.0">
   8 <link rel="up" href="../dists.html" title="Distributions">
   9 <link rel="prev" href="cauchy_dist.html" title="Cauchy-Lorentz Distribution">
  10 <link rel="next" href="empirical_cdf.html" title="Empirical Cumulative Distribution Function">
  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="cauchy_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="empirical_cdf.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.chi_squared_dist"></a><a class="link" href="chi_squared_dist.html" title="Chi Squared Distribution">Chi Squared
  28         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">chi_squared</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;20.&#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">chi_squared_distribution</span><span class="special">;</span>
  36
  37 <span class="keyword">typedef</span> <span class="identifier">chi_squared_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">chi_squared</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;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
  40 <span class="keyword">class</span> <span class="identifier">chi_squared_distribution</span>
  41 <span class="special">{</span>
  42 <span class="keyword">public</span><span class="special">:</span>
  43    <span class="keyword">typedef</span> <span class="identifier">RealType</span>  <span class="identifier">value_type</span><span class="special">;</span>
  44    <span class="keyword">typedef</span> <span class="identifier">Policy</span>    <span class="identifier">policy_type</span><span class="special">;</span>
  45
  46    <span class="comment">// Constructor:</span>
  47    <span class="identifier">chi_squared_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">i</span><span class="special">);</span>
  48
  49    <span class="comment">// Accessor to parameter:</span>
  50    <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>
  51
  52    <span class="comment">// Parameter estimation:</span>
  53    <span class="keyword">static</span> <span class="identifier">RealType</span> <span class="identifier">find_degrees_of_freedom</span><span class="special">(</span>
  54       <span class="identifier">RealType</span> <span class="identifier">difference_from_mean</span><span class="special">,</span>
  55       <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
  56       <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
  57       <span class="identifier">RealType</span> <span class="identifier">sd</span><span class="special">,</span>
  58       <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
  59 <span class="special">};</span>
  60
  61 <span class="special">}}</span> <span class="comment">// namespaces</span>
  62 </pre>
  63 <p>
  64           The Chi-Squared distribution is one of the most widely used distributions
  65           in statistical tests. If &#967;<sub>i</sub> are &#957;
  66 independent, normally distributed random
  67           variables with means &#956;<sub>i</sub> and variances &#963;<sub>i</sub><sup>2</sup>, then the random variable:
  68         </p>
  69 <div class="blockquote"><blockquote class="blockquote"><p>
  70             <span class="inlinemediaobject"><img src="../../../../equations/chi_squ_ref1.svg"></span>
  71
  72           </p></blockquote></div>
  73 <p>
  74           is distributed according to the Chi-Squared distribution.
  75         </p>
  76 <p>
  77           The Chi-Squared distribution is a special case of the gamma distribution
  78           and has a single parameter &#957; that specifies the number of degrees of freedom.
  79           The following graph illustrates how the distribution changes for different
  80           values of &#957;:
  81         </p>
  82 <div class="blockquote"><blockquote class="blockquote"><p>
  83             <span class="inlinemediaobject"><img src="../../../../graphs/chi_squared_pdf.svg" align="middle"></span>
  84
  85           </p></blockquote></div>
  86 <h5>
  87 <a name="math_toolkit.dist_ref.dists.chi_squared_dist.h0"></a>
  88           <span class="phrase"><a name="math_toolkit.dist_ref.dists.chi_squared_dist.member_functions"></a></span><a class="link" href="chi_squared_dist.html#math_toolkit.dist_ref.dists.chi_squared_dist.member_functions">Member
  89           Functions</a>
  90         </h5>
  91 <pre class="programlisting"><span class="identifier">chi_squared_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">v</span><span class="special">);</span>
  92 </pre>
  93 <p>
  94           Constructs a Chi-Squared distribution with <span class="emphasis"><em>v</em></span> degrees
  95           of freedom.
  96         </p>
  97 <p>
  98           Requires v &gt; 0, otherwise calls <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
  99         </p>
 100 <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>
 101 </pre>
 102 <p>
 103           Returns the parameter <span class="emphasis"><em>v</em></span> from which this object was
 104           constructed.
 105         </p>
 106 <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>
 107    <span class="identifier">RealType</span> <span class="identifier">difference_from_variance</span><span class="special">,</span>
 108    <span class="identifier">RealType</span> <span class="identifier">alpha</span><span class="special">,</span>
 109    <span class="identifier">RealType</span> <span class="identifier">beta</span><span class="special">,</span>
 110    <span class="identifier">RealType</span> <span class="identifier">variance</span><span class="special">,</span>
 111    <span class="identifier">RealType</span> <span class="identifier">hint</span> <span class="special">=</span> <span class="number">100</span><span class="special">);</span>
 112 </pre>
 113 <p>
 114           Estimates the sample size required to detect a difference from a nominal
 115           variance in a Chi-Squared test for equal standard deviations.
 116         </p>
 117 <div class="variablelist">
 118 <p class="title"><b></b></p>
 119 <dl class="variablelist">
 120 <dt><span class="term">difference_from_variance</span></dt>
 121 <dd><p>
 122                 The difference from the assumed nominal variance that is to be detected:
 123                 Note that the sign of this value is critical, see below.
 124               </p></dd>
 125 <dt><span class="term">alpha</span></dt>
 126 <dd><p>
 127                 The maximum acceptable risk of rejecting the null hypothesis when
 128                 it is in fact true.
 129               </p></dd>
 130 <dt><span class="term">beta</span></dt>
 131 <dd><p>
 132                 The maximum acceptable risk of falsely failing to reject the null
 133                 hypothesis.
 134               </p></dd>
 135 <dt><span class="term">variance</span></dt>
 136 <dd><p>
 137                 The nominal variance being tested against.
 138               </p></dd>
 139 <dt><span class="term">hint</span></dt>
 140 <dd><p>
 141                 An optional hint on where to start looking for a result: the current
 142                 sample size would be a good choice.
 143               </p></dd>
 144 </dl>
 145 </div>
 146 <p>
 147           Note that this calculation works with <span class="emphasis"><em>variances</em></span> and
 148           not <span class="emphasis"><em>standard deviations</em></span>.
 149         </p>
 150 <p>
 151           The sign of the parameter <span class="emphasis"><em>difference_from_variance</em></span>
 152           is important: the Chi Squared distribution is asymmetric, and the caller
 153           must decide in advance whether they are testing for a variance greater
 154           than a nominal value (positive <span class="emphasis"><em>difference_from_variance</em></span>)
 155           or testing for a variance less than a nominal value (negative <span class="emphasis"><em>difference_from_variance</em></span>).
 156           If the latter, then obviously it is a requirement that <code class="computeroutput"><span class="identifier">variance</span>
 157           <span class="special">+</span> <span class="identifier">difference_from_variance</span>
 158           <span class="special">&gt;</span> <span class="number">0</span></code>,
 159           since no sample can have a negative variance!
 160         </p>
 161 <p>
 162           This procedure uses the method in Diamond, W. J. (1989). Practical Experiment
 163           Designs, Van-Nostrand Reinhold, New York.
 164         </p>
 165 <p>
 166           See also section on Sample sizes required in <a href="http://www.itl.nist.gov/div898/handbook/prc/section2/prc232.htm" target="_top">the
 167           NIST Engineering Statistics Handbook, Section 7.2.3.2</a>.
 168         </p>
 169 <h5>
 170 <a name="math_toolkit.dist_ref.dists.chi_squared_dist.h1"></a>
 171           <span class="phrase"><a name="math_toolkit.dist_ref.dists.chi_squared_dist.non_member_accessors"></a></span><a class="link" href="chi_squared_dist.html#math_toolkit.dist_ref.dists.chi_squared_dist.non_member_accessors">Non-member
 172           Accessors</a>
 173         </h5>
 174 <p>
 175           All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
 176           functions</a> that are generic to all distributions are supported:
 177           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
 178           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
 179           <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>,
 180           <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>,
 181           <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>,
 182           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
 183           <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>,
 184           <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>.
 185         </p>
 186 <p>
 187           (We have followed the usual restriction of the mode to degrees of freedom
 188           &gt;= 2, but note that the maximum of the pdf is actually zero for degrees
 189           of freedom from 2 down to 0, and provide an extended definition that would
 190           avoid a discontinuity in the mode as alternative code in a comment).
 191         </p>
 192 <p>
 193           The domain of the random variable is [0, +&#8734;].
 194         </p>
 195 <h5>
 196 <a name="math_toolkit.dist_ref.dists.chi_squared_dist.h2"></a>
 197           <span class="phrase"><a name="math_toolkit.dist_ref.dists.chi_squared_dist.examples"></a></span><a class="link" href="chi_squared_dist.html#math_toolkit.dist_ref.dists.chi_squared_dist.examples">Examples</a>
 198         </h5>
 199 <p>
 200           Various <a class="link" href="../../stat_tut/weg/cs_eg.html" title="Chi Squared Distribution Examples">worked examples</a>
 201           are available illustrating the use of the Chi Squared Distribution.
 202         </p>
 203 <h5>
 204 <a name="math_toolkit.dist_ref.dists.chi_squared_dist.h3"></a>
 205           <span class="phrase"><a name="math_toolkit.dist_ref.dists.chi_squared_dist.accuracy"></a></span><a class="link" href="chi_squared_dist.html#math_toolkit.dist_ref.dists.chi_squared_dist.accuracy">Accuracy</a>
 206         </h5>
 207 <p>
 208           The Chi-Squared distribution is implemented in terms of the <a class="link" href="../../sf_gamma/igamma.html" title="Incomplete Gamma Functions">incomplete
 209           gamma functions</a>: please refer to the accuracy data for those functions.
 210         </p>
 211 <h5>
 212 <a name="math_toolkit.dist_ref.dists.chi_squared_dist.h4"></a>
 213           <span class="phrase"><a name="math_toolkit.dist_ref.dists.chi_squared_dist.implementation"></a></span><a class="link" href="chi_squared_dist.html#math_toolkit.dist_ref.dists.chi_squared_dist.implementation">Implementation</a>
 214         </h5>
 215 <p>
 216           In the following table <span class="emphasis"><em>v</em></span> is the number of degrees
 217           of freedom of the distribution, <span class="emphasis"><em>x</em></span> is the random variate,
 218           <span class="emphasis"><em>p</em></span> is the probability, and <span class="emphasis"><em>q = 1-p</em></span>.
 219         </p>
 220 <div class="informaltable"><table class="table">
 221 <colgroup>
 222 <col>
 223 <col>
 224 </colgroup>
 225 <thead><tr>
 226 <th>
 227                   <p>
 228                     Function
 229                   </p>
 230                 </th>
 231 <th>
 232                   <p>
 233                     Implementation Notes
 234                   </p>
 235                 </th>
 236 </tr></thead>
 237 <tbody>
 238 <tr>
 239 <td>
 240                   <p>
 241                     pdf
 242                   </p>
 243                 </td>
 244 <td>
 245                   <p>
 246                     Using the relation: pdf = <a class="link" href="../../sf_gamma/gamma_derivatives.html" title="Derivative of the Incomplete Gamma Function">gamma_p_derivative</a>(v
 247                     / 2, x / 2) / 2
 248                   </p>
 249                 </td>
 250 </tr>
 251 <tr>
 252 <td>
 253                   <p>
 254                     cdf
 255                   </p>
 256                 </td>
 257 <td>
 258                   <p>
 259                     Using the relation: p = <a class="link" href="../../sf_gamma/igamma.html" title="Incomplete Gamma Functions">gamma_p</a>(v
 260                     / 2, x / 2)
 261                   </p>
 262                 </td>
 263 </tr>
 264 <tr>
 265 <td>
 266                   <p>
 267                     cdf complement
 268                   </p>
 269                 </td>
 270 <td>
 271                   <p>
 272                     Using the relation: q = <a class="link" href="../../sf_gamma/igamma.html" title="Incomplete Gamma Functions">gamma_q</a>(v
 273                     / 2, x / 2)
 274                   </p>
 275                 </td>
 276 </tr>
 277 <tr>
 278 <td>
 279                   <p>
 280                     quantile
 281                   </p>
 282                 </td>
 283 <td>
 284                   <p>
 285                     Using the relation: x = 2 * <a class="link" href="../../sf_gamma/igamma_inv.html" title="Incomplete Gamma Function Inverses">gamma_p_inv</a>(v
 286                     / 2, p)
 287                   </p>
 288                 </td>
 289 </tr>
 290 <tr>
 291 <td>
 292                   <p>
 293                     quantile from the complement
 294                   </p>
 295                 </td>
 296 <td>
 297                   <p>
 298                     Using the relation: x = 2 * <a class="link" href="../../sf_gamma/igamma_inv.html" title="Incomplete Gamma Function Inverses">gamma_q_inv</a>(v
 299                     / 2, p)
 300                   </p>
 301                 </td>
 302 </tr>
 303 <tr>
 304 <td>
 305                   <p>
 306                     mean
 307                   </p>
 308                 </td>
 309 <td>
 310                   <p>
 311                     v
 312                   </p>
 313                 </td>
 314 </tr>
 315 <tr>
 316 <td>
 317                   <p>
 318                     variance
 319                   </p>
 320                 </td>
 321 <td>
 322                   <p>
 323                     2v
 324                   </p>
 325                 </td>
 326 </tr>
 327 <tr>
 328 <td>
 329                   <p>
 330                     mode
 331                   </p>
 332                 </td>
 333 <td>
 334                   <p>
 335                     v - 2 (if v &gt;= 2)
 336                   </p>
 337                 </td>
 338 </tr>
 339 <tr>
 340 <td>
 341                   <p>
 342                     skewness
 343                   </p>
 344                 </td>
 345 <td>
 346                   <p>
 347                     2 * sqrt(2 / v) == sqrt(8 / v)
 348                   </p>
 349                 </td>
 350 </tr>
 351 <tr>
 352 <td>
 353                   <p>
 354                     kurtosis
 355                   </p>
 356                 </td>
 357 <td>
 358                   <p>
 359                     3 + 12 / v
 360                   </p>
 361                 </td>
 362 </tr>
 363 <tr>
 364 <td>
 365                   <p>
 366                     kurtosis excess
 367                   </p>
 368                 </td>
 369 <td>
 370                   <p>
 371                     12 / v
 372                   </p>
 373                 </td>
 374 </tr>
 375 </tbody>
 376 </table></div>
 377 <h5>
 378 <a name="math_toolkit.dist_ref.dists.chi_squared_dist.h5"></a>
 379           <span class="phrase"><a name="math_toolkit.dist_ref.dists.chi_squared_dist.references"></a></span><a class="link" href="chi_squared_dist.html#math_toolkit.dist_ref.dists.chi_squared_dist.references">References</a>
 380         </h5>
 381 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 382 <li class="listitem">
 383               <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm" target="_top">NIST
 384               Exploratory Data Analysis</a>
 385             </li>
 386 <li class="listitem">
 387               <a href="http://en.wikipedia.org/wiki/Chi-square_distribution" target="_top">Chi-square
 388               distribution</a>
 389             </li>
 390 <li class="listitem">
 391               <a href="http://mathworld.wolfram.com/Chi-SquaredDistribution.html" target="_top">Weisstein,
 392               Eric W. "Chi-Squared Distribution." From MathWorld--A Wolfram
 393               Web Resource.</a>
 394             </li>
 395 </ul></div>
 396 </div>
 397 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 398 <td align="left"></td>
 399 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
 400       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
 401       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
 402       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
 403       Daryle Walker and Xiaogang Zhang<p>
 404         Distributed under the Boost Software License, Version 1.0. (See accompanying
 405         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>)
 406       </p>
 407 </div></td>
 408 </tr></table>
 409 <hr>
 410 <div class="spirit-nav">
 411 <a accesskey="p" href="cauchy_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="empirical_cdf.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 412 </div>
 413 </body>
 414 </html>