gretl_utils

gretl_utils

Functions

#define floateq()
#define floatneq()
#define floatgt()
#define floatlt()
#define ok_int()
void libgretl_init ()
int libgretl_mpi_init ()
int gretl_mpi_initialized ()
void libgretl_session_cleanup ()
void libgretl_cleanup ()
double date_as_double ()
int gretl_isdummy ()
int gretl_iszero ()
int gretl_isconst ()
int gretl_isunits ()
int gretl_isint ()
int gretl_iscount ()
int gretl_isdiscrete ()
int gretl_ispositive ()
int gretl_is_oprobit_ok ()
int true_const ()
char * format_obs ()
int set_obs ()
int gretl_compare_doubles ()
int gretl_inverse_compare_doubles ()
int count_distinct_values ()
int count_distinct_int_values ()
int rearrange_id_array ()
int gretl_compare_ints ()
void printlist ()
double gretl_double_from_string ()
int gretl_int_from_string ()
int positive_int_from_string ()
int varnum_from_string ()
GretlType gretl_type_from_name ()
double * copyvec ()
void doubles_array_free ()
double ** doubles_array_new ()
double ** doubles_array_new0 ()
int doubles_array_adjust_length ()
double ** data_array_from_model ()
int ijton ()
int transcribe_array ()
int gretl_copy_file ()
int gretl_delete_var_by_name ()
int gretl_spawn ()
int gretl_calculate_criteria ()
int ls_criteria ()
int get_last_test_type ()
void record_test_result ()
void record_matrix_test_result ()
void record_LR_test_result ()
double get_last_test_statistic ()
double get_last_pvalue ()
double get_last_lnl ()
gretl_matrix * get_last_test_matrix ()
gretl_matrix * get_last_pvals_matrix ()
double gretl_stopwatch ()
void * gretl_aligned_malloc ()
void gretl_aligned_free ()
int check_for_program ()

Object Hierarchy


Description

Functions

floateq()

#define floateq(x, y)  (fabs((x) - (y)) < DBL_EPSILON)


floatneq()

#define floatneq(x, y) (fabs((x) - (y)) > DBL_EPSILON)


floatgt()

#define floatgt(x, y)  ((x) - (y) > DBL_EPSILON)


floatlt()

#define floatlt(x, y)  ((y) - (x) > DBL_EPSILON)


ok_int()

#define ok_int(x) (x <= (double) INT_MAX && x >= (double) INT_MIN)


libgretl_init ()

void
libgretl_init (void);

In a program that uses libgretl, this function should be called once, before any other libgretl functions are used. See also libgretl_cleanup(), and libgretl_mpi_init().


libgretl_mpi_init ()

int
libgretl_mpi_init (int self,
                   int np,
                   int dcmt);

This function provides an alternative to libgretl_init() which should be used when a libgretl program is to be run in MPI mode.

Parameters

self

the MPI rank of the calling process.

 

np

the number of MPI processes.

 

dcmt

if non-zero, set up per-process RNG using DCMT.

 

Returns


gretl_mpi_initialized ()

int
gretl_mpi_initialized (void);

Returns


libgretl_session_cleanup ()

void
libgretl_session_cleanup (int mode);


libgretl_cleanup ()

void
libgretl_cleanup (void);

In a program that uses libgretl, this function may be called to free various chunks of memory after the program is finished with libgretl. Do not attempt to call any other libgretl functions after invoking this cleanup.

See also libgretl_init().


date_as_double ()

double
date_as_double (int t,
                int pd,
                double sd0);

Parameters

t

observation number (zero-based).

 

pd

data periodicity or frequency.

 

sd0

floating point representation of starting date.

 

Returns

the date corresponding to t , as a double-precision number.


gretl_isdummy ()

int
gretl_isdummy (int t1,
               int t2,
               const double *x);

Check whether series x has only 0 or 1 values over the given sample range (or possibly missing values).

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

0 if the variable is not a 0/1 dummy, otherwise the number of 1s in the series.


gretl_iszero ()

int
gretl_iszero (int t1,
              int t2,
              const double *x);

Check whether series x has only zero values over the given sample range (or possibly missing values).

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

1 if the variable is all zeros, otherwise 0.


