P-values

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

Synopsis

#include <libgretl.h>

enum                DistCode;
double              gamma_function                      (double x);
double              ln_gamma                            (double x);
double              digamma                             (double x);
double              binomial_cdf                        (double p,
                                                         int n,
                                                         int k);
double              binomial_cdf_comp                   (double p,
                                                         int n,
                                                         int k);
double              binomial_pmf                        (double p,
                                                         int n,
                                                         int k);
double              poisson_pmf                         (double lambda,
                                                         int k);
double              x_factorial                         (double x);
double              log_x_factorial                     (double x);
double              normal_pvalue_2                     (double x);
double              normal_pvalue_1                     (double x);
double              student_pvalue_2                    (double df,
                                                         double x);
double              student_pvalue_1                    (double df,
                                                         double x);
double              chisq_cdf                           (double df,
                                                         double x);
double              chisq_cdf_comp                      (double df,
                                                         double x);
double              snedecor_cdf_comp                   (int dfn,
                                                         int dfd,
                                                         double x);
double              snedecor_critval                    (int dfn,
                                                         int dfd,
                                                         double a);
double              normal_cdf                          (double x);
double              normal_cdf_inverse                  (double x);
double              normal_cdf_comp                     (double x);
double              student_cdf_inverse                 (double df,
                                                         double a);
double              normal_pdf                          (double x);
double              normal_critval                      (double a);
double              student_critval                     (double df,
                                                         double a);
double              log_normal_pdf                      (double x);
double              invmills                            (double x);
double              bvnorm_cdf                          (double rho,
                                                         double a,
                                                         double b);
gretl_matrix *      gretl_GHK                           (const gretl_matrix *C,
                                                         const gretl_matrix *A,
                                                         const gretl_matrix *B,
                                                         const gretl_matrix *U,
                                                         int *err);
double              gamma_cdf                           (double s1,
                                                         double s2,
                                                         double x,
                                                         int control);
double              gamma_cdf_comp                      (double s1,
                                                         double s2,
                                                         double x,
                                                         int control);
double              gamma_cdf_inverse                   (double shape,
                                                         double scale,
                                                         double p);
double              GED_pdf                             (double nu,
                                                         double x);
double              GED_cdf                             (double nu,
                                                         double x);
double              GED_cdf_comp                        (double nu,
                                                         double x);
double              GED_cdf_inverse                     (double nu,
                                                         double a);
double              tcrit95                             (int df);
double              rhocrit95                           (int n);
double              cephes_gamma                        (double x);
double              cephes_lgamma                       (double x);
double              gretl_get_pvalue                    (int dist,
                                                         const double *parm,
                                                         double x);
double              gretl_get_pdf                       (int dist,
                                                         const double *parm,
                                                         double x);
int                 gretl_fill_pdf_array                (int dist,
                                                         const double *parm,
                                                         double *x,
                                                         int n);
double              gretl_get_cdf                       (int dist,
                                                         const double *parm,
                                                         double x);
double              gretl_get_cdf_inverse               (int dist,
                                                         const double *parm,
                                                         double a);
double              gretl_get_critval                   (int dist,
                                                         const double *parm,
                                                         double a);
double *            gretl_get_random_series             (int dist,
                                                         const double *parm,
                                                         const double *vecp1,
                                                         const double *vecp2,
                                                         const DATASET *dset,
                                                         int *err);
gretl_matrix *      gretl_get_random_matrix             (int dist,
                                                         const double *parm,
                                                         int rows,
                                                         int cols,
                                                         int *err);
double              gretl_get_random_scalar             (int dist,
                                                         const double *parm,
                                                         int *err);
int                 batch_pvalue                        (const char *str,
                                                         DATASET *dset,
                                                         PRN *prn);
void                print_pvalue                        (int dist,
                                                         const double *parm,
                                                         double x,
                                                         double pv,
                                                         PRN *prn);
void                print_critval                       (int dist,
                                                         const double *parm,
                                                         double a,
                                                         double c,
                                                         PRN *prn);
gretl_matrix *      gretl_get_DW                        (int n,
                                                         int k,
                                                         int *err);
int                 dist_code_from_string               (const char *s);

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).

Details

enum DistCode

typedef enum {
    D_NONE = 0,
    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
} DistCode;

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


gamma_function ()

double              gamma_function                      (double x);

x :

argument.

Returns :

the gamma function of x, or NADBL on failure.

ln_gamma ()

double              ln_gamma                            (double x);

x :

argument.

Returns :

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

digamma ()

double              digamma                             (double x);

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);

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);

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);

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);

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);

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);

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.

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).

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);

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);

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);

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);

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.

snedecor_cdf_comp ()

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

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                    (int dfn,
                                                         int dfd,
                                                         double a);

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.

normal_cdf ()

double              normal_cdf                          (double x);

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);

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);

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_inverse ()

double              student_cdf_inverse                 (double df,
                                                         double a);

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.

normal_pdf ()

double              normal_pdf                          (double x);

x :

double-precision value.

Returns :

the value of the standard normal PDF evaluated at x.

normal_critval ()

double              normal_critval                      (double a);

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);

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);

x :

double-precision value.

Returns :

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

invmills ()

double              invmills                            (double x);

Adapted by putting together code from gsl and TDA (Univ. Bochum). The latter is, in turn, based on A. V. Swan, The Reciprocal of Mills's Ratio, Algorithm AS 17, Journal of the Royal Statistical Society. Series C (Applied Statistics), Vol. 18, No. 1 (1969), 115-116.

x :

double-precision value.

Returns :

the inverse Mills ratio, that is the ratio between the normal density function and the complement of the distribution function, both evaluated at x.

bvnorm_cdf ()

double              bvnorm_cdf                          (double rho,
                                                         double a,
                                                         double b);

rho :

correlation coefficient.

a :

abscissa value, first Gaussian r.v.

b :

abscissa value, second Gaussian r.v.

Returns :

for (x, y) a bivariate standard Normal rv with correlation coefficient rho, the joint probability that (x < a) and (y < b), or NADBL on failure.

gretl_GHK ()

gretl_matrix *      gretl_GHK                           (const gretl_matrix *C,
                                                         const gretl_matrix *A,
                                                         const gretl_matrix *B,
                                                         const gretl_matrix *U,
                                                         int *err);

Computes the GHK (Geweke, Hajivassiliou, Keane) approximation to the multivariate normal distribution function for n observations on m variates, using r draws.

C :

Cholesky decomposition of covariance matrix, lower triangular, m x m.

A :

Lower bounds, n x m; in case a lower bound is minus infinity this should be represented as -1.0E10.

B :

Upper bounds, n x m; in case an upper bound is plus infinity this should be represented as +1.0E10.

U :

Uniform random matrix, m x r.

Returns :

an n x 1 vector of probabilities.

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.

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.

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);

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);

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.

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.

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);

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);

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)).

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);

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.

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.

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.

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);

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);

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_get_random_series ()

double *            gretl_get_random_series             (int dist,
                                                         const double *parm,
                                                         const double *vecp1,
                                                         const double *vecp2,
                                                         const DATASET *dset,
                                                         int *err);

Produces a random series 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 serp1 or serp2.

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.

err :

location to receive error code.

Returns :

the array of pseudo-random values, or NULL 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.

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.

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.

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.

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);