/[gsl]/gsl/doc/cdf.texi
ViewVC logotype

Diff of /gsl/doc/cdf.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1.2.4 by jstover, Thu Jan 23 02:42:35 2003 UTC revision 1.1.2.5 by bjg, Sat Jun 28 18:08:40 2003 UTC
# Line 1  Line 1 
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
# Line 192  main (void) Line 118  main (void)
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    
# Line 222  Here is the output of the program, Line 148  Here is the output of the program,
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    

Legend:
Removed from v.1.1.2.4  
changed lines
  Added in v.1.1.2.5

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26