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
updateSSModelprocedure to update the state space system matrices.y (Vector) – Observed data.
ssCtl (Struct) –
Optional input, instance of an
ssControlstructure. Normally an instance is initialized by callingssControlCreate()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
cmlmtControlstructure, used for fine-tuning maximum likelihood estimation. Further information provided in thecmlmtdocumentation.ssCtl.ssm
Instance of a
ssModelstructure, contains the state space system matrices used in thekalmanFilter(). 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
ssOutstructure. 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
cmlmtResultsstructure. Further information provided in thecmlmtdocumentation.sOut.kfResults
Instance of a
kalmanOutstructure, contains the results from thekalmanFilter().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
ssModelstructure, contains the final state space system matrices used in thekalmanFilter(). 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
ssModelstructure 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()