boost/math
2
0
Fork 0
mirror of https://github.com/boostorg/math.git synced 2026-01-30 20:12:09 +00:00
Code Issues Projects Releases Wiki Activity
Files
develop
math/doc/html/math_toolkit/dist_ref/dists/cauchy_dist.html
Matt Borland 8f843fd131 Merge branch 'master' into develop
2024-10-29 08:51:15 -04:00

310 lines
19 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Cauchy-Lorentz Distribution</title>
<link rel="stylesheet" href="../../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Math Toolkit 4.2.1">
<link rel="up" href="../dists.html" title="Distributions">
<link rel="prev" href="binomial_dist.html" title="Binomial Distribution">
<link rel="next" href="chi_squared_dist.html" title="Chi Squared Distribution">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="math_toolkit.dist_ref.dists.cauchy_dist"></a><a class="link" href="cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy-Lorentz
Distribution</a>
</h4></div></div></div>
<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>
<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>
<span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter 22. 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>
<span class="keyword">class</span> <span class="identifier">cauchy_distribution</span><span class="special">;</span>
<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>
<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 22. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">cauchy_distribution</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="keyword">typedef</span> <span class="identifier">RealType</span> <span class="identifier">value_type</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">Policy</span> <span class="identifier">policy_type</span><span class="special">;</span>
<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>
<span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
<span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
The <a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
distribution</a> is named after Augustin Cauchy and Hendrik Lorentz.
It is a <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">continuous
probability distribution</a> with <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">probability
distribution function PDF</a> given by:
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="inlinemediaobject"><img src="../../../../equations/cauchy_ref1.svg"></span>
</p></blockquote></div>
<p>
The location parameter <span class="emphasis"><em>x<sub>0</sub></em></span> is the location of the peak
of the distribution (the mode of the distribution), while the scale parameter
γ specifies half the width of the PDF at half the maximum height. If the
location is zero, and the scale 1, then the result is a standard Cauchy
distribution.
</p>
<p>
The distribution is important in physics as it is the solution to the differential
equation describing forced resonance, while in spectroscopy it is the description
of the line shape of spectral lines.
</p>
<p>
The following graph shows how the distributions moves as the location parameter
changes:
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="inlinemediaobject"><img src="../../../../graphs/cauchy_pdf1.svg" align="middle"></span>
</p></blockquote></div>
<p>
While the following graph shows how the shape (scale) parameter alters
the distribution:
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="inlinemediaobject"><img src="../../../../graphs/cauchy_pdf2.svg" align="middle"></span>
</p></blockquote></div>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h0"></a>
<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
Functions</a>
</h5>
<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>
</pre>
<p>
Constructs a Cauchy distribution, with location parameter <span class="emphasis"><em>location</em></span>
and scale parameter <span class="emphasis"><em>scale</em></span>. When these parameters take
their default values (location = 0, scale = 1) then the result is a Standard
Cauchy Distribution.
</p>
<p>
Requires scale &gt; 0, otherwise calls <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
</p>
<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>
</pre>
<p>
Returns the location parameter of the distribution.
</p>
<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>
</pre>
<p>
Returns the scale parameter of the distribution.
</p>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h1"></a>
<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
Accessors</a>
</h5>
<p>
All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
functions</a> that are generic to all distributions are supported:
<a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
<a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
<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>,
<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>,
<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>,
<a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</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>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>,
<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>.
</p>
<p>
Note however that the Cauchy distribution does not have a mean, standard
deviation, etc. See <a class="link" href="../../pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">mathematically
undefined function</a> to control whether these should fail to compile
with a BOOST_STATIC_ASSERTION_FAILURE, which is the default.
</p>
<p>
Alternately, the functions <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.sd">standard deviation</a>,
<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>
and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>
will all return a <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>
if called.
</p>
<p>
The domain of the random variable is [-[max_value], +[min_value]].
</p>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h2"></a>
<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>
</h5>
<p>
The Cauchy distribution is implemented in terms of the standard library
<code class="computeroutput"><span class="identifier">tan</span></code> and <code class="computeroutput"><span class="identifier">atan</span></code>
functions, and as such should have very low error rates.
</p>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h3"></a>
<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>
</h5>
<p>
In the following table x<sub>0 </sub> is the location parameter of the distribution,
γ is its scale parameter, <span class="emphasis"><em>x</em></span> is the random variate,
<span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Function
</p>
</th>
<th>
<p>
Implementation Notes
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
pdf
</p>
</td>
<td>
<p>
Using the relation: <span class="emphasis"><em>pdf = 1 / (π * γ * (1 + ((x - x<sub>0 </sub>)
/ γ)<sup>2</sup>) </em></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
cdf and its complement
</p>
</td>
<td>
<p>
The cdf is normally given by:
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="serif_italic">p = 0.5 + atan(x)/π</span>
</p></blockquote></div>
<p>
But that suffers from cancellation error as x -&gt; -∞. So recall
that for <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span>
<span class="number">0</span></code>:
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="serif_italic">atan(x) = -π/2 - atan(1/x)</span>
</p></blockquote></div>
<p>
Substituting into the above we get:
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="serif_italic">p = -atan(1/x)/π ; x &lt; 0</span>
</p></blockquote></div>
<p>
So the procedure is to calculate the cdf for -fabs(x) using the
above formula. Note that to factor in the location and scale
parameters you must substitute (x - x<sub>0 </sub>) / γ for x in the above.
</p>
<p>
This procedure yields the smaller of <span class="emphasis"><em>p</em></span> and
<span class="emphasis"><em>q</em></span>, so the result may need subtracting from
1 depending on whether we want the complement or not, and whether
<span class="emphasis"><em>x</em></span> is less than x<sub>0 </sub> or not.
</p>
</td>
</tr>
<tr>
<td>
<p>
quantile
</p>
</td>
<td>
<p>
The same procedure is used irrespective of whether we're starting
from the probability or its complement. First the argument <span class="emphasis"><em>p</em></span>
is reduced to the range [-0.5, 0.5], then the relation
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="serif_italic">x = x<sub>0 </sub> ± γ / tan(π * p)</span>
</p></blockquote></div>
<p>
is used to obtain the result. Whether we're adding or subtracting
from x<sub>0 </sub> is determined by whether we're starting from the complement
or not.
</p>
</td>
</tr>
<tr>
<td>
<p>
mode
</p>
</td>
<td>
<p>
The location parameter.
</p>
</td>
</tr>
</tbody>
</table></div>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h4"></a>
<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>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
distribution</a>
</li>
<li class="listitem">
<a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm" target="_top">NIST
Exploratory Data Analysis</a>
</li>
<li class="listitem">
<a href="http://mathworld.wolfram.com/CauchyDistribution.html" target="_top">Weisstein,
Eric W. "Cauchy Distribution." From MathWorld--A Wolfram
Web Resource.</a>
</li>
</ul></div>
</div>
<div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
Walker and Xiaogang Zhang<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink