## P-values

P-values — probability values for test statistics and related functionality

## Functions

 double gamma_function () double ln_gamma () double digamma () double binomial_cdf () double binomial_cdf_comp () double binomial_pmf () double poisson_pmf () double x_factorial () double log_x_factorial () double normal_pvalue_2 () double normal_pvalue_1 () double student_pvalue_2 () double student_pvalue_1 () double chisq_cdf () double chisq_cdf_comp () double nc_chisq_cdf () double snedecor_cdf () double snedecor_cdf_comp () double snedecor_critval () double nc_snedecor_cdf () double normal_cdf () double normal_cdf_inverse () double normal_cdf_comp () double student_cdf () double student_cdf_inverse () double nc_student_cdf () double nc_student_pdf () double normal_pdf () double normal_critval () double student_critval () double log_normal_pdf () double gamma_cdf () double gamma_cdf_comp () double gamma_cdf_inverse () double GED_pdf () double GED_cdf () double GED_cdf_comp () double GED_cdf_inverse () double tcrit95 () double rhocrit95 () double cephes_gamma () double cephes_lgamma () double gretl_get_pvalue () double gretl_get_pdf () int gretl_fill_pdf_array () double gretl_get_cdf () double gretl_get_cdf_inverse () double gretl_get_critval () int gretl_fill_random_series () gretl_matrix * gretl_get_random_matrix () double gretl_get_random_scalar () int batch_pvalue () void print_pvalue () void print_critval () gretl_matrix * gretl_get_DW () int dist_code_from_string ()

## Types and Values

 enum DistCode

## Includes

```#include <libgretl.h>
```

## Description

Libgretl uses the cephes library, developed by Stephen Moshier, as the basic engine for much of the functionality herein. We add some extra distributions, and wrap the cephes functions for ease of use with libgretl (e.g. on failure they return the libgretl missing value code, `NADBL`).

## Functions

### gamma_function ()

```double
gamma_function (`double x`);```

#### Parameters

 x argument.

#### Returns

the gamma function of `x` , or NADBL on failure.

### ln_gamma ()

```double
ln_gamma (`double x`);```

#### Parameters

 x argument.

#### Returns

the log gamma function of `x` , or NADBL on failure.

### digamma ()

```double
digamma (`double x`);```

#### Parameters

 x argument.

#### Returns

the digamma (or Psi) function of `x` , or NADBL on failure.

### binomial_cdf ()

```double
binomial_cdf (`double p`,
`int n`,
`int k`);```

#### Parameters

 p probability of success on each trial. n number of trials. k maximum number of successes.

#### Returns

the probability of `k` or less successes on `n` trials given binomial probability `p` , or NADBL on failure.

### binomial_cdf_comp ()

```double
binomial_cdf_comp (`double p`,
`int n`,
`int k`);```

#### Parameters

 p probability of success on each trial. n number of trials. k maximum number of successes.

#### Returns

the probability of `k` + 1 or more successes on `n` trials given binomial probability `p` , or NADBL on failure.

### binomial_pmf ()

```double
binomial_pmf (`double p`,
`int n`,
`int k`);```

#### Parameters

 p success probability. n number of trials. k number of successes.

#### Returns

the probability mass for `k` successes in `n` binomial trials with success probability `p` .

### poisson_pmf ()

```double
poisson_pmf (`double lambda`,
`int k`);```

#### Parameters

 lambda mean (also variance). k test value.

#### Returns

the probability mass at `k` , for an r.v. that follows the Poisson distribution with parameter `lambda` .

### x_factorial ()

```double
x_factorial (`double x`);```

#### Parameters

 x input value.

#### Returns

the factorial of int(x), cast to a double, or NADBL on failure.

### log_x_factorial ()

```double
log_x_factorial (`double x`);```

#### Parameters

 x input value.

#### Returns

the log of the factorial of int(x), cast to a double, or NADBL on failure.

### normal_pvalue_2 ()

```double
normal_pvalue_2 (`double x`);```

Calculates the two-sided p-value for `x` in relation to the standard normal distribution.

#### Parameters

 x double-precision value.

#### Returns

2 times (1 minus the value of the standard normal CDF evaluated at abs(`x` )), or 0 on underflow.

