| Libgretl Reference Manual |
|---|
gretl_utilsgretl_utils — |
#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 (void); 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_isdiscrete (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 **Z, 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); int gretl_int_from_string (const char *s, const double **Z, const DATAINFO *pdinfo, int *err); int positive_int_from_string (const char *s); int varnum_from_string (const char *str, DATAINFO *pdinfo); int rename_var_by_id (const char *idstr, const char *vname, DATAINFO *pdinfo); int re_estimate (char *model_spec, MODEL *tmpmod, double ***pZ, 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** data_array_from_model (const MODEL *pmod, double **Z, int missv); int ijton (int i, int j, int nrows); 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_spawn (char *cmdline); int gretl_calculate_criteria (double ess, int n, int k, double *ll, double *aic, double *bic, double *hqc); int gretl_print_criteria (double ess, int nobs, int ncoeff, PRN *prn); int ls_criteria (MODEL *pmod); void record_test_result (double teststat, double pval, char *blurb); double get_last_test_statistic (char *blurb); double get_last_pvalue (char *blurb); double gretl_stopwatch (void);
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.
|
int gretl_isdummy (int t1,
int t2,
const double *x);
Check whether variable 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. |
int gretl_iszero (int t1,
int t2,
const double *x);
Check whether variable 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. |
int gretl_isconst (int t1,
int t2,
const double *x);
Check whether variable 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. |
int gretl_isunits (int t1,
int t2,
const double *x);
Check whether variable 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. |
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 > 8; else 1 if the number of distinct values is <= 8; 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.
|
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. |
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.
|
int set_obs (const char *line,
double **Z,
DATAINFO *pdinfo,
gretlopt opt);
Set the frequency and initial observation for a dataset.
line : |
command line. |
Z : |
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. |
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.
|
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.
|
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.
|
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.
|
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).
|
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.
|
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).
|
int gretl_int_from_string (const char *s,
const double **Z,
const DATAINFO *pdinfo,
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. |
Z : |
data array. |
pdinfo : |
data information struct. |
err : |
location to receive error code. |
| Returns : | integer value. |
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. |
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. |
int rename_var_by_id (const char *idstr,
const char *vname,
DATAINFO *pdinfo);
idstr : |
string representation of the ID number of the variable to be renamed. |
vname : |
new name to give the variable. |
pdinfo : |
dataset information. |
| Returns : | 0 on sucess, E_DATA on error.
|
int re_estimate (char *model_spec,
MODEL *tmpmod,
double ***pZ,
DATAINFO *pdinfo);
model_spec : |
estimation command line. |
tmpmod : |
pointer to model to recieve results. |
pZ : |
pointer to data array. |
pdinfo : |
dataset information. |
| Returns : | 0 on success, non-zero on failure. |
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.
|
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. |
double** doubles_array_new (int m,
int n);
Allocates a 2-dimensional array of doubles, that is,
m arrays each containing n elements.
m : |
number of sub-arrays. |
n : |
length of each sub-array. |
| Returns : | the allocated array, or NULL on failure.
|
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.
|
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. |
int ztox (int i,
double *px,
const double **Z,
const DATAINFO *pdinfo);
Pull one series from data matrix and put it into px.
i : |
index number of variable to extract. |
px : |
array into which to write the series. |
Z : |
data matrix. |
pdinfo : |
data information struct. |
| Returns : | the number of valid observations put into px.
|
double get_xvalue (int i,
const double **Z,
const DATAINFO *pdinfo);
i : |
|
Z : |
|
pdinfo : |
|
| Returns : |
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 Schwartz Bayesian criterion. |
hqc : |
pointer to recieve Hannan-Quinn criterion. |
| Returns : | 0 on success, non-zero on error. |
int gretl_print_criteria (double ess,
int nobs,
int ncoeff,
PRN *prn);
Prints the values of the model selection criteria AIC, BIC and HQC for the given parameters.
ess : |
error sum of squares. |
nobs : |
number of observations. |
ncoeff : |
number of parameters estimated. |
prn : |
printing struct. |
| Returns : | 0 on success, non-zero on error. |
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. |
void record_test_result (double teststat,
double pval,
char *blurb);
teststat : |
|
pval : |
|
blurb : |
| << Utilities | strutils >> |