# 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.

• 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:

1. A working copy of GAUSS 22+.

2. The Constrained Maximum Likelihood MT library for GAUSS.

3. The Time Series MT library for GAUSS.

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.

// Create file name with full path


### 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:

1. Specify the state-space system matrices.

2. Implement stationarity and non-negativity constraints on parameters.

3. Control modeling features.

4. Specify advanced maximum likelihood controls.

Before using the ssControl structure:

1. The model dimensions must be specified.

2. The control structure must be initialized.

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