gretl_isconst ()

int
gretl_isconst (int t1,
               int t2,
               const double *x);

Check whether series x is constant over the given sample range (aside from any missing values).

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

1 if the variable is constant, otherwise 0.


gretl_isunits ()

int
gretl_isunits (int t1,
               int t2,
               const double *x);

Check whether series x equals 1 over the given sample range (aside from any missing values).

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

1 if so, otherwise 0.


gretl_isint ()

int
gretl_isint (int t1,
             int t2,
             const double *x);

Check whether series x contains only integer values over the given sample range (aside from any missing values).

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

1 if so, otherwise 0.


gretl_iscount ()

int
gretl_iscount (int t1,
               int t2,
               const double *x);

Check whether series x contains nothing but non-negative integer values (some of which are > 1) over the given sample range.

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

1 if so, otherwise 0.


gretl_isdiscrete ()

int
gretl_isdiscrete (int t1,
                  int t2,
                  const double *x);

Checks the variable x over the range t1 to t2 for discreteness. This is a heuristic whose components are (a) whether the values are "fairly round" (multiples of 0.25) or not, and, if test (a) is passed, (b) whether the variable takes on only "few" distinct values.

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

0 if test (a) is not passed or the number of distinct values is > 32; else 1 if the number of distinct values is <= 32; else 2 if the number of distinct values is <= 4. A return of 1 is supposed to indicate that it's "reasonable" to treat x as discrete, while a return of 2 indicates that it's probably ureasonable _not_ to treat x as discrete, for the purpose of drawing up a frequency distribution.


gretl_ispositive ()

int
gretl_ispositive (int t1,
                  int t2,
                  const double *x,
                  int strict);

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

strict

boolean, strict inequality.

 

Returns

1 if all non-missing values in x , over the range t1 to t2 , are positive (if strict==1) or non-negative (if strict==0), otherwise 0.


gretl_is_oprobit_ok ()

int
gretl_is_oprobit_ok (int t1,
                     int t2,
                     const double *x);

Checks the variable x over the range t1 to t2 for its suitability as the dependent variable in an ordered probit analysis. The criterion used is that the variable has only non-negative integer values.

Parameters

t1

starting observation.

 

t2

ending observation.

 

x

data series to examine.

 

Returns

1 if the test succeeds, otherwise 0.


true_const ()

int
true_const (int v,
            const DATASET *dset);

Check whether variable Z[v] equals 1 over the sample range given in dset (aside from any missing values).

Parameters

v

index number of variable to test.

 

dset

dataset struct.

 

Returns

1 if so, otherwise 0.


format_obs ()

char *
format_obs (char *obs,
            int maj,
            int min,
            int pd);

Prints to obs the gretl-type date string representing the observation given by maj , min and pd .

Parameters

obs

target string (should be of length OBSLEN).

 

maj

major period (e.g. year).

 

min

minor period (e.g. quarter, month).

 

pd

data frequency.

 

Returns

obs .


set_obs ()

int
set_obs (const char *line,
         DATASET *dset,
         gretlopt opt);

Set the frequency and initial observation for a dataset, or in the case of a panel dataset, extra group or time information.

Parameters

line

command line.

 

dset

dataset struct.

 

opt

OPT_S for stacked time-series, OPT_C for stacked cross-section, OPT_T for time series, OPT_X for cross section, OPT_P to set panel structure via two variables representing unit and period respectively. For data already set as panel, OPT_G to set panel group names or OPT_I to set panel time-dimension information.

 

Returns

0 on successful completion, non-zero on error.


gretl_compare_doubles ()

int
gretl_compare_doubles (const void *a,
                       const void *b);

Comparison function for use with qsort. Sorts doubles in ascending order.

Parameters

a

pointer to first element to compare.

 

b

pointer to second element to compare.

 

Returns

appropriate value for qsort.


gretl_inverse_compare_doubles ()

int
gretl_inverse_compare_doubles (const void *a,
                               const void *b);

Comparison function for use with qsort. Sorts doubles in descending order.

Parameters

a

pointer to first element to compare.

 

b

pointer to second element to compare.

 

Returns

appropriate value for qsort.


