kalman

kalman —

Synopsis

typedef             kalman;
kalman *            kalman_new                          (const gretl_matrix *S,
                                                         const gretl_matrix *P,
                                                         const gretl_matrix *F,
                                                         const gretl_matrix *A,
                                                         const gretl_matrix *H,
                                                         const gretl_matrix *Q,
                                                         const gretl_matrix *R,
                                                         const gretl_matrix *y,
                                                         const gretl_matrix *x,
                                                         gretl_matrix *E,
                                                         int *err);
void                kalman_free                         (kalman *K);
int                 kalman_forecast                     (kalman *K,
                                                         PRN *prn);
double              kalman_get_loglik                   (const kalman *K);
double              user_kalman_get_loglik              (void);
gretl_matrix *      user_kalman_get_matrix              (int idx,
                                                         int *err);
double              user_kalman_get_s2                  (void);
int                 user_kalman_get_time_step           (void);
double              kalman_get_arma_variance            (const kalman *K);
int                 kalman_set_initial_state_vector     (kalman *K,
                                                         const gretl_matrix *S);
int                 kalman_set_initial_MSE_matrix       (kalman *K,
                                                         const gretl_matrix *P);
void                kalman_set_nonshift                 (kalman *K,
                                                         int n);
void                kalman_set_options                  (kalman *K,
                                                         int opts);
int                 kalman_get_options                  (kalman *K);
int                 kalman_parse_line                   (const char *line,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo,
                                                         gretlopt opt);
int                 user_kalman_run                     (const char *E,
                                                         const char *V,
                                                         const char *S,
                                                         const char *P,
                                                         const char *G,
                                                         double **Z,
                                                         const DATAINFO *pdinfo,
                                                         PRN *prn,
                                                         int *errp);
gretl_matrix *      user_kalman_smooth                  (const char *Pname,
                                                         const char *Uname,
                                                         int *err);
gretl_matrix *      user_kalman_simulate                (const gretl_matrix *V,
                                                         const gretl_matrix *W,
                                                         const char *Sname,
                                                         PRN *prn,
                                                         int *err);
void                kalman_cleanup                      (void);
int                 delete_kalman                       (PRN *prn);

Description

Details

kalman

typedef struct kalman_ kalman;

kalman_new ()

kalman *            kalman_new                          (const gretl_matrix *S,
                                                         const gretl_matrix *P,
                                                         const gretl_matrix *F,
                                                         const gretl_matrix *A,
                                                         const gretl_matrix *H,
                                                         const gretl_matrix *Q,
                                                         const gretl_matrix *R,
                                                         const gretl_matrix *y,
                                                         const gretl_matrix *x,
                                                         gretl_matrix *E,
                                                         int *err);

Allocates and initializes a Kalman struct, which can subsequently be used for forecasting with kalman_forecast(). The nomenclature for the various required matrices is that in Hamilton's Time Series Analysis (1994, chapter 13), except that "S" is used in place of Hamilton's \xi for the state vector.

S : r x 1 initial state vector.
P : r x r initial precision matrix.
F : r x r state transition matrix.
A : n x k matrix of coefficients on exogenous variables in the observation equation.
H : n x r matrix of coefficients on the state variables in the observation equation.
Q : r x r contemporaneous covariance matrix for the errors in the state equation.
R : n x n contemporaneous covariance matrix for the errors in the observation equation (or NULL if this is not applicable).
y : T x n matrix of dependent variable(s).
x : T x k matrix of exogenous variable(s). May be NULL if there are no exogenous variables, or if there's only a constant.
E : T x n matrix in which to record forecast errors (or NULL if this is not required).
err : location to receive error code.
Returns : pointer to allocated struct, or NULL on failure, in which case err will receive a non-zero code.

kalman_free ()

void                kalman_free                         (kalman *K);

K :

kalman_forecast ()

int                 kalman_forecast                     (kalman *K,
                                                         PRN *prn);

Generates a series of one-step ahead forecasts for y, based on information entered initially using kalman_new(), and possibly modified using kalman_set_initial_state_vector() and/or kalman_set_initial_MSE_matrix(). The log-likelihood is calculated for the sequence of forecast errors on the assumption of normality: this can be accessed using kalman_get_loglik().

K : pointer to Kalman struct: see kalman_new().
prn : printing apparatus (or NULL).
Returns : 0 on success, non-zero on error.

kalman_get_loglik ()

double              kalman_get_loglik                   (const kalman *K);

Retrieves the log-likelhood calculated via a run of kalman_forecast().

K : pointer to Kalman struct.
Returns : ll value, or NADBL on failure.

user_kalman_get_loglik ()

double              user_kalman_get_loglik              (void);

Retrieves the log-likelhood calculated via the last run of a kalman forecast, if applicable.

Returns : ll value, or NADBL on failure.

