Model structure

Model structure — handling of the MODEL struct

Functions

#define MODEL_COMMAND()
#define AR_MODEL()
#define SIMPLE_AR_MODEL()
#define ML_ESTIMATOR()
#define LIMDEP()
#define COUNT_MODEL()
#define LSQ_MODEL()
#define ASYMPTOTIC_MODEL()
#define NONLIST_MODEL()
#define is_model_ref_cmd()
#define RQ_SPECIAL_MODEL()
#define POOLED_MODEL()
MODEL * gretl_model_new ()
void gretl_model_init ()
int gretl_model_allocate_storage ()
MODEL ** gretl_model_array_new ()
MODEL * allocate_working_model ()
void gretl_model_array_destroy ()
void destroy_working_model ()
void gretl_model_smpl_init ()
void impose_model_smpl ()
void gretl_model_set_auxiliary ()
void clear_model ()
void gretl_model_free ()
void clear_model_xpx ()
void gretl_model_free_on_exit ()
void display_model_data_items ()
int gretl_model_set_data_with_destructor ()
int gretl_model_set_data ()
int gretl_model_set_matrix_as_data ()
int gretl_model_set_list_as_data ()
int gretl_model_set_string_as_data ()
int gretl_model_destroy_data_item ()
int gretl_model_detach_data_item ()
int gretl_model_set_int ()
int gretl_model_set_double ()
int gretl_model_set_full_vcv_info ()
int gretl_model_set_vcv_info ()
int gretl_model_get_vcv_type ()
int gretl_model_get_cluster_var ()
void * gretl_model_get_data ()
void * gretl_model_get_data_full ()
int gretl_model_get_int ()
double gretl_model_get_double ()
int * gretl_model_get_list ()
char * gretl_model_get_param_name ()
int gretl_model_get_param_number ()
void free_coeff_intervals ()
CoeffIntervals * gretl_model_get_coeff_intervals ()
int reset_coeff_intervals ()
int gretl_model_get_depvar ()
const char * gretl_model_get_depvar_name ()
int * gretl_model_get_x_list ()
int * gretl_model_get_y_list ()
int * gretl_model_get_secondary_list ()
int arma_model_nonseasonal_AR_order ()
int arma_model_nonseasonal_MA_order ()
int arma_model_max_AR_lag ()
int arma_model_max_MA_lag ()
int arma_model_integrated_AR_MA_coeffs ()
int regarma_model_AR_coeffs ()
const double * arma_model_get_x_coeffs ()
int arma_model_get_n_arma_coeffs ()
int regarima_model_get_AR_coeffs ()
int * arima_delta_coeffs ()
int gretl_model_set_coeff_separator ()
int gretl_model_get_coeff_separator ()
int gretl_model_new_vcv ()
int gretl_model_write_vcv ()
int gretl_model_add_QML_vcv ()
int gretl_model_add_hessian_vcv ()
int gretl_model_add_OPG_vcv ()
VMatrix * gretl_model_get_vcv ()
double gretl_model_get_vcv_element ()
int gretl_model_write_coeffs ()
int gretl_model_add_arinfo ()
MODEL * gretl_model_copy ()
void swap_models ()
int command_ok_for_model ()
int model_test_ok ()
int gretl_is_simple_OLS ()
int gretl_is_arima_model ()
int get_first_model_stat ()
int get_next_model_stat ()
int get_model_count ()
void set_model_count ()
int model_count_plus ()
void model_count_minus ()
void set_model_id ()
ModelTest * model_test_new ()
void model_test_free ()
int maybe_add_test_to_model ()
void model_test_set_teststat ()
void model_test_set_order ()
void model_test_set_dfn ()
void model_test_set_dfd ()
void model_test_set_value ()
void model_test_set_pvalue ()
void model_test_set_param ()
void model_test_set_opt ()
void model_test_set_allocated_param ()
void model_test_set_crit_and_alpha ()
void gretl_model_test_print ()
void gretl_model_print_last_test ()
void gretl_model_test_print_direct ()
void gretl_model_destroy_tests ()
void model_list_to_string ()
int highest_numbered_var_in_model ()
int mle_criteria ()
double coeff_pval ()
int exact_fit_check ()
void maybe_suppress_time_dummies ()
int gretl_model_allocate_param_names ()
int gretl_model_set_param_name ()
int gretl_model_add_arma_varnames ()
int gretl_model_add_panel_varnames ()
void gretl_model_add_allocated_varnames ()
int gretl_model_add_y_median ()
int gretl_model_add_normality_test ()
int gretl_model_get_normality_test ()
char * gretl_model_get_fitted_formula ()
void gretl_model_set_name ()
const char * gretl_model_get_name ()
double gretl_model_get_scalar ()
int gretl_model_get_series ()
gretl_matrix * gretl_model_get_matrix ()
double gretl_model_get_data_element ()
int gretl_model_serialize ()
int attach_model_tests_from_xml ()
MODEL * gretl_model_from_XML ()

Types and Values

Object Hierarchy


Includes

#include <libgretl.h>

Description

Provides underlying functionality for gretl's MODEL datatype.

Functions

MODEL_COMMAND()

#define             MODEL_COMMAND(c)


AR_MODEL()

#define             AR_MODEL(c)


SIMPLE_AR_MODEL()

#define SIMPLE_AR_MODEL(c) (c == AR || c == AR1)