count_distinct_values ()

int
count_distinct_values (const double *x,
                       int n);

Parameters

x

sorted array of doubles.

 

n

number of elements in array.

 

Returns

the number of distinct values in array x , provided that x is already sorted.


count_distinct_int_values ()

int
count_distinct_int_values (const int *x,
                           int n);

Parameters

x

sorted array of ints.

 

n

number of elements in array.

 

Returns

the number of distinct values in array x , provided that x is already sorted.


rearrange_id_array ()

int
rearrange_id_array (double *x,
                    int m,
                    int n);

Rearranges the sorted array x such that the first m elements contain the m distinct values in sorted order.

Parameters

x

sorted array of doubles.

 

m

number of distinct values in array.

 

n

number of elements in array.

 

Returns

0 on success, 1 on error (in case m is greater than n ).


gretl_compare_ints ()

int
gretl_compare_ints (const void *a,
                    const void *b);

Comparison function for use with qsort. Sorts integers in ascending order.

Parameters

a

pointer to first element to compare.

 

b

pointer to second element to compare.

 

Returns

appropriate value for qsort.


printlist ()

void
printlist (const int *list,
           const char *msg);

Prints to stderr the given list of integers along with a message.

Parameters

list

array of integers.

 

msg

message to print along with list (or NULL).

 

gretl_double_from_string ()

double
gretl_double_from_string (const char *s,
                          int *err);

If s is a valid string representation of a double, return that integer, otherwise if s is the name of a scalar variable, return the value of that variable, otherwise set the content of err to a non-zero value.

Parameters

s

string to examine.

 

err

location to receive error code.

 

Returns

double value.


gretl_int_from_string ()

int
gretl_int_from_string (const char *s,
                       int *err);

If s is a valid string representation of an integer, return that integer, otherwise if s is the name of a scalar variable, return the value of that variable, otherwise set the content of err to a non-zero value.

Parameters

s

string to examine.

 

err

location to receive error code.

 

Returns

integer value.


positive_int_from_string ()

int
positive_int_from_string (const char *s);

If s is a valid string representation of a positive integer, return that integer, otherwise return -1.

Parameters

s

string to examine.

 

Returns

integer value.


varnum_from_string ()

int
varnum_from_string (const char *str,
                    DATASET *dset);

Parameters

str

string representation of an integer ID number.

 

dset

dataset information.

 

Returns

integer ID number, or -1 on failure.


gretl_type_from_name ()

GretlType
gretl_type_from_name (const char *s,
                      const DATASET *dset);

Parameters

s

the name to check.

 

dset

dataset information.

 

Returns

non-zero if s is the name of an existing series, matrix, scalar, list, string or bundle, otherwise 0.


copyvec ()

double *
copyvec (const double *src,
         int n);

Parameters

src

array of doubles.

 

n

number of elements to copy.

 

Returns

an allocated copy of the first n elements of array src , or NULL on failure.


doubles_array_free ()

void
doubles_array_free (double **X,
                    int m);

Frees a 2-dimensional array of doubles, first freeing each sub-array.

Parameters

X

2-dimensional array of doubles.

 

m

number of sub-arrays.

 

doubles_array_new ()

double **
doubles_array_new (int m,
                   int n);

Allocates a 2-dimensional array of doubles, that is, m arrays each containing n elements. If n is zero the sub-arrays are just set to NULL.

Parameters

m

number of sub-arrays.

 

n

length of each sub-array.

 

Returns

the allocated array, or NULL on failure.


doubles_array_new0 ()

double **
doubles_array_new0 (int m,
                    int n);

Works just as doubles_array_new(), except that on successful allocation all values in the arrays are set to zero.

Parameters

m

number of sub-arrays.

 

n

length of each sub-array.

 

Returns

the allocated array, or NULL on failure.


doubles_array_adjust_length ()

int
doubles_array_adjust_length (double **X,
                             int m,
                             int new_n);

For each of the m sub-arrays in X , reallocate to a length of new_n .

Parameters

X

original two-dimensional array.

 

m

number of sub-arrays in X .

 

new_n

new length of each sub-array.

 

Returns

0 on success, non-zero on error.


data_array_from_model ()