user_kalman_get_matrix ()

gretl_matrix *      user_kalman_get_matrix              (int idx,
                                                         int *err);

Retrieves a matrix, specified by idx, from the last run of a kalman forecast, if applicable.

idx : identifier for matrix.
err : location to receive error code.
Returns : allocated matrix, or NULL on failure.

user_kalman_get_s2 ()

double              user_kalman_get_s2                  (void);

Retrieves the scale factor, \hat{\sigma}^2, calculated via the last run of a kalman forecast, if applicable.

Returns : scale value, or NADBL on failure.

user_kalman_get_time_step ()

int                 user_kalman_get_time_step           (void);

Retrieves the time step, t, from the current run of a kalman forecast, if applicable.

Returns : scale value, or NADBL on failure.

kalman_get_arma_variance ()

double              kalman_get_arma_variance            (const kalman *K);

Retrieves the estimated variance for an ARMA model estimated using the Kalman filter.

K : pointer to Kalman struct.
Returns : sigma-squared value, or NADBL on failure.

kalman_set_initial_state_vector ()

int                 kalman_set_initial_state_vector     (kalman *K,
                                                         const gretl_matrix *S);

Resets the initial value of the state vector in a Kalman struct, using the values from S. See also kalman_new().

K : pointer to Kalman struct.
S : matrix of values to set.
Returns : 0 on success, non-zero on error.

kalman_set_initial_MSE_matrix ()

int                 kalman_set_initial_MSE_matrix       (kalman *K,
                                                         const gretl_matrix *P);

Resets the initial value of the MSE matrix in a Kalman struct, using the values from P. See also kalman_new().

K : pointer to Kalman struct.
P : matrix of values to set.
Returns : 0 on success, non-zero on error.

kalman_set_nonshift ()

void                kalman_set_nonshift                 (kalman *K,
                                                         int n);

K :
n :

kalman_set_options ()

void                kalman_set_options                  (kalman *K,
                                                         int opts);

K :
opts :

kalman_get_options ()

int                 kalman_get_options                  (kalman *K);

K :
Returns :

kalman_parse_line ()

int                 kalman_parse_line                   (const char *line,
                                                         const double **Z,
                                                         const DATAINFO *pdinfo,
                                                         gretlopt opt);

Parses line and either (a) starts a filter definition or (b) adds a matrix specification to the filter or (c) completes the filter set-up.

line : "kalman" to start, "end kalman" to end; otherwise this string should contain a matrix specification on the pattern "key value".
Z : data array (may be NULL).
pdinfo : dataset information (may be NULL).
opt : may contain OPT_D for diffuse initialization of the Kalman filter; also may contain OPT_C to specify that the disturbances are correlated across the two equations.
Returns : 0 on successful completion, non-zero error code otherwise.

user_kalman_run ()

int                 user_kalman_run                     (const char *E,
                                                         const char *V,
                                                         const char *S,
                                                         const char *P,
                                                         const char *G,
                                                         double **Z,
                                                         const DATAINFO *pdinfo,
                                                         PRN *prn,
                                                         int *errp);

E :
V :
S :
P :
G :
Z :
pdinfo :
prn :
errp :
Returns :

user_kalman_smooth ()

gretl_matrix *      user_kalman_smooth                  (const char *Pname,
                                                         const char *Uname,
                                                         int *err);

If a user-defined Kalman filter is found, runs a filtering pass followed by a backward, smoothing pass. At present the Uname argument is experimental and a bodge: it will not actually do anything unless Pname is left null.

Pname : name of matrix in which to retrieve the MSE of the smoothed state (or NULL if this is not required).
Uname : name of matrix in which to retrieve the smoothed disturbances (or NULL if this is not required).
err : location to receive error code.
Returns : matrix containing the smoothed estimate of the state, or NULL on error.

user_kalman_simulate ()

gretl_matrix *      user_kalman_simulate                (const gretl_matrix *V,
                                                         const gretl_matrix *W,
                                                         const char *Sname,
                                                         PRN *prn,
                                                         int *err);

If a user-defined Kalman filter is found, use it to construct a simulation based on the artificial disturbances V and (possibly) W. If the disturbances are not correlated across the two equations, then V should contain the disturbances in the state equation and W should contain those in the observation equation (if any). But if the disturbances are correlated, then V should contain the "combined" disturbance vector at each time step, and W should be left NULL.

V : artificial disturbance to state.
W : artificial disturbance to observation.
Sname : name of matrix to retrieve simulated state (or NULL).
prn :
err : location to receive error code.
Returns : matrix containing the simulated values of the observables, or NULL on failure.

kalman_cleanup ()

void                kalman_cleanup                      (void);

delete_kalman ()

int                 delete_kalman                       (PRN *prn);

prn :
Returns :
Generated by GTK-Doc V1.11