Getting Started¶

This page provides an overview of how to implement custom state-space models in GAUSS. It covers everything needed to get working with the GAUSS state-space library including:

Installation and library dependencies.
Data loading.
The basics of state-space models.
Specifying state-space models in GAUSS.
Post-estimation impulse response functions and forecasting.

Installation¶

The GAUSS state-space library can be installed and updated using the GAUSS package manager.

More information about installing the GAUSS package manager is available in our blog, Installing the GAUSS Package Manager.

The state-space library requires:

A working copy of GAUSS 22+.
The Constrained Maximum Likelihood MT library for GAUSS.
The Time Series MT library for GAUSS.

Data Loading¶

The preferred method for loading data is the loadd() procedure. The loadd() function allows you to load data from:

Excel (XLS, XLSX)
CSV or other delimited text files.
Stata (DTA), SAS (SAS7BDAT), SPSS or GAUSS Datasets (DAT).
GAUSS Matrix files (FMT), or HDF5 datasets.

The loadd() function uses two inputs:

The filename.
A formula string .

// Create file name with full path
dataset = getGAUSSHome() $+ "examples/detroit.sas7bdat";

// Load two specific variables from the file
detroit = loadd(dataset, "unemployment + hourly_earn");

The variable name can be used to directly reference individual variables within a loaded dataframe:

y = detroit[., "unemployment"];

For more information on data loading, cleaning and management in GAUSS see our GAUSS Data Management Guide.

State-Space Model Specification¶

The GAUSS sslib library uses the state-space representation of a linear model written as

\[y_t = d + Z\alpha_t + \epsilon_t\]

\[\alpha_{t+1} = c + T\alpha_t + R\eta_t\]

where

\[\epsilon_t \sim N(0, H)\]

\[\eta_t \sim N(0, Q)\]

and

Object	Description	Dimension
\(y_t\)	Observed data.	\(p \times 1\)
\(\alpha_t\)	Unobserved state.	\(m \times 1\)
\(d\)	Observation intercept.	\(m \times 1\)
\(Z\)	Design matrix.	\(p \times m\)
\(H\)	Observation disturbance covariance matrix.	\(p \times 1\)
\(c\)	State intercept.	\(m \times 1\)
\(T\)	Transition matrix.	\(m \times m\)
\(R\)	Selection matrix.	\(m \times r\)
\(\eta_t\)	State disturbance.	\(r \times 1\)
\(Q\)	State disturbance covariance matrix.	\(r \times r\)

Notice that the current GAUSS sslib only supports time-invariant state-space models such that all state-space representation matrices are constant.

This state-space representation is a flexible platform for modeling and supports a variety of time series models including ARIMA, SARIMA, VAR, unobserved components, and dynamic factor models.

Example: AR(2)¶

Consider the \(AR(2)\) model

\[y_t = \phi_1 y_{t-1} + \phi_2 y_{t-2} + e_t\]

\[e_t \sim N(0, \sigma^2)\]

