1 |
@cindex cumulative distribution functions |
@cindex cumulative distribution functions |
2 |
|
|
3 |
This chapter describes functions for evaluating the cumulative |
This chapter describes functions for evaluating cumulative distribution |
4 |
distribution functions (CDF) for some common random variables. |
functions (CDF) of random variates. The cumulative distribution |
5 |
|
functions can be computed separately for @math{P(x)}, the lower tail of |
6 |
|
the distribution, and @math{Q(x)}, the upper tail of the distribution, |
7 |
|
allowing full accuracy to be retained for small results. |
8 |
|
|
9 |
The functions described in this section are declared in |
The functions described in this section are declared in |
10 |
@file{gsl_cdf.h}. |
@file{gsl_cdf.h}. |
11 |
|
|
12 |
@menu |
@menu |
13 |
* Cumulative Distribution Function Usage:: |
* The Gaussian CDF:: |
14 |
* The gsl_cdf_result struct:: |
* The Gaussian Quantile Function:: |
15 |
* The Gaussian CDF:: |
* The Gamma CDF:: |
16 |
* The Gaussian Quantile Function:: |
* CDF Examples:: |
17 |
* The Gamma CDF:: |
* CDF References and Further Reading:: |
|
* CDF Examples:: |
|
|
* CDF References and Further Reading:: |
|
18 |
@end menu |
@end menu |
19 |
|
|
|
@node Cumulative Distribution Function Usage |
|
|
@section Usage |
|
|
|
|
|
Following the design of the GSL special functions, the cumulative |
|
|
distribution functions are available in two calling conventions, a |
|
|
@dfn{natural form} which returns the numerical value of the function |
|
|
and |
|
|
an @dfn{error-handling form} which returns an error code. The two |
|
|
types |
|
|
of function provide alternative ways of accessing the same underlying |
|
|
code. |
|
|
|
|
|
The @dfn{natural form} returns only the value of the function and can be |
|
|
used directly in mathematical expressions. For example, the following |
|
|
function call will compute the value of the Gamma cdf with |
|
|
scale parameter alpha and shape parameter beta. |
|
|
|
|
|
@example |
|
|
double y = gsl_cdf_gamma (x, alpha, beta, GSL_CDF_LOWER); |
|
|
@end example |
|
|
@noindent |
|
|
There is no way to access an error code or to estimate the error using |
|
|
this method. To allow access to this information the alternative |
|
|
error-handling form stores the value and error in a modifiable argument, |
|
|
|
|
|
@example |
|
|
gsl_cdf_result result; |
|
|
int status = gsl_cdf_gamma_e (x, alpha, beta, GSL_CDF_UPPER, &result); |
|
|
@end example |
|
|
@noindent |
|
|
The error-handling functions have the suffix @code{_e}. The returned |
|
|
status value indicates error conditions such as overflow, underflow or |
|
|
loss of precision. If there are no errors the error-handling functions |
|
|
return @code{GSL_SUCCESS}. |
|
|
|
|
|
@node The gsl_cdf_result struct |
|
|
@section The gsl_cdf_result struct |
|
|
@cindex gsl_cdf_result |
|
|
@cindex gsl_cdf_result_e10 |
|
|
|
|
|
The error handling form of the special functions always calculate an |
|
|
error estimate along with the value of the result. Therefore, |
|
|
structures are provided for amalgamating a value and error estimate. |
|
|
These structures are declared in the header file @file{gsl_cdf_result.h}. |
|
|
|
|
|
The @code{gsl_cdf_result} struct contains value and error fields. |
|
|
|
|
|
@example |
|
|
typedef struct |
|
|
@{ |
|
|
double val; |
|
|
double err; |
|
|
@} gsl_cdf_result; |
|
|
@end example |
|
|
@noindent |
|
|
The field @var{val} contains the value and the field @var{err} contains |
|
|
an estimate of the absolute error in the value. |
|
|
|
|
|
In some cases, an overflow or underflow can be detected and handled by a |
|
|
function. In this case, it may be possible to return a scaling exponent |
|
|
as well as an error/value pair in order to save the result from |
|
|
exceeding the dynamic range of the built-in types. The |
|
|
@code{gsl_cdf_result_e10} struct contains value and error fields as well |
|
|
as an exponent field such that the actual result is obtained as |
|
|
@code{result * 10^(e10)}. |
|
|
|
|
|
@example |
|
|
typedef struct |
|
|
@{ |
|
|
double val; |
|
|
double err; |
|
|
int e10; |
|
|
@} gsl_cdf_result_e10; |
|
|
@end example |
|
|
|
|
|
@page |
|
20 |
@node The Gaussian CDF |
@node The Gaussian CDF |
21 |
@section The Gaussian Cumulative Distribution Function |
@section The Gaussian Cumulative Distribution Function |
22 |
|
|
23 |
@deftypefun double gsl_cdf_gauss (double @var{z}, gsl_cdf_tail_t @var{tail}) |
@deftypefun double gsl_cdf_gauss_P (double @var{z}) |
24 |
|
@deftypefunx double gsl_cdf_gauss_Q (double @var{z}) |
25 |
This function computes the probability @math{Pr(Z<x)} for a |
This function computes the probability @math{Pr(Z<x)} for a |
26 |
standard normal random variable @math{Z} if @math{tail=GSL_CDF_LOWER}, |
standard normal random variable @math{Z} if @math{tail=GSL_CDF_LOWER}, |
27 |
or @math{Pr(Z>x)} if @math{tail=GSL_CDF_UPPER}. A standard normal |
or @math{Pr(Z>x)} if @math{tail=GSL_CDF_UPPER}. A standard normal |
118 |
|
|
119 |
for ( i = 0; i < 4; i++ ) |
for ( i = 0; i < 4; i++ ) |
120 |
@{ |
@{ |
121 |
prob = gsl_cdf_gauss ( y[i], GSL_CDF_LOWER ); |
prob = gsl_cdf_gauss_P ( y[i] ); |
122 |
printf ( "Chance that Z is less than %f is %f.\n", |
printf ( "Probability that Z is less than %g is %f\n", |
123 |
y[i], prob); |
y[i], prob); |
124 |
@} |
@} |
125 |
|
|
126 |
for ( i = 0; i < 4; i++ ) |
for ( i = 0; i < 4; i++ ) |
127 |
@{ |
@{ |
128 |
prob = gsl_cdf_gauss ( y[i], GSL_CDF_UPPER ); |
prob = gsl_cdf_gauss_Q ( y[i] ); |
129 |
printf( "Chance that Z is greater than %f is %f.\n", |
printf( "Probability that Z is greater than %g is %f\n", |
130 |
y[i], prob ); |
y[i], prob ); |
131 |
@} |
@} |
132 |
|
|
148 |
|
|
149 |
@example |
@example |
150 |
$ ./a.out |
$ ./a.out |
151 |
Chance that Z is less than -2.300000 is 0.010724. |
Chance that Z is less than -2.300000 is 0.010724 |
152 |
Chance that Z is less than -1.400000 is 0.080757. |
Chance that Z is less than -1.400000 is 0.080757 |
153 |
Chance that Z is less than 0.320000 is 0.625516. |
Chance that Z is less than 0.320000 is 0.625516 |
154 |
Chance that Z is less than 1.500000 is 0.933193. |
Chance that Z is less than 1.500000 is 0.933193 |
155 |
Chance that Z is greater than -2.300000 is 0.989276. |
Chance that Z is greater than -2.300000 is 0.989276 |
156 |
Chance that Z is greater than -1.400000 is 0.919243. |
Chance that Z is greater than -1.400000 is 0.919243 |
157 |
Chance that Z is greater than 0.320000 is 0.374484. |
Chance that Z is greater than 0.320000 is 0.374484 |
158 |
Chance that Z is greater than 1.500000 is 0.066807. |
Chance that Z is greater than 1.500000 is 0.066807 |
159 |
@end example |
@end example |
160 |
|
|
161 |
|
|