]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [section:cauchy_dist Cauchy-Lorentz Distribution] |
2 | ||
3 | ``#include <boost/math/distributions/cauchy.hpp>`` | |
4 | ||
5 | template <class RealType = double, | |
6 | class ``__Policy`` = ``__policy_class`` > | |
7 | class cauchy_distribution; | |
8 | ||
9 | typedef cauchy_distribution<> cauchy; | |
10 | ||
11 | template <class RealType, class ``__Policy``> | |
12 | class cauchy_distribution | |
13 | { | |
14 | public: | |
15 | typedef RealType value_type; | |
16 | typedef Policy policy_type; | |
17 | ||
18 | cauchy_distribution(RealType location = 0, RealType scale = 1); | |
19 | ||
20 | RealType location()const; | |
21 | RealType scale()const; | |
22 | }; | |
23 | ||
24 | The [@http://en.wikipedia.org/wiki/Cauchy_distribution Cauchy-Lorentz distribution] | |
25 | is named after Augustin Cauchy and Hendrik Lorentz. | |
26 | It is a [@http://en.wikipedia.org/wiki/Probability_distribution continuous probability distribution] | |
27 | with [@http://en.wikipedia.org/wiki/Probability_distribution probability distribution function PDF] | |
28 | given by: | |
29 | ||
30 | [equation cauchy_ref1] | |
31 | ||
32 | The location parameter x[sub 0][space] is the location of the | |
33 | peak of the distribution (the mode of the distribution), | |
34 | while the scale parameter [gamma][space] specifies half the width | |
35 | of the PDF at half the maximum height. If the location is | |
36 | zero, and the scale 1, then the result is a standard Cauchy | |
37 | distribution. | |
38 | ||
39 | The distribution is important in physics as it is the solution | |
40 | to the differential equation describing forced resonance, | |
41 | while in spectroscopy it is the description of the line shape | |
42 | of spectral lines. | |
43 | ||
44 | The following graph shows how the distributions moves as the | |
45 | location parameter changes: | |
46 | ||
47 | [graph cauchy_pdf1] | |
48 | ||
49 | While the following graph shows how the shape (scale) parameter alters | |
50 | the distribution: | |
51 | ||
52 | [graph cauchy_pdf2] | |
53 | ||
54 | [h4 Member Functions] | |
55 | ||
56 | cauchy_distribution(RealType location = 0, RealType scale = 1); | |
57 | ||
58 | Constructs a Cauchy distribution, with location parameter /location/ | |
59 | and scale parameter /scale/. When these parameters take their default | |
60 | values (location = 0, scale = 1) | |
61 | then the result is a Standard Cauchy Distribution. | |
62 | ||
63 | Requires scale > 0, otherwise calls __domain_error. | |
64 | ||
65 | RealType location()const; | |
66 | ||
67 | Returns the location parameter of the distribution. | |
68 | ||
69 | RealType scale()const; | |
70 | ||
71 | Returns the scale parameter of the distribution. | |
72 | ||
73 | [h4 Non-member Accessors] | |
74 | ||
75 | All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions] | |
76 | that are generic to all distributions are supported: __usual_accessors. | |
77 | ||
78 | Note however that the Cauchy distribution does not have a mean, | |
79 | standard deviation, etc. See __math_undefined | |
80 | [/link math_toolkit.pol_ref.assert_undefined mathematically undefined function] | |
81 | to control whether these should fail to compile with a BOOST_STATIC_ASSERTION_FAILURE, | |
82 | which is the default. | |
83 | ||
84 | Alternately, the functions __mean, __sd, | |
85 | __variance, __skewness, __kurtosis and __kurtosis_excess will all | |
86 | return a __domain_error if called. | |
87 | ||
88 | The domain of the random variable is \[-[max_value], +[min_value]\]. | |
89 | ||
90 | [h4 Accuracy] | |
91 | ||
92 | The Cauchy distribution is implemented in terms of the | |
93 | standard library `tan` and `atan` functions, | |
94 | and as such should have very low error rates. | |
95 | ||
96 | [h4 Implementation] | |
97 | ||
98 | [def __x0 x[sub 0 ]] | |
99 | ||
100 | In the following table __x0 is the location parameter of the distribution, | |
101 | [gamma][space] is its scale parameter, | |
102 | /x/ is the random variate, /p/ is the probability and /q = 1-p/. | |
103 | ||
104 | [table | |
105 | [[Function][Implementation Notes]] | |
106 | [[pdf][Using the relation: pdf = 1 / ([pi] * [gamma] * (1 + ((x - __x0) / [gamma])[super 2]) ]] | |
107 | [[cdf and its complement][ | |
108 | The cdf is normally given by: | |
109 | ||
110 | p = 0.5 + atan(x)/[pi] | |
111 | ||
112 | But that suffers from cancellation error as x -> -[infin]. | |
113 | So recall that for `x < 0`: | |
114 | ||
115 | atan(x) = -[pi]/2 - atan(1/x) | |
116 | ||
117 | Substituting into the above we get: | |
118 | ||
119 | p = -atan(1/x) ; x < 0 | |
120 | ||
121 | So the procedure is to calculate the cdf for -fabs(x) | |
122 | using the above formula. Note that to factor in the location and scale | |
123 | parameters you must substitute (x - __x0) / [gamma][space] for x in the above. | |
124 | ||
125 | This procedure yields the smaller of /p/ and /q/, so the result | |
126 | may need subtracting from 1 depending on whether we want the complement | |
127 | or not, and whether /x/ is less than __x0 or not. | |
128 | ]] | |
129 | [[quantile][The same procedure is used irrespective of whether we're starting | |
130 | from the probability or its complement. First the argument /p/ is | |
131 | reduced to the range \[-0.5, 0.5\], then the relation | |
132 | ||
133 | x = __x0 [plusminus] [gamma][space] / tan([pi] * p) | |
134 | ||
135 | is used to obtain the result. Whether we're adding | |
136 | or subtracting from __x0 is determined by whether we're | |
137 | starting from the complement or not.]] | |
138 | [[mode][The location parameter.]] | |
139 | ] | |
140 | ||
141 | [h4 References] | |
142 | ||
143 | * [@http://en.wikipedia.org/wiki/Cauchy_distribution Cauchy-Lorentz distribution] | |
144 | * [@http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm NIST Exploratory Data Analysis] | |
145 | * [@http://mathworld.wolfram.com/CauchyDistribution.html Weisstein, Eric W. "Cauchy Distribution." From MathWorld--A Wolfram Web Resource.] | |
146 | ||
147 | [endsect][/section:cauchy_dist Cauchi] | |
148 | ||
149 | [/ cauchy.qbk | |
150 | Copyright 2006, 2007 John Maddock and Paul A. Bristow. | |
151 | Distributed under the Boost Software License, Version 1.0. | |
152 | (See accompanying file LICENSE_1_0.txt or copy at | |
153 | http://www.boost.org/LICENSE_1_0.txt). | |
154 | ] |