### normal_pvalue_1 ()

```double
normal_pvalue_1 (`double x`);```

Calculates the one-sided p-value for `x` in relation to the standard normal distribution (that is, the probability that a random variable distributed as N(0, 1) is greater than `x` ).

#### Parameters

 x double-precision value.

#### Returns

1 minus the value of the standard normal CDF evaluated at `x` .

### student_pvalue_2 ()

```double
student_pvalue_2 (`double df`,
`double x`);```

#### Parameters

 df degrees of freedom. x the cutoff point in the distribution.

#### Returns

the probability that t(`df` ) is greater than `x` (two-sided, using the absolute value of `x` ), or NADBL on failure.

### student_pvalue_1 ()

```double
student_pvalue_1 (`double df`,
`double x`);```

#### Parameters

 df degrees of freedom. x the cutoff point in the distribution.

#### Returns

the probability that t(`df` ) is greater than `x` , or NADBL on failure.

### chisq_cdf ()

```double
chisq_cdf (`double df`,
`double x`);```

#### Parameters

 df degrees of freedom. x the cutoff point in the distribution.

#### Returns

the integral from 0 to `x` of the chi-square distribution with `df` degrees of freedom, or NADBL on failure.

### chisq_cdf_comp ()

```double
chisq_cdf_comp (`double df`,
`double x`);```

#### Parameters

 df degrees of freedom. x the cutoff point in the distribution.

#### Returns

the integral from `x` to infinity of the chi-square distribution with `df` degrees of freedom, or NADBL on failure.

### nc_chisq_cdf ()

```double
nc_chisq_cdf (`double df`,
`double delta`,
`double x`);```

Calculates the value at `x` of the CDF of the noncentral chi^2 distribution with `df` dof and noncentrality parameter equal to `delta` .

This is a version of `cumchn()` from dcdflib, de-spaghettized by Jack Lucchetti (2015-06-21). The original algorithm uses formula 26.4.25 from Abramowitz and Stegun, Handbook of Mathematical Functions, US NBS (1966).

#### Parameters

 df degrees of freedom. delta noncentrality parameter. x reference value.

#### Returns

the calculated probability, or NADBL on failure.

### snedecor_cdf ()

```double
snedecor_cdf (`double dfn`,
`double dfd`,
`double x`);```

#### Parameters

 dfn numerator degrees of freedom. dfd denominator degrees of freedom. x the cutoff point in the distribution.

#### Returns

the integral of the F distribution with `dfn` and `dfd` degrees of freedom, from 0 to `x` , or NADBL on failure.

### snedecor_cdf_comp ()

```double
snedecor_cdf_comp (`double dfn`,
`double dfd`,
`double x`);```

#### Parameters

 dfn numerator degrees of freedom. dfd denominator degrees of freedom. x the cutoff point in the distribution.

#### Returns

the integral of the F distribution with `dfn` and `dfd` degrees of freedom, from `x` to infinity, or NADBL on failure.

### snedecor_critval ()

```double
snedecor_critval (`double dfn`,
`double dfd`,
`double a`);```

#### Parameters

 dfn numerator degrees of freedom. dfd denominator degrees of freedom. a right-tail probability.

#### Returns

the F argument x such that the integral from x to infinity of the F density is equal to the given probability `a` , or NADBL on failure.

### nc_snedecor_cdf ()

```double
nc_snedecor_cdf (`double dfn`,
`double dfd`,
`double delta`,
`double x`);```

Calculates the value at `x` of the CDF of the noncentral F distribution with `dfn` , `dfd` dof and noncentrality parameter equal to `delta` .

This is a version of `cumfnc()` from dcdflib, de-spaghettized by Jack Lucchetti (2015-06-21). The original algorithm uses formula 26.6.18 from Abramowitz and Stegun, Handbook of Mathematical Functions, US NBS (1966).

#### Parameters

 dfn degrees of freedom (num). dfd degrees of freedom (den). delta noncentrality parameter. x reference value.

#### Returns

the calculated probability, or NADBL on failure.

### normal_cdf ()

```double
normal_cdf (`double x`);```

#### Parameters

 x double-precision value.

