P-values

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

Synopsis

#include <libgretl.h>

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                           (int df,
                                                         double x);
double              chisq_cdf_comp                      (int 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);
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                    (char st,
                                                         const double *parm,
                                                         double x);
double              gretl_get_pdf                       (char st,
                                                         const double *parm,
                                                         double x);
int                 gretl_fill_pdf_array                (char st,
                                                         const double *parm,
                                                         double *x,
                                                         int n);
double              gretl_get_cdf                       (char st,
                                                         const double *parm,
                                                         double x);
double              gretl_get_cdf_inverse               (char st,
                                                         const double *parm,
                                                         double a);
double              gretl_get_critval                   (char st,
                                                         const double *parm,
                                                         double a);
double *            gretl_get_random_series             (char st,
                                                         const double *parm,
                                                         const double *serp1,
                                                         const double *serp2,
                                                         const DATAINFO *pdinfo,
                                                         int *err);
int                 batch_pvalue                        (const char *str,
                                                         double ***pZ,
                                                         DATAINFO *pdinfo,
                                                         PRN *prn);
void                print_pvalue                        (char st,
                                                         const double *parm,
                                                         double x,
                                                         double pv,
                                                         PRN *prn);
void                print_critval                       (char st,
                                                         const double *parm,
                                                         double a,
                                                         double c,
                                                         PRN *prn);
gretl_matrix *      gretl_get_DW                        (int n,
                                                         int k,
                                                         int *err);

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

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

Ripped and adapted from Gnumeric, with a bug corrected for the case (a * b < 0) && (rho < 0).

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.

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 calculated probability, or NADBL on failure.

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                    (char st,
                                                         const double *parm,
                                                         double x);

st :

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 st and parm from x to infinity, or NADBL on error.

gretl_get_pdf ()

double              gretl_get_pdf                       (char st,
                                                         const double *parm,
                                                         double x);

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

st :

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                (char st,
                                                         const double *parm,
                                                         double *x,
                                                         int n);

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

st :

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                       (char st,
                                                         const double *parm,
                                                         double x);

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

st :

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               (char st,
                                                         const double *parm,
                                                         double a);

st :

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 st and parm, integrated from its minimum to y, is equal to a, or NADBL on failure.

gretl_get_critval ()

double              gretl_get_critval                   (char st,
                                                         const double *parm,
                                                         double a);

st :

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 st and parm, such that P(X >= x) = a, or NADBL on failure.

gretl_get_random_series ()

double *            gretl_get_random_series             (char st,
                                                         const double *parm,
                                                         const double *serp1,
                                                         const double *serp2,
                                                         const DATAINFO *pdinfo,
                                                         int *err);

Produces a random series conforming to the distribution given by st, 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.

st :

distribution code.

parm :

array holding either one or two scalar parameter values, depending on the distribution.

serp1 :

series containing values for first param, or NULL.

serp2 :

series containing values for second param, or NULL.

pdinfo :

dataset information.

err :

location to receive error code.

Returns :

the array of pseudo-random values, or NULL on error.

batch_pvalue ()

int                 batch_pvalue                        (const char *str,
                                                         double ***pZ,
                                                         DATAINFO *pdinfo,
                                                         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).

pZ :

pointer to the data array.

pdinfo :

data information struct.

prn :

gretl printing struct.

Returns :

0 on success, non-zero code on error.

print_pvalue ()

void                print_pvalue                        (char st,
                                                         const double *parm,
                                                         double x,
                                                         double pv,
                                                         PRN *prn);

Prints the p-value information in a consistent manner.

st :

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                       (char st,
                                                         const double *parm,
                                                         double a,
                                                         double c,
                                                         PRN *prn);

Prints the critical value information in a consistent manner.

st :

distribution code.

parm :

array holding 1 or 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.