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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Cauchy-Lorentz 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="binomial_dist.html" title="Binomial Distribution">
  10 <link rel="next" href="chi_squared_dist.html" title="Chi Squared 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="binomial_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="chi_squared_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.cauchy_dist"></a><a class="link" href="cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy-Lorentz
  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">cauchy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
  31 <pre class="programlisting"><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>
  32           <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>
  33 <span class="keyword">class</span> <span class="identifier">cauchy_distribution</span><span class="special">;</span>
  34
  35 <span class="keyword">typedef</span> <span class="identifier">cauchy_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">cauchy</span><span class="special">;</span>
  36
  37 <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>
  38 <span class="keyword">class</span> <span class="identifier">cauchy_distribution</span>
  39 <span class="special">{</span>
  40 <span class="keyword">public</span><span class="special">:</span>
  41    <span class="keyword">typedef</span> <span class="identifier">RealType</span>  <span class="identifier">value_type</span><span class="special">;</span>
  42    <span class="keyword">typedef</span> <span class="identifier">Policy</span>    <span class="identifier">policy_type</span><span class="special">;</span>
  43
  44    <span class="identifier">cauchy_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
  45
  46    <span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
  47    <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
  48 <span class="special">};</span>
  49 </pre>
  50 <p>
  51           The <a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
  52           distribution</a> is named after Augustin Cauchy and Hendrik Lorentz.
  53           It is a <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">continuous
  54           probability distribution</a> with <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">probability
  55           distribution function PDF</a> given by:
  56         </p>
  57 <p>
  58           <span class="inlinemediaobject"><img src="../../../../equations/cauchy_ref1.svg"></span>
  59         </p>
  60 <p>
  61           The location parameter x<sub>0</sub> &#160; is the location of the peak of the distribution
  62           (the mode of the distribution), while the scale parameter &#947; &#160; specifies half
  63           the width of the PDF at half the maximum height. If the location is zero,
  64           and the scale 1, then the result is a standard Cauchy distribution.
  65         </p>
  66 <p>
  67           The distribution is important in physics as it is the solution to the differential
  68           equation describing forced resonance, while in spectroscopy it is the description
  69           of the line shape of spectral lines.
  70         </p>
  71 <p>
  72           The following graph shows how the distributions moves as the location parameter
  73           changes:
  74         </p>
  75 <p>
  76           <span class="inlinemediaobject"><img src="../../../../graphs/cauchy_pdf1.svg" align="middle"></span>
  77         </p>
  78 <p>
  79           While the following graph shows how the shape (scale) parameter alters
  80           the distribution:
  81         </p>
  82 <p>
  83           <span class="inlinemediaobject"><img src="../../../../graphs/cauchy_pdf2.svg" align="middle"></span>
  84         </p>
  85 <h5>
  86 <a name="math_toolkit.dist_ref.dists.cauchy_dist.h0"></a>
  87           <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.member_functions"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.member_functions">Member
  88           Functions</a>
  89         </h5>
  90 <pre class="programlisting"><span class="identifier">cauchy_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
  91 </pre>
  92 <p>
  93           Constructs a Cauchy distribution, with location parameter <span class="emphasis"><em>location</em></span>
  94           and scale parameter <span class="emphasis"><em>scale</em></span>. When these parameters take
  95           their default values (location = 0, scale = 1) then the result is a Standard
  96           Cauchy Distribution.
  97         </p>
  98 <p>
  99           Requires scale &gt; 0, otherwise calls <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
 100         </p>
 101 <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
 102 </pre>
 103 <p>
 104           Returns the location parameter of the distribution.
 105         </p>
 106 <pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
 107 </pre>
 108 <p>
 109           Returns the scale parameter of the distribution.
 110         </p>
 111 <h5>
 112 <a name="math_toolkit.dist_ref.dists.cauchy_dist.h1"></a>
 113           <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.non_member_accessors"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.non_member_accessors">Non-member
 114           Accessors</a>
 115         </h5>
 116 <p>
 117           All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
 118           functions</a> that are generic to all distributions are supported:
 119           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
 120           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
 121           <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>,
 122           <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>,
 123           <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>,
 124           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
 125           <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>,
 126           <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>.
 127         </p>
 128 <p>
 129           Note however that the Cauchy distribution does not have a mean, standard
 130           deviation, etc. See <a class="link" href="../../pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">mathematically
 131           undefined function</a> to control whether these should fail to compile
 132           with a BOOST_STATIC_ASSERTION_FAILURE, which is the default.
 133         </p>
 134 <p>
 135           Alternately, the functions <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>,
 136           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
 137           <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>, <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>
 138           and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>
 139           will all return a <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>
 140           if called.
 141         </p>
 142 <p>
 143           The domain of the random variable is [-[max_value], +[min_value]].
 144         </p>
 145 <h5>
 146 <a name="math_toolkit.dist_ref.dists.cauchy_dist.h2"></a>
 147           <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.accuracy"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.accuracy">Accuracy</a>
 148         </h5>
 149 <p>
 150           The Cauchy distribution is implemented in terms of the standard library
 151           <code class="computeroutput"><span class="identifier">tan</span></code> and <code class="computeroutput"><span class="identifier">atan</span></code>
 152           functions, and as such should have very low error rates.
 153         </p>
 154 <h5>
 155 <a name="math_toolkit.dist_ref.dists.cauchy_dist.h3"></a>
 156           <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.implementation"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.implementation">Implementation</a>
 157         </h5>
 158 <p>
 159           In the following table x<sub>0 </sub> is the location parameter of the distribution,
 160           &#947; &#160; is its scale parameter, <span class="emphasis"><em>x</em></span> is the random variate,
 161           <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
 162         </p>
 163 <div class="informaltable"><table class="table">
 164 <colgroup>
 165 <col>
 166 <col>
 167 </colgroup>
 168 <thead><tr>
 169 <th>
 170                   <p>
 171                     Function
 172                   </p>
 173                 </th>
 174 <th>
 175                   <p>
 176                     Implementation Notes
 177                   </p>
 178                 </th>
 179 </tr></thead>
 180 <tbody>
 181 <tr>
 182 <td>
 183                   <p>
 184                     pdf
 185                   </p>
 186                 </td>
 187 <td>
 188                   <p>
 189                     Using the relation: pdf = 1 / (&#960; * &#947; * (1 + ((x - x<sub>0 </sub>) / &#947;)<sup>2</sup>)
 190                   </p>
 191                 </td>
 192 </tr>
 193 <tr>
 194 <td>
 195                   <p>
 196                     cdf and its complement
 197                   </p>
 198                 </td>
 199 <td>
 200                   <p>
 201                     The cdf is normally given by:
 202                   </p>
 203                   <p>
 204                     p = 0.5 + atan(x)/&#960;
 205                   </p>
 206                   <p>
 207                     But that suffers from cancellation error as x -&gt; -&#8734;. So recall
 208                     that for <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span>
 209                     <span class="number">0</span></code>:
 210                   </p>
 211                   <p>
 212                     atan(x) = -&#960;/2 - atan(1/x)
 213                   </p>
 214                   <p>
 215                     Substituting into the above we get:
 216                   </p>
 217                   <p>
 218                     p = -atan(1/x) ; x &lt; 0
 219                   </p>
 220                   <p>
 221                     So the procedure is to calculate the cdf for -fabs(x) using the
 222                     above formula. Note that to factor in the location and scale
 223                     parameters you must substitute (x - x<sub>0 </sub>) / &#947; &#160; for x in the above.
 224                   </p>
 225                   <p>
 226                     This procedure yields the smaller of <span class="emphasis"><em>p</em></span> and
 227                     <span class="emphasis"><em>q</em></span>, so the result may need subtracting from
 228                     1 depending on whether we want the complement or not, and whether
 229                     <span class="emphasis"><em>x</em></span> is less than x<sub>0 </sub> or not.
 230                   </p>
 231                 </td>
 232 </tr>
 233 <tr>
 234 <td>
 235                   <p>
 236                     quantile
 237                   </p>
 238                 </td>
 239 <td>
 240                   <p>
 241                     The same procedure is used irrespective of whether we're starting
 242                     from the probability or its complement. First the argument <span class="emphasis"><em>p</em></span>
 243                     is reduced to the range [-0.5, 0.5], then the relation
 244                   </p>
 245                   <p>
 246                     x = x<sub>0 </sub> &#177; &#947; &#160; / tan(&#960; * p)
 247                   </p>
 248                   <p>
 249                     is used to obtain the result. Whether we're adding or subtracting
 250                     from x<sub>0 </sub> is determined by whether we're starting from the complement
 251                     or not.
 252                   </p>
 253                 </td>
 254 </tr>
 255 <tr>
 256 <td>
 257                   <p>
 258                     mode
 259                   </p>
 260                 </td>
 261 <td>
 262                   <p>
 263                     The location parameter.
 264                   </p>
 265                 </td>
 266 </tr>
 267 </tbody>
 268 </table></div>
 269 <h5>
 270 <a name="math_toolkit.dist_ref.dists.cauchy_dist.h4"></a>
 271           <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.references"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.references">References</a>
 272         </h5>
 273 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 274 <li class="listitem">
 275               <a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
 276               distribution</a>
 277             </li>
 278 <li class="listitem">
 279               <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm" target="_top">NIST
 280               Exploratory Data Analysis</a>
 281             </li>
 282 <li class="listitem">
 283               <a href="http://mathworld.wolfram.com/CauchyDistribution.html" target="_top">Weisstein,
 284               Eric W. "Cauchy Distribution." From MathWorld--A Wolfram
 285               Web Resource.</a>
 286             </li>
 287 </ul></div>
 288 </div>
 289 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 290 <td align="left"></td>
 291 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 292       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 293       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 294       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 295         Distributed under the Boost Software License, Version 1.0. (See accompanying
 296         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>)
 297       </p>
 298 </div></td>
 299 </tr></table>
 300 <hr>
 301 <div class="spirit-nav">
 302 <a accesskey="p" href="binomial_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="chi_squared_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 303 </div>
 304 </body>
 305 </html>