#### Returns

the value of the standard normal CDF evaluated at `x` , or NADBL on failure.

### normal_cdf_inverse ()

```double
normal_cdf_inverse (`double x`);```

#### Parameters

 x double-precision value.

#### Returns

the argument, y, for which the area under the Gaussian probability density function (integrated from minus infinity to y) is equal to x, or NADBL on failure.

### normal_cdf_comp ()

```double
normal_cdf_comp (`double x`);```

#### Parameters

 x the cutoff point in the distribution.

#### Returns

the integral from `x` to infinity of the standard normal distribution, or NADBL on failure.

### student_cdf ()

```double
student_cdf (`double df`,
`double x`);```

#### Parameters

 df degrees of freedom. x the cutoff point in the distribution.

#### Returns

the integral from minus infinity to `x` of the Student's t distribution with `df` degrees of freedom, or NADBL on failure.

### student_cdf_inverse ()

```double
student_cdf_inverse (`double df`,
`double a`);```

#### Parameters

 df degrees of freedom. a probability.

#### Returns

the argument x such that the integral from minus infinity to `x` of the t(`df` ) density is equal to the given probability `a` , or NADBL on failure.

### nc_student_cdf ()

```double
nc_student_cdf (`double df`,
`double delta`,
`double x`);```

Calculates the value at `x` of the CDF of the noncentral Student t distribution with `df` dof and noncentrality parameter equal to `delta` . The algorithm is by Benson-Krishnamoorthy (2003) CSDA 43, with minimal changes.

#### Parameters

 df degrees of freedom. delta noncentrality parameter. x reference value.

#### Returns

the calculated probability, or NADBL on failure.

### nc_student_pdf ()

```double
nc_student_pdf (`double df`,
`double delta`,
`double x`);```

Calculates the value at `x` of the PDF of the noncentral Student t distribution with `df` dof and noncentrality parameter equal to `delta` . The algorithm is from Wikipedia, apparently used in R too.

#### Parameters

 df degrees of freedom. delta noncentrality parameter. x reference value.

#### Returns

the calculated density, or NADBL on failure.

### normal_pdf ()

```double
normal_pdf (`double x`);```

#### Parameters

 x double-precision value.

#### Returns

the value of the standard normal PDF evaluated at `x` .

### normal_critval ()

```double
normal_critval (`double a`);```

#### Parameters

 a right-tail probability.

#### Returns

the argument z such that the integral from z to infinity of the standard normal density is equal to the given probability `a` , or NADBL on failure.

### student_critval ()

```double
student_critval (`double df`,
`double a`);```

#### Parameters

 df degrees of freedom. a right-tail probability.

#### Returns

the argument x such that the integral from x to infinity of the t(`df` ) density is equal to the given probability `a` , or NADBL on failure.

### log_normal_pdf ()

```double
log_normal_pdf (`double x`);```

#### Parameters

 x double-precision value.

#### Returns

the value of the log-normal PDF evaluated at `x` .

### gamma_cdf ()

```double
gamma_cdf (`double s1`,
`double s2`,
`double x`,
`int control`);```

Calculates the value of the CDF of the gamma distribution at `x` . If `control` equals 1, then it is assumed that the parameters `s1` and `s2` represent the shape and scale, respectively, otherwise it is assumed they give mean and variance.

#### Parameters

 s1 first parameter. s2 second parameter. x reference value. control see below.

#### Returns

the calculated probability, or NADBL on failure.

### gamma_cdf_comp ()

```double
gamma_cdf_comp (`double s1`,
`double s2`,
`double x`,
`int control`);```

Calculates the complement of the CDF of the gamma distribution at `x` . If `control` equals 1, then it is assumed that the parameters `s1` and `s2` represent the shape and scale, respectively, otherwise it is assumed they give mean and variance.

#### Parameters

 s1 first parameter. s2 second parameter. x reference value. control see below.

#### Returns

the calculated probability, or NADBL on failure.

### gamma_cdf_inverse ()

```double
gamma_cdf_inverse (`double shape`,
`double scale`,
`double p`);```

#### Parameters

 shape shape. scale scale. p probability.

#### Returns

