Nonlinear models

Nonlinear models — estimation of nonlinear models

Synopsis

#include <libgretl.h>

typedef             nlspec;
nlspec *            nlspec_new                          (int ci,
                                                         const DATASET *dset);
void                nlspec_destroy                      (nlspec *spec);
int                 nlspec_add_param_with_deriv         (nlspec *spec,
                                                         const char *s);
int                 nlspec_add_param_list               (nlspec *spec,
                                                         int np,
                                                         double *vals,
                                                         char **names);
int                 aux_nlspec_add_param_list           (nlspec *spec,
                                                         int np,
                                                         double *vals,
                                                         char **names);
int                 nlspec_set_regression_function      (nlspec *spec,
                                                         const char *fnstr,
                                                         const DATASET *dset);
void                nlspec_set_t1_t2                    (nlspec *spec,
                                                         int t1,
                                                         int t2);
int                 nl_parse_line                       (int ci,
                                                         const char *line,
                                                         const DATASET *dset,
                                                         PRN *prn);
MODEL               nl_model                            (DATASET *dset,
                                                         gretlopt opt,
                                                         PRN *prn);
MODEL               model_from_nlspec                   (nlspec *spec,
                                                         DATASET *dset,
                                                         gretlopt opt,
                                                         PRN *prn);
int                 nls_boot_calc                       (const MODEL *pmod,
                                                         DATASET *dset,
                                                         int ft1,
                                                         int ft2,
                                                         double *fcerr);
double              get_default_nls_toler               (void);

Description

Provides mechanisms for estimating nonlinear models via Nonlinear Least Squares, Maximum Likelihood, or GMM.

Details

nlspec

typedef struct nlspec_ nlspec;

An opaque structure handled only via accessor functions.


nlspec_new ()

nlspec *            nlspec_new                          (int ci,
                                                         const DATASET *dset);

ci :

NLS, MLE or GMM.

dset :

information on dataset.

Returns :

a pointer to a newly allocated nonlinear model specification, or NULL on failure.

nlspec_destroy ()

void                nlspec_destroy                      (nlspec *spec);

Frees all resources associated with spec, and frees the pointer itself.

spec :

pointer to nls specification.

nlspec_add_param_with_deriv ()

int                 nlspec_add_param_with_deriv         (nlspec *spec,
                                                         const char *s);

Adds an analytical derivative to spec. This pointer must have previously been obtained by a call to nlspec_new(). The required format for dstr is "varname = formula", where varname is the name of the (scalar) variable holding the parameter in question, and formula is an expression, of the sort that is fed to gretl's genr command, giving the derivative of the regression function in spec with respect to the parameter. The variable holding the parameter must be already present in the dataset.

spec :

pointer to nls specification.

s :

string specifying a derivative with respect to a parameter of the regression function.

Returns :

0 on success, non-zero error code on error.

nlspec_add_param_list ()

int                 nlspec_add_param_list               (nlspec *spec,
                                                         int np,
                                                         double *vals,
                                                         char **names);

Adds to spec a list of (scalar) parameters to be estimated. For an example of use see nls_example.c in the gretl extra subdirectory.

spec :

nls specification.

np :

number of parameters.

vals :

array of initial parameter values.

names :

array of parameter names.

Returns :

0 on success, non-zero error code on error.

aux_nlspec_add_param_list ()

int                 aux_nlspec_add_param_list           (nlspec *spec,
                                                         int np,
                                                         double *vals,
                                                         char **names);


nlspec_set_regression_function ()

int                 nlspec_set_regression_function      (nlspec *spec,
                                                         const char *fnstr,
                                                         const DATASET *dset);

Adds the regression function to spec. This pointer must have previously been obtained by a call to nlspec_new(). The required format for fnstr is "varname = formula", where varname is the name of the dependent variable and formula is an expression of the sort that is fed to gretl's genr command. The dependent variable must be already present in the dataset.

spec :

pointer to nls specification.

fnstr :

string specifying nonlinear regression function.

dset :

information on dataset.

Returns :

0 on success, non-zero error code on error.

nlspec_set_t1_t2 ()

void                nlspec_set_t1_t2                    (nlspec *spec,
                                                         int t1,
                                                         int t2);

Sets the sample range for estimation of spec. This pointer must have previously been obtained by a call to nlspec_new().

spec :

pointer to nls specification.

t1 :

starting observation.

t2 :

ending observation.

nl_parse_line ()

int                 nl_parse_line                       (int ci,
                                                         const char *line,
                                                         const DATASET *dset,
                                                         PRN *prn);

This function is used to create the specification of a nonlinear model, to be estimated via nl_model (i.e. via NLS, MLE or GMM). It can be called several times to build up the required information. See the manual entries for nls, mle and gmm for details.

ci :

NLS, MLE or GMM.

line :

string containing information to be added to a nonlinear model specification.

dset :

dataset struct.

prn :

gretl printing struct (for warning messages).

Returns :

0 on success, non-zero error code on failure.

nl_model ()

MODEL               nl_model                            (DATASET *dset,
                                                         gretlopt opt,
                                                         PRN *prn);

Computes estimates of a model via nonlinear least squares, maximum likelihood, or GMM. The model must have been specified previously, via calls to the function nl_parse_line. Those calls determine, among other things, which estimator will be used.

dset :

dataset struct.

opt :

may include OPT_V for verbose output, OPT_R for robust covariance matrix.

prn :

printing struct.

Returns :

a model struct containing the parameter estimates and associated statistics.

model_from_nlspec ()

MODEL               model_from_nlspec                   (nlspec *spec,
                                                         DATASET *dset,
                                                         gretlopt opt,
                                                         PRN *prn);

Computes estimates of the model specified in spec. The spec must first be obtained using nlspec_new(), and initialized using nlspec_set_regression_function(). If analytical derivatives are to be used (which is optional but recommended) these are set using nlspec_add_param_with_deriv().

spec :

nonlinear model specification.

dset :

dataset struct.

opt :

may include OPT_V for verbose output, OPT_A to treat as an auxiliary model, OPT_C to produce coefficient estimates only (don't bother with GNR to produce standard errors).

prn :

printing struct.

Returns :

a model struct containing the parameter estimates and associated statistics.

nls_boot_calc ()

int                 nls_boot_calc                       (const MODEL *pmod,
                                                         DATASET *dset,
                                                         int ft1,
                                                         int ft2,
                                                         double *fcerr);


get_default_nls_toler ()

double              get_default_nls_toler               (void);

Returns :

the default value used in the convergence criterion for estimation of models using nonlinear least squares.