ssFit#

Purpose#

Estimates parameters of a state-space model using Kalman filtering and maximum likelihood estimation.

Format#

sOut = ssFit(&updateSSModel, par, y[, ssCtl])#
Parameters:

  • &updateSSModel (Function pointer) – pointer to a procedure that specifies how to update the state space system matrices. See remarks for further information.

  • par (Vector) – Contains starting values for parameters to be estimated. This parameter vector is used in the updateSSModel procedure to update the state space system matrices.

  • y (Vector) – Observed data.

  • ssCtl (Struct) –

    Optional input, instance of an ssControl structure. Normally an instance is initialized by calling ssControlCreate() and members of this instance can be set to other values by the user. For an instance named ssCtl, the members are:

    ssCtl.param_names

    String array, parameter names.

    ssCtl.stationary_vars

    Vector, specifies the index of the variables which should be constrained stationary.

    ssCtl.positive_vars

    Vector, specifies the index of the variables which should be constrained positive.

    ssCtl.ctl

    Instance of a cmlmtControl structure, used for fine-tuning maximum likelihood estimation. Further information provided in the cmlmt documentation.

    ssCtl.ssm

    Instance of a ssModel structure, contains the state space system matrices used in the kalmanFilter(). Contains the following members:

    ssm.Z

    k_endog x k_states, transition matrix.

    ssm.d

    k_endog x 1, observation intercept.

    ssm.H

    k_endog x k_endog, observation disturbance covariance.

    ssm.T

    k_states x k_states, design matrix.

    ssm.c

    k_states x k_states, state intercept.

    ssm.R

    k_states x k_posdef, selection matrix.

    ssm.Q

    k_states x k_posdef, state disturbance covariance.

    ssm.a_0

    k_states x 1, initial prior state mean.

    ssm.p_0

    k_states x k_states, initial prior state covariance.

Returns:

sOut (Struct) –

an instance of an ssOut structure. For an instance named sOut, the members are:

sOut.final_params

String array, final parameter estimates.

sOut.resid

Vector, residuals.

sOut.fitted

Vector, the fitted y values based on final parameter estimates.

sOut.df_model

Vector, degrees of freedom of the model.

sOut.df_resid

Vector, degrees of freedom of the residuals.

sOut.numObs

Vector, number of observations.

sOut.mleResults

Instance of a cmlmtResults structure. Further information provided in the cmlmt documentation.

sOut.kfResults

Instance of a kalmanOut structure, contains the results from the kalmanFilter().

kfResults.filtered_state

Matrix, k_endog x numObs, filtered states.

kfResults.filtered_state_cov

Array, numObs x k_endog x k_endog, filtered state covariances.

kfResults.predicted_state

Matrix, k_endog x (numObs+1), predicted states.

kfResults.predicted_state_cov

Array, numObs x k_endog x k_endog, predicted state covariances.

kfResults.forecast

Matrix, k_endog x numObs, forecasts.

kfResults.forecast_error

Matrix, k_endog x numObs, forecast error.

kfResults.forecast_error_cov

Array, numObs x k_endog x k_endog, forecast error covariances.

kfResults.loglikelihood

Matrix, k_endog x (numObs+1), computed loglikelihood.

sOut.ssmFinal

Instance of a ssModel structure, contains the final state space system matrices used in the kalmanFilter(). Contains the following members:

ssmFinal.Z

k_endog x k_states, transition matrix.

ssmFinal.d

k_endog x 1, observation intercept.

ssmFinal.H

k_endog x k_endog, observation disturbance covariance.

ssmFinal.T

k_states x k_states, design matrix.

ssmFinal.c

k_states x k_states, state intercept.

ssmFinal.R

k_states x k_posdef, selection matrix.

ssmFinal.Q

k_states x k_posdef, state disturbance covariance.

ssmFinal.a_0

k_states x 1, initial prior state mean.

ssmFinal.p_0

k_states x k_states, initial prior state covariance.

sOut.aic

Scalar, model Akaike’s information criterion.

sOut.aicc

Scalar, model corrected Akaike’s information criterion.

sOut.bic

Scalar, model Schwarz’ Bayesian information criterion.

sOut.hqic

Scalar, model Hannan–Quinn information criterion.

sOut.ssy

Scalar, sum of squares total (Deviations of y from mean of y).

sOut.sse

Scalar, sum of squared errors.

sOut.mse

Scalar, means squared errors.

sOut.rsquared

Scalar, model r-squared.

sOut.ljung_box

Scalar, Ljung-Box Q-test for autocorrelation.

sOut.ljung_box_pval