the argument x such that the integral from zero to `x` of the gamma density with given scale and shape parameters is equal to the given probability `p` , or NADBL on failure. Note that the alternate parametrization (mean, variance) is not supported.

### GED_pdf ()

```double
GED_pdf (`double nu`,
`double x`);```

#### Parameters

 nu shape parameter. x double.

#### Returns

the density function of the Generalized Error distribution with shape parameter `nu` at `x` , or NADBL on failure.

### GED_cdf ()

```double
GED_cdf (`double nu`,
`double x`);```

Calculates the value of the CDF of the Generalized Error distribution with parameter `nu` at `x` . We exploit the fact that if x ~ GED(n), then |x/k|^n is a Gamma rv.

#### Parameters

 nu shape parameter. x reference value.

#### Returns

the calculated probability, or NADBL on failure.

### GED_cdf_comp ()

```double
GED_cdf_comp (`double nu`,
`double x`);```

Calculates the complement of the CDF of the Generalized Error distribution with parameter `nu` at `x` . We exploit the fact that if x ~ GED(n), then |x/k|^n is a Gamma rv.

#### Parameters

 nu shape parameter. x reference value.

#### Returns

the calculated probability, or NADBL on failure.

### GED_cdf_inverse ()

```double
GED_cdf_inverse (`double nu`,
`double a`);```

#### Parameters

 nu shape parameter. a probability.

#### Returns

the argument x such that the integral from minus infinity to `x` of the standardized GED density with shape parameter `nu` is equal to the given probability `a` , or NADBL on failure. We exploit the well-known relationship between the standardized GED and the Gamma variates.

### tcrit95 ()

```double
tcrit95 (`int df`);```

#### Parameters

 df degrees of freedom.

#### Returns

the two-sided 95 percent critical value for the t distribution with `df` degrees of freedom, or NADBL on failure.

### rhocrit95 ()

```double
rhocrit95 (`int n`);```

Computes the two-sided 5 percent critical value of the sample correlation coefficient for a sample of size `n` . This is based on the inverse of the function which maps from the correlation coefficient, r, to a student t statistic, namely

t = r / sqrt[(1—r^2) / (n-2)]

The inverse is r = sqrt(t^2 / (t^2 + n - 2)).

#### Parameters

 n sample size.

#### Returns

the critical value, or NADBL on failure.

### cephes_gamma ()

```double
cephes_gamma (`double x`);```

### cephes_lgamma ()

```double
cephes_lgamma (`double x`);```

### gretl_get_pvalue ()

```double
gretl_get_pvalue (`int dist`,
`const double *parm`,
`double x`);```

#### Parameters

 dist distribution code. parm array holding from zero to two parameter values, depending on the distribution. x abscissa value.

#### Returns

the integral of the PDF specified by `dist` and `parm` from `x` to infinity, or NADBL on error.

### gretl_get_pdf ()

```double
gretl_get_pdf (`int dist`,
`const double *parm`,
`double x`);```

Evaluates the PDF for the distribution specified by `dist` and `parm` at `x` .

#### Parameters

 dist distribution code. parm array holding from zero to two parameter values, depending on the distribution. x abscissa value.

#### Returns

the PDF value, or NADBL on error.

### gretl_fill_pdf_array ()

```int
gretl_fill_pdf_array (`int dist`,
`const double *parm`,
`double *x`,
`int n`);```

On input, `x` contains an array of abscissae at which the PDF specified by `dist` and `parm` should be evaluated. On output it contains the corresponding PDF values.

#### Parameters

 dist distribution code. parm array holding from zero to two parameter values, depending on the distribution. x see below. n number of elements in `x` .

#### Returns

0 on success, non-zero on error.

### gretl_get_cdf ()

```double
gretl_get_cdf (`int dist`,
`const double *parm`,
`double x`);```

Evaluates the CDF for the distribution specified by `dist` and `parm` applicable at `x` .

#### Parameters

 dist distribution code. parm array holding from zero to two parameter values, depending on the distribution. x abscissa value.

#### Returns

the CDF value, or NADBL on error.

### gretl_get_cdf_inverse ()

```double
gretl_get_cdf_inverse (`int dist`,
`const double *parm`,
`double a`);```

