gretl_utils

gretl_utils

Synopsis

#define             floateq                             (x,
                                                         y)
#define             floatneq                            (x,
                                                         y)
#define             floatgt                             (x,
                                                         y)
#define             floatlt                             (x,
                                                         y)
#define             ok_int                              (x)
void                libgretl_init                       (void);
void                libgretl_session_cleanup            (int mode);
void                libgretl_cleanup                    (void);
double              date                                (int nt,
                                                         int pd,
                                                         const double sd0);
int                 gretl_isdummy                       (int t1,
                                                         int t2,
                                                         const double *x);
int                 gretl_iszero                        (int t1,
                                                         int t2,
                                                         const double *x);
int                 gretl_isconst                       (int t1,
                                                         int t2,
                                                         const double *x);
int                 gretl_isunits                       (int t1,
                                                         int t2,
                                                         const double *x);
int                 gretl_isint                         (int t1,
                                                         int t2,
                                                         const double *x);
int                 gretl_iscount                       (int t1,
                                                         int t2,
                                                         const double *x);
int                 gretl_isdiscrete                    (int t1,
                                                         int t2,
                                                         const double *x);
int                 gretl_is_oprobit_ok                 (int t1,
                                                         int t2,
                                                         const double *x);
int                 true_const                          (int v,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);
char *              format_obs                          (char *obs,
                                                         int maj,
                                                         int min,
                                                         int pd);
int                 set_obs                             (const char *line,
                                                         double ***pZ,
                                                         DATAINFO *pdinfo,
                                                         gretlopt opt);
int                 gretl_compare_doubles               (const void *a,
                                                         const void *b);
int                 gretl_inverse_compare_doubles       (const void *a,
                                                         const void *b);
int                 count_distinct_values               (const double *x,
                                                         int n);
int                 count_distinct_int_values           (const int *x,
                                                         int n);
int                 rearrange_id_array                  (double *x,
                                                         int m,
                                                         int n);
int                 gretl_compare_ints                  (const void *a,
                                                         const void *b);
void                printlist                           (const int *list,
                                                         const char *msg);
double              gretl_double_from_string            (const char *s,
                                                         int *err);
int                 gretl_int_from_string               (const char *s,
                                                         int *err);
int                 positive_int_from_string            (const char *s);
int                 varnum_from_string                  (const char *str,
                                                         DATAINFO *pdinfo);
GretlType           gretl_type_from_name                (const char *s,
                                                         const DATAINFO *pdinfo);
double *            copyvec                             (const double *src,
                                                         int n);
void                doubles_array_free                  (double **X,
                                                         int m);
double **           doubles_array_new                   (int m,
                                                         int n);
double **           doubles_array_new0                  (int m,
                                                         int n);
int                 doubles_array_adjust_length         (double **X,
                                                         int m,
                                                         int new_n);
double **           data_array_from_model               (const MODEL *pmod,
                                                         double **Z,
                                                         int missv);
int                 ijton                               (int i,
                                                         int j,
                                                         int nrows);
int                 transcribe_array                    (double *targ,
                                                         const double *src,
                                                         const DATAINFO *pdinfo);
int                 ztox                                (int i,
                                                         double *px,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);
double              get_xvalue                          (int i,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);
int                 gretl_copy_file                     (const char *src,
                                                         const char *dest);
int                 gretl_delete_var_by_name            (const char *s,
                                                         PRN *prn);
int                 gretl_spawn                         (char *cmdline);
int                 gretl_calculate_criteria            (double ess,
                                                         int n,
                                                         int k,
                                                         double *ll,
                                                         double *aic,
                                                         double *bic,
                                                         double *hqc);
int                 ls_criteria                         (MODEL *pmod);
int                 get_last_test_type                  (void);
void                record_test_result                  (double teststat,
                                                         double pval,
                                                         char *blurb);
void                record_matrix_test_result           (gretl_matrix *tests,
                                                         gretl_matrix *pvals);
void                record_LR_test_result               (double teststat,
                                                         double pval,
                                                         double lnl,
                                                         char *blurb);
double              get_last_test_statistic             (char *blurb);
double              get_last_pvalue                     (char *blurb);
double              get_last_lnl                        (char *blurb);
gretl_matrix *      get_last_test_matrix                (int *err);
gretl_matrix *      get_last_pvals_matrix               (int *err);
double              gretl_stopwatch                     (void);

Description

Details

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


libgretl_session_cleanup ()

void                libgretl_session_cleanup            (int mode);


libgretl_cleanup ()

void                libgretl_cleanup                    (void);


date ()

double              date                                (int nt,
                                                         int pd,
                                                         const double sd0);

nt :

observation number (zero-based).

pd :

data periodicity or frequency.

sd0 :

floating point representation of starting date.

Returns :

the date corresponding to nt, 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).

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

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

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

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

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.

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.

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

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 double **Z,
                                                         const DATAINFO *pdinfo);

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

v :

index number of variable to test.

Z :

data array.

pdinfo :

dataset information.

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.

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,
                                                         double ***pZ,
                                                         DATAINFO *pdinfo,
                                                         gretlopt opt);

Set the frequency and initial observation for a dataset.

line :

command line.

pZ :

pointer to data array.

pdinfo :

data information 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.

Returns :

0 on successful completion, 1 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.

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.

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

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

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.

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.

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.

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.

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.

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.

s :

string to examine.

Returns :

integer value.

varnum_from_string ()

int                 varnum_from_string                  (const char *str,
                                                         DATAINFO *pdinfo);

str :

string representation of an integer ID number.

pdinfo :

dataset information.

Returns :

integer ID number, or -1 on failure.

gretl_type_from_name ()

GretlType           gretl_type_from_name                (const char *s,
                                                         const DATAINFO *pdinfo);

s :

the name to check.

pdinfo :

dataset information.

Returns :

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

copyvec ()

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

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.

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.

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.

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.

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.

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]

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 DATAINFO *pdinfo);

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

targ :

arrat to which to write.

src :

array from which to read.

pdinfo :

data information struct.

Returns :

the number of valid observations put into targ.

ztox ()

int                 ztox                                (int i,
                                                         double *px,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);


get_xvalue ()

double              get_xvalue                          (int i,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo);


gretl_copy_file ()

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


gretl_delete_var_by_name ()

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


gretl_spawn ()

int                 gretl_spawn                         (char *cmdline);


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.

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

pmod :

pointer to gretl model structure.

Returns :

0 on success, non-zero on error.

get_last_test_type ()

int                 get_last_test_type                  (void);


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


get_last_pvalue ()

double              get_last_pvalue                     (char *blurb);


get_last_lnl ()

double              get_last_lnl                        (char *blurb);


get_last_test_matrix ()

gretl_matrix *      get_last_test_matrix                (int *err);


get_last_pvals_matrix ()

gretl_matrix *      get_last_pvals_matrix               (int *err);


gretl_stopwatch ()

double              gretl_stopwatch                     (void);