Scalar, p-value of the Ljung-Box Q-test for autocorrelation.

sOut.hetero_test

Scalar, tests for the null hypothesis of no heteroskedasticity.

sOut.hetero_test_pval

Scalar, p-value of the test for the null hypothesis of no heteroskedasticity.

sOut.jb_stat

Scalar, the Jarque-Bera goodness-of-fit test on model residuals.

sOut.jb_stat_pval

Scalar, p-value ofthe Jarque-Bera goodness-of-fit test.

sOut.standardized_forecast_errors

Scalar, standardized forecast errors used in all residual diagnostics.

sOut.skew

Scalar, sample skewness of the standardized forecast errors.

sOut.kurtosis

Scalar, sample kurtosis of the standardized forecast errors.

sOut.irf

Scalar, model impulse response functions.

sOut.forecasts

Scalar, forecasts.

Examples#

new;
library cmlmt, tsmt, sslib;

// Load data
fname = getGAUSShome $+ "pkgs/tsmt/examples/enders_sim2.dat";
y = loadd(fname, "ar2");

// Set up parameter vector and start values
param_vec_st = asDF(zeros(3, 1), "param");

param_vec_st[1] = -0.322;
param_vec_st[2] = 0.433;
param_vec_st[3] = 0.0025;

// Declare shape
k_endog = 1;
k_states = 2;
k_posdef = 1;

// Declare control structure
struct ssControl ssCtl;
ssCtl = ssControlCreate(k_states, k_endog);

// Set fixed parameters of model
ssCtl.ssm.Z = { 1 0 };
ssCtl.ssm.R[1, 1] = 1;

// Parameter names
ssCtl.param_names = "phi1"$|"phi2"$|"sigma2";

// Constraint variables
ssCtl.stationary_vars = 1|2;
ssCtl.positive_vars = 3;

// Call ssFit function
struct ssOut sOut;
sOut = ssFit(&updateSSModel, param_vec_st, y, ssCtl);

// Set up procedure for updating SS model
// structure
proc (0) = updateSSModel(struct ssModel *ssmod, param);

  // Set up kalman filter matrices
  ssmod->T =  param[1 2]'|(1~0);
  ssmod->Q[1, 1] = param[3];

endp;

The results printed to screen are

 Return Code:                                                             0
 Log-likelihood:                                                      -38.3
 Number of Cases:                                                       100
 AIC:                                                                 82.59
 AICC:                                                                82.84
 BIC:                                                                 90.41
 HQIC:                                                                81.17
 Covariance Method:                                    ML covariance matrix
 ==========================================================================

 Parameters   Estimates   Std. Err.      T-stat       Prob.    Gradient
 --------------------------------------------------------------------------
       phi1      0.6845      0.0890      7.6913      0.0000      0.0000
       phi2     -0.4639      0.0904     -5.1333      0.0000      0.0000
     sigma2      0.0884      0.0126      6.9972      0.0000      0.0000

Correlation matrix of the parameters
--------------------------------------------------------------------------

     1.0000     -0.4756     -0.0132
    -0.4756      1.0000      0.0278
    -0.0132      0.0278      1.0000

Wald 95% Confidence Limits
--------------------------------------------------------------------------
 Parameters   Estimates Lower Limit Upper Limit    Gradient
--------------------------------------------------------------------------
       phi1      0.6845     -0.6826     -0.3753      0.0000
       phi2     -0.4639      0.2657      0.7817      0.0000
     sigma2      0.0884      0.2552      0.3395      0.0000

Model and residual diagnostics:
==========================================================================

Ljung-Box (Q):                                                       0.024
Prob(Q):                                                             0.877
Heteroskedasticity (H):                                               1.04
Prob(H):                                                             0.908
Jarque-Bera (JB):                                                     6.34
Prob(JB):                                                           0.0421
Skew:                                                                0.021
Kurtosis:                                                             1.76
==========================================================================

Remarks#

The update function is a required user-provided procedure which specifies how the state space system matrices should be updated with the underlying model parameters.

The update function must always take the same inputs:

  • A pointer to a ssModel structure which contains the state space system matrices.

  • A vector of parameters.

The update function should only specify system matrices which contain parameters, it should not specify fixed system matrices.

For example, we might have the following update function specifying how the parameters of a model should be placed in the state space matrices:

proc (0) = updateSSModel(struct ssModel *ssmod, param);

 // Set up kalman filter matrices
 ssmod->T =  param[1 2]'|(1~0);
 ssmod->Q[1, 1] = param[3];

endp;

Source#

ssmain.src

See also

Functions ssControlCreate(), ssIRF(), ssPredict()

On this page
Show Source