#### Parameters

 dist distribution code. parm array holding from zero to two parameter values, depending on the distribution. a probability value.

#### Returns

the argument, y, for which the area under the PDF specified by `dist` and `parm` , integrated from its minimum to y, is equal to `a` , or NADBL on failure.

### gretl_get_critval ()

```double
gretl_get_critval (`int dist`,
`const double *parm`,
`double a`);```

#### Parameters

 dist distribution code. parm array holding from zero to two parameter values, depending on the distribution. a right-tail probability.

#### Returns

the abcsissa value x for the distribution specified by `dist` and `parm` , such that P(X >= x) = `a` , or NADBL on failure.

### gretl_fill_random_series ()

```int
gretl_fill_random_series (`double *x`,
`int dist`,
`const double *parm`,
`const double *vecp1`,
`const double *vecp2`,
`const DATASET *dset`);```

Fills `x` with random values conforming to the distribution given by `dist` , which may require specification of either one or two parameters. These parameters are either given as (scalar) elements of `parm` , or they may vary by observation, in which case they are given as the elements of `vecp1` or `vecp2` .

#### Parameters

 x series to fill (must be of length dset->n). dist distribution code. parm array holding either one or two scalar parameter values, depending on the distribution. vecp1 series containing values for first param, or `NULL`. vecp2 series containing values for second param, or `NULL`. dset dataset information.

#### Returns

0 on success, non-zero code on error.

### gretl_get_random_matrix ()

```gretl_matrix *
gretl_get_random_matrix (`int dist`,
`const double *parm`,
`int rows`,
`int cols`,
`int *err`);```

### gretl_get_random_scalar ()

```double
gretl_get_random_scalar (`int dist`,
`const double *parm`,
`int *err`);```

### batch_pvalue ()

```int
batch_pvalue (`const char *str`,
`DATASET *dset`,
`PRN *prn`);```

Calculates and prints the probability that a random variable distributed as specified in the command line `str` exceeds the value indicated in `str` .

#### Parameters

 str the command line, which should be of one of the following forms: pvalue z x (Normal distribution); pvalue t df x (t-distribution); pvalue X df x (Chi-square); pvalue F dfn dfd x (F-distribution); or pvalue G mean variance x (Gamma distribution). pvalue B prob n x (Binomial distribution). pvalue P mean k (Poisson distribution). pvalue W shape scale x (Weibull distribution). dset dataset struct. prn gretl printing struct.

#### Returns

0 on success, non-zero code on error.

### print_pvalue ()

```void
print_pvalue (`int dist`,
`const double *parm`,
`double x`,
`double pv`,
`PRN *prn`);```

Prints the p-value information in a consistent manner.

#### Parameters

 dist distribution code. parm array holding 1 or 2 parameter values. x the value in the distribution. pv the p-value. prn gretl printer.

### print_critval ()

```void
print_critval (`int dist`,
`const double *parm`,
`double a`,
`double c`,
`PRN *prn`);```

Prints the critical value information in a consistent manner.

#### Parameters

 dist distribution code. parm array holding 0 to 2 parameter values. a alpha. c the critical value. prn gretl printer.

### gretl_get_DW ()

```gretl_matrix *
gretl_get_DW (`int n`,
`int k`,
`int *err`);```

Consults a table of Durbin-Watson critical values and returns the results in a gretl_matrix.

#### Parameters

 n number of observations k number of regressors excluding the constant. err location to receive error code.

#### Returns

on success, a 4-vector containing the lower and upper Durbin-Watson values, dl and du, along with the values actually used for `n` and `k` (which may differ from those given on input if the exact values are not found in the table and have to be approximated). On error, returns `NULL`.

### dist_code_from_string ()

```int
dist_code_from_string (`const char *s`);```

## Types and Values

### enum DistCode

#### Members

 D_NONE D_UNIFORM D_UDISCRT D_NORMAL D_STUDENT D_CHISQ D_SNEDECOR D_BINOMIAL D_POISSON D_WEIBULL D_GAMMA D_GED D_BETA D_DW D_BINORM D_JOHANSEN D_BETABIN D_NC_CHISQ D_NC_F D_NC_T