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 snedecor_cdf_comp ()
double snedecor_critval ()
double normal_cdf ()
double normal_cdf_inverse ()
double normal_cdf_comp ()
double student_cdf_inverse ()
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

Object Hierarchy


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.


snedecor_cdf_comp ()

double
snedecor_cdf_comp (int dfn,
                   int 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 (int dfn,
                  int 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.


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


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

Returns


cephes_lgamma ()

double
cephes_lgamma (double x);

Returns


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

Returns


gretl_get_random_scalar ()

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

Returns


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

Returns

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