double **
data_array_from_model (const MODEL *pmod,
                       double **Z,
                       int missv);

Constructs a dataset containing all the variables referenced in pmod . The arrays start at the correct sample offset for pmod , and are contiguous. If missvals equals 0, this is done by creating a set of pointers into the main dataset, but if there are missing values to be handled, the sub-arrays are newly allocated and purged of NAs.

Parameters

pmod

reference model.

 

Z

main data array.

 

missv

should equal 1 if there are missing values to be skipped, else 0.

 

Returns

two-dimensional array, or NULL on failure.


ijton ()

int
ijton (int i,
       int j,
       int nrows);

Given a (row, column) reference into a symmetric 2-dimensional matrix A, finds the index into a 1-dimensional array x composed of the non-redundant (lower) elements of A.

E.g. for the 3 x 3 case with 6 non-redundant elements, 0 to 5,

A(0,0) = x[0] A(0,1) = x[1] A(0,2) = x[2] A(1,0) = x[1] A(1,1) = x[3] A(1,2) = x[4] A(2,0) = x[2] A(2,1) = x[4] A(2,1) = x[5]

Parameters

i

row number (0-based)

 

j

column number (0-based)

 

nrows

number of rows (and columns) in symmetric matrix.

 

Returns

0-based index into flat array.


transcribe_array ()

int
transcribe_array (double *targ,
                  const double *src,
                  const DATASET *dset);

Copy from src to targ , skipping any missing values, over the sample range defined in dset .

Parameters

targ

arrat to which to write.

 

src

array from which to read.

 

dset

data information struct.

 

Returns

the number of valid observations put into targ .


gretl_copy_file ()

int
gretl_copy_file (const char *src,
                 const char *dest);

Returns


gretl_delete_var_by_name ()

int
gretl_delete_var_by_name (const char *s,
                          PRN *prn);

Returns


gretl_spawn ()

int
gretl_spawn (char *cmdline);

Returns


gretl_calculate_criteria ()

int
gretl_calculate_criteria (double ess,
                          int n,
                          int k,
                          double *ll,
                          double *aic,
                          double *bic,
                          double *hqc);

Calculates model selection criteria based on ess , nobs and k , for a model estimated via least squares.

Parameters

ess

error sum of squares.

 

n

number of observations.

 

k

number of parameters estimated.

 

ll

pointer to recieve loglikelihood.

 

aic

pointer to recieve Akaike criterion.

 

bic

pointer to recieve Schwarz Bayesian criterion.

 

hqc

pointer to recieve Hannan-Quinn criterion.

 

Returns

0 on success, non-zero on error.


ls_criteria ()

int
ls_criteria (MODEL *pmod);

Fills out the model selection criteria members of pmod , using gretl_calculate_criteria().

Parameters

pmod

pointer to gretl model structure.

 

Returns

0 on success, non-zero on error.


get_last_test_type ()

int
get_last_test_type (void);

Returns


record_test_result ()

void
record_test_result (double teststat,
                    double pval,
                    char *blurb);


record_matrix_test_result ()

void
record_matrix_test_result (gretl_matrix *tests,
                           gretl_matrix *pvals);


record_LR_test_result ()

void
record_LR_test_result (double teststat,
                       double pval,
                       double lnl,
                       char *blurb);


get_last_test_statistic ()

double
get_last_test_statistic (char *blurb);

Returns


get_last_pvalue ()

double
get_last_pvalue (char *blurb);

Returns


get_last_lnl ()

double
get_last_lnl (char *blurb);

Returns


get_last_test_matrix ()

gretl_matrix *
get_last_test_matrix (int *err);

Returns


get_last_pvals_matrix ()

gretl_matrix *
get_last_pvals_matrix (int *err);

Returns


gretl_stopwatch ()

double
gretl_stopwatch (void);

Returns


gretl_aligned_malloc ()

void *
gretl_aligned_malloc (size_t size,
                      size_t alignment);

Returns


gretl_aligned_free ()

void
gretl_aligned_free (void *mem);


check_for_program ()

int
check_for_program (const char *prog);

Parameters

prog

name of program.

 

Returns

1 if prog is found in the PATH, otherwise 0.

Types and Values