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