7 |
@file{gsl_cdf.h}. |
@file{gsl_cdf.h}. |
8 |
|
|
9 |
@menu |
@menu |
10 |
|
* Cumulative Distribution Function Usage:: |
11 |
|
* The gsl_cdf_result struct:: |
12 |
* The Gaussian CDF:: |
* The Gaussian CDF:: |
13 |
* CDF Examples:: |
* CDF Examples:: |
14 |
* CDF References and Further Reading:: |
* CDF References and Further Reading:: |
15 |
@end menu |
@end menu |
16 |
|
|
17 |
|
@node Cumulative Distribution Function Usage |
18 |
|
@section Usage |
19 |
|
|
20 |
|
Following the design of the GSL special functions, the cumulative |
21 |
|
distribution functions are available in two calling conventions, a |
22 |
|
@dfn{natural form} which returns the numerical value of the function |
23 |
|
and |
24 |
|
an @dfn{error-handling form} which returns an error code. The two |
25 |
|
types |
26 |
|
of function provide alternative ways of accessing the same underlying |
27 |
|
code. |
28 |
|
|
29 |
|
The @dfn{natural form} returns only the value of the function and can be |
30 |
|
used directly in mathematical expressions. For example, the following |
31 |
|
function call will compute the value of the Gamma cdf with |
32 |
|
scale parameter alpha and shape parameter beta. |
33 |
|
|
34 |
|
@example |
35 |
|
double y = gsl_cdf_gamma (x, alpha, beta, GSL_CDF_LOWER); |
36 |
|
@end example |
37 |
|
@noindent |
38 |
|
There is no way to access an error code or to estimate the error using |
39 |
|
this method. To allow access to this information the alternative |
40 |
|
error-handling form stores the value and error in a modifiable argument, |
41 |
|
|
42 |
|
@example |
43 |
|
gsl_cdf_result result; |
44 |
|
int status = gsl_cdf_gamma_e (x, alpha, beta, GSL_CDF_UPPER, &result); |
45 |
|
@end example |
46 |
|
@noindent |
47 |
|
The error-handling functions have the suffix @code{_e}. The returned |
48 |
|
status value indicates error conditions such as overflow, underflow or |
49 |
|
loss of precision. If there are no errors the error-handling functions |
50 |
|
return @code{GSL_SUCCESS}. |
51 |
|
|
52 |
|
@node The gsl_cdf_result struct |
53 |
|
@section The gsl_cdf_result struct |
54 |
|
@cindex gsl_cdf_result |
55 |
|
@cindex gsl_cdf_result_e10 |
56 |
|
|
57 |
|
The error handling form of the special functions always calculate an |
58 |
|
error estimate along with the value of the result. Therefore, |
59 |
|
structures are provided for amalgamating a value and error estimate. |
60 |
|
These structures are declared in the header file @file{gsl_cdf_result.h}. |
61 |
|
|
62 |
|
The @code{gsl_cdf_result} struct contains value and error fields. |
63 |
|
|
64 |
|
@example |
65 |
|
typedef struct |
66 |
|
@{ |
67 |
|
double val; |
68 |
|
double err; |
69 |
|
@} gsl_cdf_result; |
70 |
|
@end example |
71 |
|
@noindent |
72 |
|
The field @var{val} contains the value and the field @var{err} contains |
73 |
|
an estimate of the absolute error in the value. |
74 |
|
|
75 |
|
In some cases, an overflow or underflow can be detected and handled by a |
76 |
|
function. In this case, it may be possible to return a scaling exponent |
77 |
|
as well as an error/value pair in order to save the result from |
78 |
|
exceeding the dynamic range of the built-in types. The |
79 |
|
@code{gsl_cdf_result_e10} struct contains value and error fields as well |
80 |
|
as an exponent field such that the actual result is obtained as |
81 |
|
@code{result * 10^(e10)}. |
82 |
|
|
83 |
|
@example |
84 |
|
typedef struct |
85 |
|
@{ |
86 |
|
double val; |
87 |
|
double err; |
88 |
|
int e10; |
89 |
|
@} gsl_cdf_result_e10; |
90 |
|
@end example |
91 |
|
|
92 |
@page |
@page |
93 |
@node The Gaussian CDF |
@node The Gaussian CDF |
94 |
@section The Gaussian Cumulative Distribution Function |
@section The Gaussian Cumulative Distribution Function |