ML_ESTIMATOR()

#define             ML_ESTIMATOR(c)


LIMDEP()

#define             LIMDEP(c)


COUNT_MODEL()

#define COUNT_MODEL(c) (c == POISSON || c == NEGBIN)


LSQ_MODEL()

#define             LSQ_MODEL(c)


ASYMPTOTIC_MODEL()

#define             ASYMPTOTIC_MODEL(c)


NONLIST_MODEL()

#define NONLIST_MODEL(c) (c == NLS || c == MLE || c == GMM)


is_model_ref_cmd()

#define             is_model_ref_cmd(c)


RQ_SPECIAL_MODEL()

#define             RQ_SPECIAL_MODEL(m)


POOLED_MODEL()

#define             POOLED_MODEL(m)


gretl_model_new ()

MODEL *
gretl_model_new (void);

Allocates memory for a gretl MODEL struct and initializes the struct, using gretl_model_init().

Returns

pointer to model (or NULL if allocation fails).


gretl_model_init ()

void
gretl_model_init (MODEL *pmod,
                  const DATASET *dset);

Initializes a gretl MODEL, including setting its pointer members to NULL. This initialization should be done if the caller has declared a MODEL struct directly, rather than obtaining a pointer to MODEL using gretl_model_new() (in which case the initialization is done automatically).

Parameters

pmod

pointer to model.

 

dset

pointer to dataset.

 

gretl_model_allocate_storage ()

int
gretl_model_allocate_storage (MODEL *pmod);

Allocates space for coefficients and standard errors, residuals and fitted values in pmod . The sizes of the arrays are based on the ncoeff and full_n members of pmod , which must be set first. The residuals and fitted values are initialized to gretl's missing value.

Parameters

pmod

pointer to model.

 

Returns

0 on success, E_ALLOC on error.


gretl_model_array_new ()

MODEL **
gretl_model_array_new (int n);

Allocates memory for an array of n gretl MODEL structs and initializes each model using gretl_model_init().

Parameters

n

number of models in array.

 

Returns

pointer to models array (or NULL if allocation fails).


allocate_working_model ()

MODEL *
allocate_working_model (void);

Allocates memory for gretl MODEL struct and initializes it. The model is "protected" against deletion.

Returns

pointer to model (or NULL if allocation fails).


gretl_model_array_destroy ()

void
gretl_model_array_destroy (MODEL **models,
                           int n);

Frees all resources associated with an array of models, which should have been obtained via gretl_model_array_new().

Parameters

models

array of gretl models.

 

n

number of models in array.

 

destroy_working_model ()

void
destroy_working_model (MODEL *models);


gretl_model_smpl_init ()

void
gretl_model_smpl_init (MODEL *pmod,
                       const DATASET *dset);

Records the start and end of the current sample range in the model pmod , which may be necessary for future reference if a hypothesis test is to be performed. Note that this sample range may not be the same as the data range over which the model is actually estimated (for example, in the case of autoregressive models where observations have to be dropped to allow for lags).

Parameters

pmod

pointer to model.

 

dset

dataset information.

 

impose_model_smpl ()

void
impose_model_smpl (const MODEL *pmod,
                   DATASET *dset);

Sets on dset the sample range (starting and ending observations) that was in effect when pmod was estimated. This is not always the same as the data range over which pmod was actually estimated (e.g. in case of autoregressive models, where observations are dropped to allow for lags).

Parameters

pmod

pointer to model.

 

dset

dataset information.

 

gretl_model_set_auxiliary ()

void
gretl_model_set_auxiliary (MODEL *pmod,
                           ModelAuxCode aux);

Sets an auxiliary code on pmod , which may be relevant for how the model is printed.

Parameters

pmod

pointer to model.

 

aux

code indicating a model's function in an auxiliary role (typically, in relation to a hypothesis test on another model).

 

clear_model ()

void
clear_model (MODEL *pmod);

Clears a gretl MODEL, freeing all allocated storage and setting pointer members to NULL. Also frees any data pointers attached via gretl_model_set_data(). The model pointer itself is not freed, so this function may be called on a MODEL which has been declared directly by the caller; in that case the caller should pass the address of the MODEL in question.

Parameters

pmod

pointer to model.

 

gretl_model_free ()

void
gretl_model_free (MODEL *pmod);

Free allocated content of pmod then the pointer itself.

Parameters

pmod

pointer to MODEL.

 

clear_model_xpx ()

void
clear_model_xpx (MODEL *pmod);


gretl_model_free_on_exit ()

void
gretl_model_free_on_exit (MODEL *pmod);

Free allocated content of pmod then the pointer itself, without regard to the model's reference count.

Parameters

pmod

pointer to MODEL.

 

display_model_data_items ()

void
display_model_data_items (const MODEL *pmod);


gretl_model_set_data_with_destructor ()

int
gretl_model_set_data_with_destructor (MODEL *pmod,
                                      const char *key,
                                      void *ptr,
                                      GretlType type,
                                      size_t size,
                                      void (*destructor) (void *));

Attaches data to pmod : the data can be retrieved later using gretl_model_get_data(). Note that the data are not "physically" copied to the model; simply, ptr is recorded on the model. This means that the data referenced by the pointer now in effect belong to pmod . When pmod is cleared with clear_model(), destructor will be invoked with ptr as its single argument. If a simple "free" is OK for freeing the data, you can use gretl_model_set_data() instead.