There are a number of ways to transform this model to state-space representation. Consider, for example, letting \(\alpha_t = (y_t, y_{t-1})'\).

Transition Equation:

\[\begin{split}\alpha_t = \begin{bmatrix} \phi_1 & \phi_2\\ 1 & 0\end{bmatrix} \alpha_{t-1} + \begin{bmatrix} 1\\ 0 \end{bmatrix} \eta_t\end{split}\]

Measurement Equation:

\[y_t = \begin{bmatrix} 1 & 0 \end{bmatrix} \alpha_t\]

In this representation the system matrices are:

Object	Specification
\(d\)	0
\(Z\)	\(\begin{bmatrix} 1 & 0 \end{bmatrix}\)
\(H\)	0
\(c\)	0
\(T\)	\(\begin{bmatrix} \phi_1 & \phi_2\\ 1 & 0 \end{bmatrix}\)
\(R\)	\(\begin{bmatrix} 1 \\ 0 \end{bmatrix}\)
\(Q\)	\(\sigma^2\)

The unknown parameters are \(\phi_1\), \(\phi_2\), and \(\sigma^2\).

Estimation of State-Space Models¶

The GAUSS sslib relies on two tools for estimating state-space models, the Kalman filter and maximum likelihood estimation.

Tool	Purpose
Kalman filter	The Kalman filter uses recursive iteration to estimate the unknown state.
Maximum likelihood	Uses the likelihood function generated from the Kalman filter to estimate the unknown parameters.

You will never need to interact with these two tools directly when using the GAUSS state-space framework. However, for more information about either of these please see the following:

State-Space Models in GAUSS¶

The sslib library contains a suite of tools that allows you to specify, estimate, diagnose, and perform post-estimation forecasts.

Prior to estimating the model with ssFit(), there are several simple steps that must be taken:

Load data and required libraries.
Set up parameter vector and start values.
Set up control structures.
Initialize system matrices.
Specify variable constraints.
Set up procedure for updating system matrices.

Step One: Load data and libraries¶

The first step to estimating state-space models in GAUSS is to load the data and proper libraries:

new;
library sslib, tsmt, cmlmt;

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

Step Two: Set up parameter vector and start values¶

If you are estimating a custom state-space model, a vector of parameter starting values is required. The parameter vector should be a column vector which contains a starting value for each unknown parameter.

In the \(AR(2)\) model there are three unknown parameters \(\phi_1\), \(\phi_2\), and \(\sigma^2\).

/*
** Set up parameter vector
** and start values
*/

// Create a dataframe
param_vec_st = asDF(zeros(3, 1), "param");

// Starting values for phi_1,
// phi_2, and sigma2
param_vec_st[1] = -0.322;
param_vec_st[2] = 0.433;
param_vec_st[3] = 0.0025;

Step Three: Set up the control structure¶

The ssControl structure is used to:

Specify the state-space system matrices.
Implement stationarity and non-negativity constraints on parameters.
Control modeling features.
Specify advanced maximum likelihood controls.

Before using the ssControl structure:

The model dimensions must be specified.
The control structure must be initialized.
The default values must be filled.

Specifying the model dimensions¶

The model dimensions are defined by three variables:

Variable	Description
`k_endog`	Number of endogenous variables.
`k_states`	Number of state variables.
`k_posdef`	Optional, dimension of the state innovation with a positive definite covariance matrix. Default = k_states.

The \(AR(2)\) model has one endogenous variable and two state variables:

/*
** Declare shape
*/
// Number of endogenous variables
k_endog = 1;

// Number of states
k_states = 2;

Initialize control structure and system matrices¶

After specifying the model dimensions, the ssControl structure and the system matrices should be initialized using the ssControlCreate() procedure.

// Declare an instance of
// ssControl structure
struct ssControl ssCtl;

// Fill the control structure with defaults
// and sets up the system matrices.
ssCtl = ssControlCreate(k_states, k_endog);

The ssControlCreate() procedure initiates the state-space system matrices in a ssModel structure. The matrices are all set to zeroes in the following dimensions:

Object	Specification
\(ssm.d\)	\(k_{endog} \times 1\)
\(ssm.Z\)	\(k_{endog} \times k_{states}\)
\(ssm.H\)	\(k_{endog} \times k_{endog}\)
\(ssm.c\)	\(k_{states} \times k_{states}\)
\(ssm.T\)	\(k_{states} \times k_{states}\)
\(ssm.R\)	\(k_{states} \times k_{posdef}\)
\(ssm.Q\)	\(k_{posdef} \times k_{posdef}\)

Step Four: Set up fixed system matrices¶

After initializing the ssControl structure any elements of the system matrices that are fixed and do not contain parameters to be estimated should be specified using GAUSS matrix notation.

For example, in the \(AR(2)\) example above, the design matrix, \(Z\), is given by

\[\begin{bmatrix} 1 & 0 \end{bmatrix}\]

and the selection matrix, \(R\), is given by

\[\begin{split}\begin{bmatrix} 1 \\ 0 \end{bmatrix}\end{split}\]

These matrices have no relationship to the model parameters and should be specified before calling the ssFit() procedure:

/*
** Step four: Set up fixed system
**            matrices
**
** The system matrices are stored in the
** control structure in ssModel structure ssm:
**
*/

// Set design matrix by
// specifying full matrix
ssCtl.ssm.Z = { 1 0 };

// Set selection matrix by
// specifying the 1,1 element
ssCtl.ssm.R[1, 1] = 1;

In the example above, two different approaches are taken to setting the fixed elements in the system matrices.

The first is to set the entire transition (\(Z\)) matrix.
The second is to just change the 1,1 element of the selection matrix (\(R\)).

After setting the fixed elements, the transition and selection matrices are:

ssCtl.ssm.Z
     1.0000000        0.0000000

ssCtl.ssm.R
     1.0000000        0.0000000
     0.0000000        0.0000000

Step Five: Set up parameter constraints¶

The sslib library includes tools for implementing two types of parameter constraints:

Non-negativity constraint using the positive_vars member of the ssControl structure.
Stationarity constraint using the stationary_vars member of the ssControl structure.

In the \(AR(2)\) model:

\(\phi_1\) and \(\phi_2\) should be stationary.
\(\sigma^2\) should be non-negative.

/*
** Constrained variables
*/

/*
** This stationary_vars member
** indicates which variables should be
** constrained to stationarity.
*/
// Set the first and second parameters in
// the parameter vector to be stationary
ssCtl.stationary_vars = 1|2;

/*
** This positive_vars member
** indicates which variables should be
** constrained to positive.
*/
// Set the third parameters in
// the parameter vector to be positive
ssCtl.positive_vars = 3;

Step Six: Set procedure for updating the `ssModel` structure with parameters¶

The final step before calling the ssFit() procedure is to specify the relationship between the state-space system matrices and the model parameters using a updateSSModel procedure.

The updateSSModel function should always include two input parameters:

Object	Specification
`*ssmod`	A pointer to the `ssmod` structure.
`param`	The parameter vector.

The updateSSModel is a user-defined function whose body describes how the parameters fit into the system matrices. The function uses a pointer to the *ssmod structure and the -> method for assigning values to members within the structures.

For example, the updateSSModel for the \(AR(2)\) model is:

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

  // Specify transition matrix
  ssmod->T =  param[1 2]'|(1~0);

  // Specify state covariance
  ssmod->Q[1, 1] = param[3];

endp;

Estimating the model¶

Once the model is specified and the constraints are set, the parameters are estimated using the ssFit() procedure. This procedure requires four inputs:

Variable	Description
`&updateSSModel`	A pointer to the user-defined, state-space system update function.
`param_vec_st`	Parameter vector with starting values.
`y`	Data.
`ssCtl`	An instance of the `ssControl` structure. Should be initialized using the `ssControlCreate` procedure.

/*
** Step six: Call the ssFit procedure.
**            This will:
**              1. Estimate model parameters.
**              2. Estimate inference statistics (se, t-stats).
**              3. Perform model residual diagnostics.
**              4. Compute model diagnostics and summary statistics.
*/
struct ssOut sOut;
sOut = ssFit(&updateSSModel, param_vec_st, y, ssCtl);

The ssFit() procedure estimates the model parameters and their inference statistics:

 Return Code:                                                             0
 Log-likelihood:                                                     -37.38
 Number of Cases:                                                        99
 AIC:                                                                 80.75
 AICC:                                                                   81
 BIC:                                                                 88.57
 HQIC:                                                                79.34
 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

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

It also prints model and residual diagnostics:

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
==========================================================================

GAUSS State-Space Modeling (SSLIB)

ssARIMA