The size is needed in case the model is copied with copy_model(), in which case the target of the copying operation receives a newly allocated copy of the data in question.

Parameters

pmod

pointer to MODEL.

 

key

key string for data, used in retrieval.

 

ptr

data-pointer to be attached to model.

 

type

type of data to set.

 

size

size of data in bytes.

 

destructor

pointer to function that should be used to free the data-pointer in question.

 

Returns

0 on success, 1 on failure.


gretl_model_set_data ()

int
gretl_model_set_data (MODEL *pmod,
                      const char *key,
                      void *ptr,
                      GretlType type,
                      size_t size);

Attaches data to pmod : the data can be retrieved later using gretl_model_get_data(). Note that the data are not "physically" copied to the model; simply, ptr is recorded on the model. This means that the data referenced by the pointer now in effect belong to pmod . The data pointer will be freed when pmod is cleared with clear_model(). If the data has deep structure that requires special treatment on freeing, use gretl_model_set_data_with_destructor() instead.

The size is needed in case the model is copied with copy_model(), in which case the target of the copying operation receives a newly allocated copy of the data in question.

Parameters

pmod

pointer to MODEL.

 

key

key string for data, used in retrieval.

 

ptr

data-pointer to be attached to model.

 

type

type of the data to set.

 

size

size of data in bytes.

 

Returns

0 on success, 1 on failure.


gretl_model_set_matrix_as_data ()

int
gretl_model_set_matrix_as_data (MODEL *pmod,
                                const char *key,
                                gretl_matrix *m);

Attaches m to pmod as data, recoverable via the key key using gretl_model_get_data().

Parameters

pmod

pointer to MODEL.

 

key

key string, used in retrieval.

 

m

matrix to attach.

 

Returns

0 on success, 1 on failure.


gretl_model_set_list_as_data ()

int
gretl_model_set_list_as_data (MODEL *pmod,
                              const char *key,
                              int *list);

Attaches list to pmod as data, recoverable via the key key using gretl_model_get_data(). Note that the model takes ownership of the supplied list.

Parameters

pmod

pointer to MODEL.

 

key

key string, used in retrieval.

 

list

list to attach.

 

Returns

0 on success, 1 on failure.


gretl_model_set_string_as_data ()

int
gretl_model_set_string_as_data (MODEL *pmod,
                                const char *key,
                                char *str);

Attaches str to pmod as data, recoverable via the key key using gretl_model_get_data().

Parameters

pmod

pointer to MODEL.

 

key

key string, used in retrieval.

 

str

string to attach.

 

Returns

0 on success, 1 on failure.


gretl_model_destroy_data_item ()

int
gretl_model_destroy_data_item (MODEL *pmod,
                               const char *key);

Looks up the data pointer, attached to pmod , that is identified by key , and if a pointer is found, frees it (or applies the destructor function that was set for the item, if any) and removes it from the model's list of data items. If you want to remove the item from the model's list without freeing the underlying data pointer, use gretl_model_detach_data_item().

Parameters

pmod

pointer to model.

 

key

key string.

 

Returns

0 on success, 1 on failure (pointer not found).


gretl_model_detach_data_item ()

int
gretl_model_detach_data_item (MODEL *pmod,
                              const char *key);

Looks up the data item, attached to pmod , that is identified by key , and if an item is found, removes it from the model's list of such items. The data pointer associated with key is not touched. If you want the underlying resources associated with key to be freed, use gretl_model_destroy_data_item().

Parameters

pmod

pointer to model.

 

key

key string.

 

Returns

0 on success, 1 on failure (key not found).


gretl_model_set_int ()

int
gretl_model_set_int (MODEL *pmod,
                     const char *key,
                     int val);

Records an integer value on a model: the value can be retrieved later using gretl_model_get_int(), using the appropriate key .

Parameters

pmod

pointer to MODEL.

 

key

key string, used in retrieval.

 

val

integer value to set.

 

Returns

0 on success, 1 on failure.


gretl_model_set_double ()

int
gretl_model_set_double (MODEL *pmod,
                        const char *key,
                        double val);

Records a floating-point value on pmod : the value can be retrieved later using gretl_model_get_double() with the appropriate key .

Parameters

pmod

pointer to model.

 

key

key string, used in retrieval.

 

val

double-precision value to set.

 

Returns

0 on success, 1 on failure.


gretl_model_set_full_vcv_info ()

int
gretl_model_set_full_vcv_info (MODEL *pmod,
                               int vmaj,
                               int vmin,
                               int order,
                               int flags,
                               double bw);

Returns

0 on success, 1 on failure.


gretl_model_set_vcv_info ()

int
gretl_model_set_vcv_info (MODEL *pmod,
                          int vmaj,
                          int vmin);

Parameters

pmod

pointer to model.

 

Returns

0 on success, 1 on failure.


gretl_model_get_vcv_type ()

int
gretl_model_get_vcv_type (const MODEL *pmod);

Parameters

pmod

pointer to model.

 

Returns

index of variance-covariance matrix type.


gretl_model_get_cluster_var ()

int
gretl_model_get_cluster_var (const MODEL *pmod);

Parameters

pmod

pointer to model.

 

Returns

the dataset index of the clustering variable used for the variance-covariance matrix in pmod , or 0 if there is no such variable.


gretl_model_get_data ()

void *
gretl_model_get_data (const MODEL *pmod,
                      const char *key);

Parameters

pmod

pointer to model.

 

key

key string.

 

Returns

the data pointer identified by key , or NULL on failure.


gretl_model_get_data_full ()

void *
gretl_model_get_data_full (const MODEL *pmod,
                           const char *key,
                           GretlType *type,
                           size_t *sz);

Parameters

pmod

pointer to model.

 

key

key string.

 

type

location to receive data type.

 

sz

location to receive the size of the data.

 

Returns

the data pointer identified by key , or NULL on failure.


gretl_model_get_int ()

int
gretl_model_get_int (const MODEL *pmod,
                     const char *key);

Parameters

pmod

pointer to model.

 

key

key string.

 

Returns

the integer value identified by key , or 0 on failure.


gretl_model_get_double ()

double
gretl_model_get_double (const MODEL *pmod,
                        const char *key);

Parameters

pmod

pointer to model.

 

key

key string.

 

Returns

the double-precision value identified by key , or NADBL on failure.


gretl_model_get_list ()

int *
gretl_model_get_list (const MODEL *pmod,
                      const char *key);

Parameters

pmod

pointer to model.

 

key

key string.

 

Returns

the list of integers identified by key , or NULL on failure.


gretl_model_get_param_name ()

char *
gretl_model_get_param_name (const MODEL *pmod,
                            const DATASET *dset,
                            int i,
                            char *targ);

Writes the appropriate parameter name into targ , which should be at least VNAMELEN bytes long. Usually this is the name of a variable in the dataset, but sometimes it is a special string (e.g. for nonlinear models).

Parameters

pmod

pointer to model.

 

dset

dataset information.

 

i

index number for parameter, zero-based, corresponding to position in the coeff array in pmod .

 

targ

string into which to write param name.

 

Returns

targ .


gretl_model_get_param_number ()

int
gretl_model_get_param_number (const MODEL *pmod,
                              const DATASET *dset,
                              const char *s);

Parameters

pmod

pointer to model.

 

dset

dataset information.

 

s

name of model parameter.

 

Returns

the zero-based index of the coefficient in pmod corresponding to s , or -1 if s is not the name of a parameter.


free_coeff_intervals ()

void
free_coeff_intervals (CoeffIntervals *cf);


gretl_model_get_coeff_intervals ()

CoeffIntervals *
gretl_model_get_coeff_intervals (const MODEL *pmod,
                                 const DATASET *dset);

Save the 95 percent confidence intervals for the parameter estimates in pmod .

Parameters

pmod

pointer to gretl model.

 

dset

dataset information.

 

Returns

pointer to CONFINT struct containing the results.


reset_coeff_intervals ()

int
reset_coeff_intervals (CoeffIntervals *cf,
                       double alpha);

Recomputes the intervals in cf using the given value of alpha .

Parameters

cf

pointer to confidence intervals struct.

 

alpha

nominal non-coverage, as decimal.

 

Returns

0 on success, non-zero if alpha is out of bounds.


gretl_model_get_depvar ()

int
gretl_model_get_depvar (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

the ID number of the dependent variable in pmod .


gretl_model_get_depvar_name ()

const char *
gretl_model_get_depvar_name (const MODEL *pmod,
                             const DATASET *dset);

Parameters

pmod

pointer to gretl model.

 

dset

dataset information.

 

Returns

the name of the dependent variable in pmod .


gretl_model_get_x_list ()

int *
gretl_model_get_x_list (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

an allocated copy of the list of independent variables included in pmod , or NULL on failure.


gretl_model_get_y_list ()

int *
gretl_model_get_y_list (const MODEL *pmod);

Retrieve an allocated copy of the list of dependent variables for pmod : in almost all cases this will have a single element; an exception is biprobit.

Parameters

pmod

model to examine.

 

Returns

allocated list or NULL on error.


gretl_model_get_secondary_list ()

int *
gretl_model_get_secondary_list (const MODEL *pmod);

Retrieve an allocated copy of the secondary list from pmod : e.g. the list of instruments in the case of IVREG, or the selection equation list for HECKIT.

Parameters

pmod

model to examine.

 

Returns

allocated list or NULL on error.


arma_model_nonseasonal_AR_order ()

int
arma_model_nonseasonal_AR_order (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

the non-seasonal autoregressive order of pmod , or 0 if pmod is not an ARMA model.


arma_model_nonseasonal_MA_order ()

int
arma_model_nonseasonal_MA_order (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

the non-seasonal moving-average order of pmod , or 0 if pmod is not an ARMA model.


arma_model_max_AR_lag ()

int
arma_model_max_AR_lag (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

the maximum autoregressive lag in pmod , or 0 if pmod is not an ARMA model. The maximum AR lag takes into account any differencing (seasonal and/or non-seasonal) in an ARIMA model.


arma_model_max_MA_lag ()

int
arma_model_max_MA_lag (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

the maximum moving-average lag in pmod , or 0 if pmod is not an ARMA model.


arma_model_integrated_AR_MA_coeffs ()

int
arma_model_integrated_AR_MA_coeffs (const MODEL *pmod,
                                    double **phi_star,
                                    double **theta_star);

Creates consolidated versions of the AR and MA coefficient vectors from pmod . If pmod includes seasonal ARMA terms, the vectors are suitably expanded to include the interactions between seasonal and non-seasonal terms. If the dependent variable has been differenced, the AR coefficients are integrated to account for the differencing. These are the \Phi^* and \Theta^* as used by Box and Jenkins for forecasting.

The length of these vectors can be determined using gretl_arma_model_get_max_AR_lag() and gretl_arma_model_get_max_MA_lag() respectively.

Parameters

pmod

pointer to gretl model.

 

phi_star

pointer to receive AR coeff vector.

 

theta_star

pointer to receive MA coeff vector.

 

Returns

0 on success, non-zero on error.


regarma_model_AR_coeffs ()

int
regarma_model_AR_coeffs (const MODEL *pmod,
                         double **phi0,
                         int *pp);

Creates a consolidated version of the AR coefficients from pmod . If pmod includes seasonal AR terms the vector is suitably expanded to include the interactions between seasonal and non-seasonal terms, but it is not integrated with respect to any differencing of the dependent variable.

Parameters

pmod

pointer to gretl model.

 

phi0

pointer to receive AR coeff vector.

 

pp

pointer to receive length of phi0 .

 

Returns

0 on success, non-zero on error.


arma_model_get_x_coeffs ()

const double *
arma_model_get_x_coeffs (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

pointer to the array of coefficients on the exogenous regressors in pmod , or NULL if the model is not ARMA or if there are no such regressors.


arma_model_get_n_arma_coeffs ()

int
arma_model_get_n_arma_coeffs (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

the sum of the numbers of AR and MA coefficients in pmod .


regarima_model_get_AR_coeffs ()

int
regarima_model_get_AR_coeffs (const MODEL *pmod,
                              double **phi0,
                              int *pp);

Returns


arima_delta_coeffs ()

int *
arima_delta_coeffs (int d,
                    int D,
                    int s);

Parameters

d

order of non-seasonal differencing (<= 2)

 

D

order of seasonal differencing (<= 2)

 

s

seasonal periodicity

 

Returns

array of d + s * D coefficients of the lag operator in the expansion of (1-L)^d * (1-L^s)^D. These are given in the negative; for example, if d = 1 then c[0] = 1.


gretl_model_set_coeff_separator ()

int
gretl_model_set_coeff_separator (MODEL *pmod,
                                 const char *s,
                                 int pos);

Arranges for the insertion of the given string (or a blank line if s is NULL) at the given position in the array of coefficients, when the model is printed. The extra line is printed before coefficient pos , where pos is interpreted as a zero-based index.

Parameters

pmod

pointer to model.

 

s

informative string (or NULL).

 

pos

position in the array of coefficients.

 

Returns

0 on success, E_ALLOC on failure.


gretl_model_get_coeff_separator ()

int
gretl_model_get_coeff_separator (const MODEL *pmod,
                                 const char **ps,
                                 int *ppos);

Retrieves information that has been set on pmod regarding the insertion of an extra line when printing the coefficients, if any.

Parameters

pmod

pointer to model.

 

ps

location to receive string, if any.

 

ppos

location to receive position, if any.

 

Returns

1 if such information is present, 0 otherwise.


gretl_model_new_vcv ()

int
gretl_model_new_vcv (MODEL *pmod,
                     int *nelem);

Allocates space for a packed coefficient covariance matrix in pmod (if such space is not already allocated). Sets all entries in the array to zero.

Parameters

pmod

pointer to model.

 

nelem

pointer to receive number of elements in the packed array, or NULL;

 

Returns

0 on success, E_ALLOC on error.


gretl_model_write_vcv ()

int
gretl_model_write_vcv (MODEL *pmod,
                       const gretl_matrix *V);

Write the covariance matrix V into the model pmod , using the special packed format that is required by the MODEL struct, and set the standard errors to the square root of the diagonal elements of this matrix.

Parameters

pmod

pointer to model.

 

V

covariance matrix.

 

Returns

0 on success, non-zero code on error.


gretl_model_add_QML_vcv ()

int
gretl_model_add_QML_vcv (MODEL *pmod,
                         int ci,
                         const gretl_matrix *H,
                         const gretl_matrix *G,
                         const DATASET *dset,
                         gretlopt opt);

Write a QML covariance matrix into the model pmod , and set the standard errors to the square root of the diagonal elements of this matrix. The ci argument, specifying the estimator for pmod , is required only if opt includes & OPT_C; otherwise it is ignored.

Parameters

pmod

pointer to model.

 

ci

command index for model.

 

H

inverse of the (negative) Hessian, k x k.

 

G

score matrix, T x k.

 

dset

pointer to dataset (can be NULL if not doing clustering).

 

opt

may include OPT_C for cluster-robust variant.

 

Returns

0 on success, non-zero code on error.


gretl_model_add_hessian_vcv ()

int
gretl_model_add_hessian_vcv (MODEL *pmod,
                             const gretl_matrix *H);

Write H into the model pmod as its covariance matrix, and set the standard errors to the square roots of the diagonal elements of this matrix.

Parameters

pmod

pointer to model.

 

H

inverse of the (negative) Hessian.

 

Returns

0 on success, non-zero code on error.


gretl_model_add_OPG_vcv ()

int
gretl_model_add_OPG_vcv (MODEL *pmod,
                         const gretl_matrix *G);

Compute (G'G)^{-1}, write this into pmod as its covariance matrix, and set the standard errors to the square roots of the diagonal elements of this matrix.

Parameters

pmod

pointer to model.

 

G

T x k gradient matrix.

 

Returns

0 on success, non-zero code on error.


gretl_model_get_vcv ()

VMatrix *
gretl_model_get_vcv (MODEL *pmod,
                     const DATASET *dset);

Supplies the caller with a copy of the variance-covariance matrix for the parameter estimates in pmod , in a format suitable for printing. See also free_vcv(). To get the covariance matrix as a gretl_matrix, see gretl_vcv_matrix_from_model().

Parameters

pmod

pointer to model.

 

dset

dataset information.

 

Returns

VMatrix struct or NULL on error.


gretl_model_get_vcv_element ()

double
gretl_model_get_vcv_element (const MODEL *pmod,
                             int i,
                             int j,
                             int np);

Parameters

pmod

pointer to model.

 

i

row (0-based).

 

j

column(0-based).

 

np

the number of parameters represented in pmod 's covariance matrix.

 

Returns

the (i , j ) element of pmod 's covariance matrix, or NADBL on failure.


gretl_model_write_coeffs ()

int
gretl_model_write_coeffs (MODEL *pmod,
                          double *b,
                          int k);

Write the coefficients b into the model pmod , whose coefficient array is resized appropriately if need be.

Parameters

pmod

pointer to model.

 

b

array of coefficients.

 

k

number of elements in b .

 

Returns

0 on success, non-zero code on error.


gretl_model_add_arinfo ()

int
gretl_model_add_arinfo (MODEL *pmod,
                        int nterms);

Performs initial setup for structure to hold info on autoregressive coefficients.

Parameters

pmod

pointer to model.

 

nterms

number of autoregressive coefficients.

 

Returns

0 on success, 1 on error.


gretl_model_copy ()

MODEL *
gretl_model_copy (const MODEL *pmod);

Does a deep copy of pmod : allocates a new MODEL pointer which has its own allocated copies of all the pointer members of pmod . The only feature of pmod that is not duplicated is the reference count, which is set to zero in the copy.

Parameters

pmod

pointer to MODEL to copy.

 

Returns

the copied model, or NULL on failure.


swap_models ()

void
swap_models (MODEL *targ,
             MODEL *src);

Swaps the content of the two model pointers.

Parameters

targ

pointer to target MODEL.

 

src

pointer to source MODEL.

 

command_ok_for_model ()

int
command_ok_for_model (int test_ci,
                      gretlopt opt,
                      const MODEL *pmod);

Check to see if the model-related command in question is meaningful and acceptable in the context of the estimator associated with pmod . Note, though, that this function may give a "false positive": to be quite sure, we may need to know more about the model (e.g. specific options used). See also model_test_ok().

Parameters

test_ci

index of command to be tested.

 

opt

option for command to be tested.

 

pmod

the gretl model in question.

 

Returns

1 if the command seems OK, otherwise 0.


model_test_ok ()

int
model_test_ok (int ci,
               gretlopt opt,
               const MODEL *pmod,
               const DATASET *dset);

A more rigorous version of command_ok_for_model(). Use this function if the extra information is available.

Parameters

ci

index of a model test command.

 

opt

option associated with test command, if any.

 

pmod

the model to be tested.

 

dset

dataset information.

 

Returns

1 if the test command ci (with possible option opt ) is acceptable in the context of the model pmod , and the dataset described by dset , otherwise 0.


gretl_is_simple_OLS ()

int
gretl_is_simple_OLS (const MODEL *pmod);

Returns


gretl_is_arima_model ()

int
gretl_is_arima_model (const MODEL *pmod);

Returns


get_first_model_stat ()

int
get_first_model_stat (const char **word,
                      const char **desc);

Returns


get_next_model_stat ()

int
get_next_model_stat (const char **word,
                     const char **desc);

Returns


get_model_count ()

int
get_model_count (void);

Returns


set_model_count ()

void
set_model_count (int c);


model_count_plus ()

int
model_count_plus (void);

Returns


model_count_minus ()

void
model_count_minus (void);


set_model_id ()

void
set_model_id (MODEL *pmod);


model_test_new ()

ModelTest *
model_test_new (ModelTestType ttype);

Parameters

ttype

type of test to add.

 

Returns

new ModelTest pointer, or NULL on failure.


model_test_free ()

void
model_test_free (ModelTest *test);

Parameters

test

object to free.

 

maybe_add_test_to_model ()

int
maybe_add_test_to_model (MODEL *pmod,
                         ModelTest *test);

Adds a ModelTest to pmod , if the test in question has not already been performed and recorded. Note that this function takes care of freeing test .

Parameters

pmod

pointer to model.

 

test

model test to be added.

 

Returns

1 if the test was added, otherwise 0.


model_test_set_teststat ()

void
model_test_set_teststat (ModelTest *test,
                         unsigned char ts);


model_test_set_order ()

void
model_test_set_order (ModelTest *test,
                      int order);


model_test_set_dfn ()

void
model_test_set_dfn (ModelTest *test,
                    int df);


model_test_set_dfd ()

void
model_test_set_dfd (ModelTest *test,
                    int df);


model_test_set_value ()

void
model_test_set_value (ModelTest *test,
                      double val);


model_test_set_pvalue ()

void
model_test_set_pvalue (ModelTest *test,
                       double pval);


model_test_set_param ()

void
model_test_set_param (ModelTest *test,
                      const char *s);


model_test_set_opt ()

void
model_test_set_opt (ModelTest *test,
                    gretlopt opt);


model_test_set_allocated_param ()

void
model_test_set_allocated_param (ModelTest *test,
                                char *s);


model_test_set_crit_and_alpha ()

void
model_test_set_crit_and_alpha (ModelTest *test,
                               double crit,
                               double alpha);


gretl_model_test_print ()

void
gretl_model_test_print (const MODEL *pmod,
                        int i,
                        PRN *prn);


gretl_model_print_last_test ()

void
gretl_model_print_last_test (const MODEL *pmod,
                             PRN *prn);


gretl_model_test_print_direct ()

void
gretl_model_test_print_direct (const ModelTest *test,
                               int heading,
                               PRN *prn);


gretl_model_destroy_tests ()

void
gretl_model_destroy_tests (MODEL *pmod);

Clears any hypothesis test structs that have been attached to pmod .

Parameters

pmod

pointer to model.

 

model_list_to_string ()

void
model_list_to_string (int *list,
                      char *buf);


highest_numbered_var_in_model ()

int
highest_numbered_var_in_model (const MODEL *pmod,
                               const DATASET *dset);

Returns


mle_criteria ()

int
mle_criteria (MODEL *pmod,
              int addk);

Returns


coeff_pval ()

double
coeff_pval (int ci,
            double x,
            int df);

Returns


exact_fit_check ()

int
exact_fit_check (const MODEL *pmod,
                 PRN *prn);

Returns


maybe_suppress_time_dummies ()

void
maybe_suppress_time_dummies (MODEL *pmod,
                             int ndum);


gretl_model_allocate_param_names ()

int
gretl_model_allocate_param_names (MODEL *pmod,
                                  int k);

Allocate an array of k strings to hold the names given to the associated coefficients, in a model where these strings are not simply given by the names of the independent variables.

Parameters

pmod

pointer to target model.

 

k

number of strings to allocate.

 

Returns

0 on success, non-zero on error.


gretl_model_set_param_name ()

int
gretl_model_set_param_name (MODEL *pmod,
                            int i,
                            const char *name);

Parameters

pmod

pointer to target model.

 

i

0-based index of value to set.

 

name

string value to set.

 

Returns

0 on success, non-zero on error.


gretl_model_add_arma_varnames ()

int
gretl_model_add_arma_varnames (MODEL *pmod,
                               const DATASET *dset,
                               int yno,
                               int p,
                               int q,
                               const char *pmask,
                               const char *qmask,
                               int P,
                               int Q,
                               int r);

Composes a set of names to be given to the regressors in an ARMA model.

Parameters

pmod

pointer to target model.

 

dset

dataset information.

 

yno

ID number of dependent variable.

 

p

non-seasonal (max) AR order.

 

q

non-seasonal (max) MA order.

 

pmask

for masking out specific AR lags.

 

qmask

for masking out specific MA lags.

 

P

seasonal AR order.

 

Q

seasonal MA order.

 

r

number of exogenous regressors (excluding the constant).

 

Returns

0 on success, non-zero on error.


gretl_model_add_panel_varnames ()

int
gretl_model_add_panel_varnames (MODEL *pmod,
                                const DATASET *dset,
                                const int *ulist);

Composes a set of names to be given to the regressors in an panel model.

Parameters

pmod

pointer to target model.

 

dset

dataset information.

 

ulist

list of index numbers of cross-sectional units included in the model.

 

Returns

0 on success, non-zero on error.


gretl_model_add_allocated_varnames ()

void
gretl_model_add_allocated_varnames (MODEL *pmod,
                                    char **vnames);

Attaches an allocated set of variable names to be used when printing model results, for use in special cases where we can't just reference names from the list of regressors attached to the model. The number of strings must match the number of coefficients, given by the ncoeff member of pmod .

Note that pmod "takes charge" of the array vnames : this will be freed when the model is destroyed.

Parameters

pmod

pointer to target model.

 

vnames

array of names of independent variables.

 

gretl_model_add_y_median ()

int
gretl_model_add_y_median (MODEL *pmod,
                          const double *y);

Calculates the median of y using the valid observations with the model's sample range and attaches the median to the model as data under the key ymedian.

Parameters

pmod

pointer to target model.

 

y

array containing the dependent variable.

 

Returns

0 on success or error code on error.


gretl_model_add_normality_test ()

int
gretl_model_add_normality_test (MODEL *pmod,
                                double X2);

Returns


gretl_model_get_normality_test ()

int
gretl_model_get_normality_test (const MODEL *pmod,
                                PRN *prn);

Returns


gretl_model_get_fitted_formula ()

char *
gretl_model_get_fitted_formula (const MODEL *pmod,
                                int xvar,
                                const DATASET *dset);

If pmod is a simple linear, quadratic or logistic model, and if xvar is in fact the "x" variable from the model, returns a string representing the formula for generating the fitted values as a function of x. This formula may be used in the context of a fitted versus actual plot.

Parameters

pmod

pointer to target model.

 

xvar

ID number of variable that _may_ be "x" in the model.

 

dset

dataset information.

 

Returns

formula for fitted values, or NULL if this is not available.


gretl_model_set_name ()

void
gretl_model_set_name (MODEL *pmod,
                      const char *name);

Sets the name of the given model; this is used in printing the model and in displaying it in the gretl GUI. Note that a model's name must be no more than MAXSAVENAME bytes in length, including the terminating NUL byte; name is truncated if it is too long.

Parameters

pmod

pointer to target model.

 

name

the name to give the model.

 

gretl_model_get_name ()

const char *
gretl_model_get_name (const MODEL *pmod);

Parameters

pmod

pointer to gretl model.

 

Returns

the name that has been set for pmod , if any. Note that the value returned may be NULL.


gretl_model_get_scalar ()

double
gretl_model_get_scalar (const MODEL *pmod,
                        ModelDataIndex idx,
                        DATASET *dset,
                        int *err);

Retrieves a specified scalar statistic from pmod : idx must be less than M_SCALAR_MAX.

Parameters

pmod

pointer to target model.

 

idx

index for the scalar value that is wanted.

 

dset

dataset struct.

 

err

location to receive error code (required).

 

Returns

the requested statistic, or NADBL on failure, in which case err will contain a non-zero error code.


gretl_model_get_series ()

int
gretl_model_get_series (double *x,
                        MODEL *pmod,
                        const DATASET *dset,
                        ModelDataIndex idx);

Retrieves from pmod a copy of a specified series (for example, regression residuals); idx must be greater than M_ELEM_MAX and less than M_SERIES_MAX.

Parameters

x

series to fill (must be of length dset->n).

 

pmod

pointer to target model.

 

dset

dataset information.

 

idx

index for the series that is wanted.

 

Returns

0 on success, non-zero code on error.


gretl_model_get_matrix ()

gretl_matrix *
gretl_model_get_matrix (MODEL *pmod,
                        ModelDataIndex idx,
                        int *err);

Retrieves from pmod a copy of a specified matrix (for example, regression residuals); idx must be greater than M_ELEM_MAX and less than M_MAX.

Parameters

pmod

pointer to target model.

 

idx

index for the matrix that is wanted.

 

err

location to receive error code (required).

 

Returns

the allocated matrix, or NULL on failure, in which case err will contain a non-zero error code.


gretl_model_get_data_element ()

double
gretl_model_get_data_element (MODEL *pmod,
                              int idx,
                              const char *s,
                              const DATASET *dset,
                              int *err);

Returns


gretl_model_serialize ()

int
gretl_model_serialize (const MODEL *pmod,
                       SavedObjectFlags flags,
                       FILE *fp);

Returns


attach_model_tests_from_xml ()

int
attach_model_tests_from_xml (MODEL *pmod,
                             xmlNodePtr node);

Returns


gretl_model_from_XML ()

MODEL *
gretl_model_from_XML (xmlNodePtr node,
                      xmlDocPtr doc,
                      const DATASET *dset,
                      int *err);

Reads info on a gretl model from the given XML node and doc , and reconstitutes the model in memory.

Parameters

node

XML node from which to read.

 

doc

pointer to XML document.

 

dset

dataset information.

 

err

location to receive error code.

 

Returns

allocated model, or NULL on failure.

Types and Values

enum ArmaFlags

Members

ARMA_X12A

   

ARMA_EXACT

   

ARMA_LS

   

ARMA_OLS

   

CoeffIntervals

typedef struct CoeffIntervals_ CoeffIntervals;


enum VCVMajorType

Members

VCV_CLASSICAL

   

VCV_HC

   

VCV_HAC

   

VCV_ML

   

VCV_PANEL

   

VCV_RQ

   

VCV_CLUSTER

   

enum MLVCVType

Members

ML_UNSET

   

ML_HESSIAN

   

ML_IM

   

ML_OP

   

ML_QML

   

ML_BW

   

ML_VCVMAX

   

enum HACKernel

Members

KERNEL_BARTLETT

   

KERNEL_PARZEN

   

KERNEL_QS

   

KERNEL_MAX

   

enum PanelVCVType

Members

PANEL_HAC

   

PANEL_BK

   

enum RQVCVType

Members

RQ_ASY

   

RQ_NID

   

VCVInfo

typedef struct VCVInfo_ VCVInfo;


enum ModelTestType

Members

GRETL_TEST_ADD

   

GRETL_TEST_ARCH

   

GRETL_TEST_AUTOCORR

   

GRETL_TEST_CHOW

   

GRETL_TEST_CUSUM

   

GRETL_TEST_QLR

   

GRETL_TEST_GROUPWISE

   

GRETL_TEST_LOGS

   

GRETL_TEST_NORMAL

   

GRETL_TEST_OMIT

   

GRETL_TEST_RESET

   

GRETL_TEST_SQUARES

   

GRETL_TEST_WHITES

   

GRETL_TEST_SARGAN

   

GRETL_TEST_IV_HAUSMAN

   

GRETL_TEST_PANEL_HAUSMAN

   

GRETL_TEST_PANEL_F

   

GRETL_TEST_PANEL_BP

   

GRETL_TEST_PANEL_TIMEDUM

   

GRETL_TEST_HET_1

   

GRETL_TEST_BP

   

GRETL_TEST_CHOWDUM

   

GRETL_TEST_COMFAC

   

GRETL_TEST_INDEP

   

GRETL_TEST_RE

   

GRETL_TEST_WITHIN_F

   

GRETL_TEST_MAX