dssm

Create diffuse linear Gaussian state-space model

Description

The dssm function returns a dssm object specifying the functional form and storing the parameter values of a diffuse linear Gaussian state-space model for a latent state process x_t possibly imperfectly observed through the variable y_t. The variables x_t and y_t can be univariate or multivariate and the model parameters or variable dimensions can be time-invariant or time-varying (see Decide on Model Structure). A diffuse state-space model contains diffuse states, and variances of the initial distributions of diffuse states are Inf. All diffuse states are independent of each other and all other states. Object functions of the dssm object implement the diffuse Kalman filter for filtering, smoothing, and parameter estimation.

The key components of a dssm object are the state-transition A, state-disturbance-loading B, measurement-sensitivity C, and observation-innovation D coefficient matrices because they completely specify the model structure. You can explicitly specify each matrix or supply a custom function that implicitly specifies them. Regardless, given the model structure, all coefficients are unknown and estimable unless you specify their values.

To estimate a model containing unknown parameter values, pass the model and data to estimate. To work with an estimated or fully specified dssm object, pass it to an object function.

Alternative state-space models include:

• The ssm model object — Standard linear Gaussian state-space model

• The bssm model object — Bayesian linear state-space model

• The bnlssm model object — Bayesian nonlinear non-Gaussian state-space model

Creation

Syntax

Mdl = dssm(A,B,C)

Mdl = dssm(A,B,C,D)

Mdl = dssm(___,Name=Value)

Mdl = dssm(ParamMap)

Mdl = dssm(SSMMdl)

Description

Explicitly Specify Coefficient Matrices

Mdl = dssm(A,B,C) returns the diffuse linear Gaussian state-space model Mdl with state-transition matrix A, state-disturbance-loading matrix B, and measurement-sensitivity matrix C. At each time t, the state combination y_t = Cx_t is observed without error. dssm sets the model properties A, B, and C from the corresponding inputs.

Mdl = dssm(A,B,C,D) additionally specifies the observation-innovation matrix D and sets the property D.

Mdl = dssm(___,Name=Value) sets properties that describe the initial state distribution using name-value arguments, and using any input-argument combination in the previous syntaxes. For example, dssm(A,B,C,StateType=[0; 1; 2]) specifies that the first state variable is initially stationary, the second state variable is initially the constant 1, and the third state variable is initially nonstationary.

Implicitly Specify Coefficient Matrices By Using Custom Function

Mdl = dssm(ParamMap) returns the diffuse state-space model Mdl whose structure is specified by the custom parameter-to-matrix mapping function ParamMap. The function maps a parameter vector θ to the matrices A, B, and C. Optionally, ParamMap can map parameters to D, Mean0, Cov0, or StateType. To accommodate a regression component in the observation equation, ParamMap can return deflated observation data.

Convert from Diffuse to Standard State-Space Model

Mdl = dssm(SSMMdl) converts a standard state-space model object SSMMdl to a diffuse state-space model object Mdl. dssm sets all initial variances of diffuse states in Mdl.Cov0 to Inf.

Because Mdl is a diffuse state-space model, dssm object functions apply the diffuse Kalman filter, instead of the standard Kalman filter, for filtering, smoothing, and parameter estimation.

Input Arguments

SSMMdl — Standard state-space model

ssm model object

Standard state-space model to convert to a diffuse state-space model, specified as an ssm model object.

dssm sets all initial state variances of nonconstant states to Inf and all initial states variances of constant states to 0.

Properties

A — State-transition coefficient matrix

matrix | cell vector of matrices | empty array []

State-transition coefficient matrix for explicit state-space model creation, specified as a matrix or cell vector of matrices. When you implicitly create a model, dssm sets A to an empty array, and determines the state-transition coefficient matrix from ParamMap

The state-transition coefficient matrix, A_t, specifies how the states, x_t, are expected to transition from period t – 1 to t, for all t = 1,...,T. That is, the expected state-transition equation at period t is E(x_t|x_t–1) = A_tx_t–1.

For time-invariant state-space models, specify A as an m-by-m matrix, where m is the number of states per period.

For time-varying state-space models, specify A as a T-dimensional cell array, where A{t} contains an m_t-by-m_{t – 1} state-transition coefficient matrix. If the number of states changes from period t – 1 to t, then m_t ≠ m_{t – 1}.

NaN values in any coefficient matrix indicate unique, unknown parameters in the state-space model. A contributes:

• sum(isnan(A(:))) unknown parameters to time-invariant state-space models. In other words, if the state-space model is time invariant, then the software uses the same unknown parameters defined in A at each period.

• numParamsA unknown parameters to time-varying state-space models, where numParamsA = sum(cell2mat(cellfun(@(x)sum(sum(isnan(x))),A,'UniformOutput',0))). In other words, if the state-space model is time varying, then the software assigns a new set of parameters for each matrix in A.

You cannot specify A and ParamMap simultaneously.

Data Types: double | cell

B — State-disturbance-loading coefficient matrix

matrix | cell vector of matrices | empty array []

State-disturbance-loading coefficient matrix for explicit state-space model creation, specified as a matrix or cell vector of matrices. When you implicitly create a model, dssm sets B to an empty array, and determines the state-disturbance-loading coefficient matrix from ParamMap.

The state disturbances, u_t, are independent Gaussian random variables with mean 0 and standard deviation 1. The state-disturbance-loading coefficient matrix, B_t, specifies the additive error structure in the state-transition equation from period t – 1 to t, for all t = 1,...,T. That is, the state-transition equation at period t is x_t = A_tx_t–1 + B_tu_t.

For time-invariant state-space models, specify B as an m-by-k matrix, where m is the number of states and k is the number of state disturbances per period. B*B' is the state-disturbance covariance matrix for all periods.

For time-varying state-space models, specify B as a T-dimensional cell array, where B{t} contains an m_t-by-k_t state-disturbance-loading coefficient matrix. If the number of states or state disturbances changes at period t, then the matrix dimensions between B{t-1} and B{t} vary. B{t}*B{t}' is the state-disturbance covariance matrix for period t.

NaN values in any coefficient matrix indicate unique, unknown parameters in the state-space model. B contributes:

• sum(isnan(B(:))) unknown parameters to time-invariant state-space models. In other words, if the state-space model is time invariant, then the software uses the same unknown parameters defined in B at each period.

• numParamsB unknown parameters to time-varying state-space models, where numParamsB = sum(cell2mat(cellfun(@(x)sum(sum(isnan(x))),B,'UniformOutput',0))). In other words, if the state-space model is time varying, then the software assigns a new set of parameters for each matrix in B.

You cannot specify B and ParamMap simultaneously.

Data Types: double | cell

C — Measurement-sensitivity coefficient matrix

matrix | cell vector of matrices | empty array []

Measurement-sensitivity coefficient matrix for explicit state-space model creation, specified as a matrix or cell vector of matrices. When you implicitly create a model, dssm sets C to an empty array, and determines the measurement-sensitivity coefficient matrix from ParamMap.

The measurement-sensitivity coefficient matrix, C_t, specifies how the states are expected to linearly combine at period t to form the observations, y_t, for all t = 1,...,T. That is, the expected observation equation at period t is E(y_t|x_t) = C_tx_t.

For time-invariant state-space models, specify C as an n-by-m matrix, where n is the number of observations and m is the number of states per period.

For time-varying state-space models, specify C as a T-dimensional cell array, where C{t} contains an n_t-by-m_t measurement-sensitivity coefficient matrix. If the number of states or observations changes at period t, then the matrix dimensions between C{t-1} and C{t} vary.

NaN values in any coefficient matrix indicate unique, unknown parameters in the state-space model. C contributes:

• sum(isnan(C(:))) unknown parameters to time-invariant state-space models. In other words, if the state-space model is time invariant, then the software uses the same unknown parameters defined in C at each period.

• numParamsC unknown parameters to time-varying state-space models, where numParamsC = sum(cell2mat(cellfun(@(x)sum(sum(isnan(x))),C,'UniformOutput',0))). In other words, if the state-space model is time varying, then the software assigns a new set of parameters for each matrix in C.

You cannot specify C and ParamMap simultaneously.

Data Types: double | cell

D — Observation-innovation coefficient matrix

empty array [] (default) | matrix | cell vector of matrices

Observation-innovation coefficient matrix for explicit state-space model creation, specified as a matrix or cell vector of matrices.

The observation innovations, ε_t, are independent Gaussian random variables with mean 0 and standard deviation 1. The observation-innovation coefficient matrix, D_t, specifies the additive error structure in the observation equation at period t, for all t = 1,...,T. That is, the observation equation at period t is y_t = C_tx_t + D_tε_t.

For time-invariant state-space models, specify D as an n-by-h matrix, where n is the number of observations and h is the number of observation innovations per period. D*D' is the observation-innovation covariance matrix for all periods.

For time-varying state-space models, specify D as a T-dimensional cell array, where D{t} contains an n_t-by-h_t matrix. If the number of observations or observation innovations changes at period t, then the matrix dimensions between D{t-1} and D{t} vary. D{t}*D{t}' is the observation-innovation covariance matrix for period t.

NaN values in any coefficient matrix indicate unique, unknown parameters in the state-space model. D contributes:

• sum(isnan(D(:))) unknown parameters to time-invariant state-space models. In other words, if the state-space model is time invariant, then the software uses the same unknown parameters defined in D at each period.

• numParamsD unknown parameters to time-varying state-space models, where numParamsD = sum(cell2mat(cellfun(@(x)sum(sum(isnan(x))),D,'UniformOutput',0))). In other words, if the state-space model is time varying, then the software assigns a new set of parameters for each matrix in D.

By default, D is an empty matrix indicating no observation innovations in the state-space model. However, when you implicitly create a model, dssm sets D to [], and determines the observation-innovation coefficient matrix from ParamMap.

You cannot specify D and ParamMap simultaneously.

Data Types: double | cell

Mean0 — Initial state mean

numeric vector | empty array []

Initial state mean for explicit state-space model creation, specified as a numeric vector or an empty array ([]). As a numeric vector, Mean0 has length equal to the number of initial states (size(A,1) or size(A{1},1)). Mean0 is the mean of the Gaussian distribution of the states at period 0.

If you implicitly create a state-space model by specifying ParamMap, the following conditions apply:

• You cannot specify the Mean0 property by using name-value argument syntax. Instead, specify the initial state mean in the parameter-to-matrix mapping function.

• Before you estimate the model by using the estimate function, Mean0 is [] and read only. The estimate function specifies Mean0 after estimation.

For the default values, see Algorithms.

Data Types: double

Cov0 — Initial state covariance matrix

square matrix | empty array []

Initial state covariance matrix, specified as a square matrix or an empty array []. As a matrix, Cov0 has dimensions equal to the number of initial states (size(A,1) or size(A{1},1)). Cov0 is the covariance of the Gaussian distribution of the states at period 0.

If you implicitly create a state-space model by specifying ParamMap, the following conditions apply:

• You cannot specify the Cov0 property by using name-value argument syntax. Instead, specify the initial state covariance in the parameter-to-matrix mapping function.

• Before you estimate the model by using the estimate function, Cov0 is [] and read only. The estimate function specifies Cov0 after estimation.

Diagonal elements of Cov0 that have value Inf correspond to diffuse initial state distributions. This specification indicates complete ignorance or no prior knowledge of the initial state value. Subsequently, the software filters, smooths, and estimates parameters in the presence of diffuse initial state distributions using the diffuse Kalman filter. To use the standard Kalman filter for diffuse states instead, set each diagonal element of Cov0 to a large, positive value, for example, 1e7. This specification suggests relatively weak knowledge of the initial state value.

For the default values, see Algorithms.

Data Types: double

StateType — Initial state distribution type

numeric vector | empty array []

Initial state distribution type, specified as a numeric vector or empty array []. As a numeric vector, StateType has length equal to the number of initial states (size(A,1) or size(A{1},1)).

This table summarizes the available types of initial state distributions.

Value	Initial State Distribution Type
0	Stationary (e.g., ARMA models)
1	The constant 1 (that is, the state is 1 with probability 1)
2	Nonstationary (e.g., random walk model, seasonal linear time series) or static state

Example: Suppose that the state equation has two state variables: The first state variable is an AR(1) process, and the second state variable is a random walk. Set StateType to [0; 2].

If you implicitly create a state-space model by specifying ParamMap, the following conditions apply:

• You cannot specify the StateType property by using name-value argument syntax. Instead, specify the initial state covariance in the parameter-to-matrix mapping function.

• Before you estimate the model by using the estimate function, StateType is [] and read only. The estimate function specifies StateType after estimation.

For nonstationary states, dssm sets Cov0 to Inf by default. Subsequently, the software assumes that diffuse states are uncorrelated and implements the diffuse Kalman filter for filtering, smoothing, and parameter estimation. This specification imposes no prior knowledge on the initial state values of diffuse states.

Data Types: double

ParamMap — Parameter-to-matrix mapping function

empty array [] (default) | function handle

Parameter-to-matrix mapping function for implicit state-space model creation, specified as a function handle.

The function, to which ParamMap is a function handle, must accept at least one input argument and return at least three output arguments. The requisite input argument is a vector of unknown state-space model parameters θ, and the requisite output arguments correspond to the coefficient matrices A, B, and C, respectively. If your parameter-to-mapping function requires the input θ only, then implicitly create a state-space model by entering

Mdl = ssm(@ParamMap)

In general, you can write an intermediate function, for example, ParamFun, using the syntax

function [A,B,C,D,Mean0,Cov0,StateType,DeflateY] = ...
    ParamFun(theta,...otherInputArgs...)

In this general case, create the state-space model by entering

Mdl = ssm(@(theta)ParamMap(theta,...otherInputArgs...))

However, the following conditions apply:

• Follow the order of the output arguments.

• theta is a vector, and each element corresponds to an unknown state-space model parameter.

• ParamFun must return A, B, and C, which correspond to the state-transition, state-disturbance-loading, and measurement-sensitivity coefficient matrices, respectively.

• For the optional output arguments D, Mean0, Cov0, StateType, and DeflateY:

  • The optional output arguments correspond to the observation-innovation coefficient matrix D and the properties Mean0, Cov0, and StateType.

  • To skip specifying an optional output argument, set the argument to [] in the function body. For example, to skip specifying D, then set D = []; in the function.

  • DeflateY is the deflated-observation data, which accommodates a regression component in the observation equation. For example, in this function, which has a linear regression component, Y is the vector of observed responses and Z is the vector of predictor data.

    function [A,B,C,D,Mean0,Cov0,StateType,DeflateY] = ParamFun(theta,Y,Z)
    	...
    	DeflateY = Y - theta(9) - theta(10)*Z;
    	...
    end

  • For the default values of Mean0, Cov0, and StateType, see Algorithms.

• It is best practice to:

  • Load the data to the MATLAB^® Workspace before specifying the model.

  • Create the parameter-to-matrix mapping function as its own file.

If you specify ParamMap, you cannot specify any other property or input argument.

If you explicitly create a state-space model, ParamMap is an empty array [].

Data Types: function_handle

Object Functions

Fit Model to Data

estimate	Maximum likelihood parameter estimation of diffuse state-space models
refine	Refine initial parameters to aid diffuse state-space model estimation
disp	Display summary information for diffuse state-space model

Estimate State Variables

filter	Forward recursion of diffuse state-space models
smooth	Backward recursion of diffuse state-space models

Impulse Response Function

irf	Impulse response function (IRF) of state-space model
irfplot	Plot impulse response function (IRF) of state-space model

Generate Minimum Mean Square Error Forecasts

forecast

Forecast states and observations of diffuse state-space models

Examples

Explicitly Create Diffuse State-Space Model Containing Known and Unknown Parameters

Create a diffuse state-space model containing two independent states, $$x_{1,t}$$ and $$x_{3,t}$$, and an observation, $$y_t$$, that is the deterministic sum of the two states at time $$t$$. $$x_1$$ is an AR(1) model with a constant and $$x_3$$ is a random walk. Symbolically, the state-space model is

$$\left[\begin{array}{c}{x}_{1,t}\\ x_{2,t}\\ x_{3,t}\end{array}\right]=\left[\begin{array}{ccc}{\varphi }_1& c_1& 0\\ 0& 1& 0\\ 0& 0& 1\end{array}\right]\left[\begin{array}{c}{x}_{t-1,1}\\ x_{t-1,2}\\ x_{t-1,3}\end{array}\right]+\left[\begin{array}{cc}{\sigma }_1& 0\\ 0& 0\\ 0& {\sigma }_2\end{array}\right]\left[\begin{array}{c}{u}_{t,1}\\ u_{t,3}\end{array}\right]$$

$$y_t=\left[\begin{array}{ccc}1& 0& 1\end{array}\right]\left[\begin{array}{c}{x}_{t,1}\\ x_{t,2}\\ x_{t,3}\end{array}\right].$$

The state disturbances, $$u_{1,t}$$ and $$u_{3,t}$$, are standard Gaussian random variables.

Specify the state-transition matrix.

A = [NaN NaN 0; 0 1 0; 0 0 1];

The NaN values indicate unknown parameters.

Specify the state-disturbance-loading matrix.

B = [NaN 0; 0 0; 0 NaN];

Specify the measurement-sensitivity matrix.

C = [1 0 1];

Create a vector that specifies the state types. In this example:

• $$x_{1,t}$$ is a stationary AR(1) model, so its state type is 0.

• $$x_{2,t}$$ is a placeholder for the constant in the AR(1) model. Because the constant is unknown and is expressed in the first equation, $$x_{2,t}$$ is 1 for the entire series. Therefore, its state type is 1.

• $$x_{3,t}$$ is a nonstationary, random walk with drift, so its state type is 2.

StateType = [0 1 2];

Create the state-space model using dssm.

Mdl = dssm(A,B,C,StateType=StateType)

Mdl = 
State-space model type: dssm

State vector length: 3
Observation vector length: 1
State disturbance vector length: 2
Observation innovation vector length: 0
Sample size supported by model: Unlimited
Unknown parameters for estimation: 4

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...
Unknown parameters: c1, c2,...

State equations:
x1(t) = (c1)x1(t-1) + (c2)x2(t-1) + (c3)u1(t)
x2(t) = x2(t-1)
x3(t) = x3(t-1) + (c4)u2(t)

Observation equation:
y1(t) = x1(t) + x3(t)

Initial state distribution:

Initial state means are not specified.
Initial state covariance matrix is not specified.
State types
     x1         x2        x3   
 Stationary  Constant  Diffuse 

Mdl is a dssm model object containing unknown parameters. A detailed summary of Mdl prints to the Command Window. If you do not specify the initial state covariance matrix, then the initial variance of $$x_{3,t}$$ is Inf.

It is good practice to verify that the state and observation equations are correct. If the equations are not correct, then expand the state-space equation and verify it manually.

Explicitly Create Diffuse State-Space Model Containing Observation Error

Create a diffuse state-space model containing two random walk states. The observations are the sum of the two states, plus Gaussian error. Symbolically, the equation is

$$\left[\begin{array}{c}{x}_{t,1}\\ x_{t,2}\end{array}\right]=\left[\begin{array}{cc}1& 0\\ 0& 1\end{array}\right]\left[\begin{array}{c}{x}_{t-1,1}\\ x_{t-1,2}\end{array}\right]+\left[\begin{array}{cc}{\sigma }_1& 0\\ 0& {\sigma }_2\end{array}\right]\left[\begin{array}{c}{u}_{t,1}\\ u_{t,2}\end{array}\right]$$

$$y_t=\left[\begin{array}{cc}1& 1\end{array}\right]\left[\begin{array}{c}{x}_{t,1}\\ x_{t,2}\end{array}\right]+{\sigma }_3{\epsilon }_t.$$

Define the state-transition matrix.

A = [1 0; 0 1];

Define the state-disturbance-loading matrix.

B = [NaN 0; 0 NaN];

Define the measurement-sensitivity matrix.

C = [1 1];

Define the observation-innovation matrix.

D = NaN;

Create a vector that specifies that both states are nonstationary.

StateType = [2; 2];

Create the state-space model using dssm.

 Mdl = dssm(A,B,C,D,StateType=StateType)

Mdl = 
State-space model type: dssm

State vector length: 2
Observation vector length: 1
State disturbance vector length: 2
Observation innovation vector length: 1
Sample size supported by model: Unlimited
Unknown parameters for estimation: 3

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...
Unknown parameters: c1, c2,...

State equations:
x1(t) = x1(t-1) + (c1)u1(t)
x2(t) = x2(t-1) + (c2)u2(t)

Observation equation:
y1(t) = x1(t) + x2(t) + (c3)e1(t)

Initial state distribution:

Initial state means are not specified.
Initial state covariance matrix is not specified.
State types
    x1       x2   
 Diffuse  Diffuse 

Mdl is an dssm model containing unknown parameters. A detailed summary of Mdl prints to the Command Window.

Pass the data and Mdl to estimate to estimate the parameters. During estimation, the initial state variances are Inf, and estimate implements the diffuse Kalman filter.

Create Known Diffuse State-Space Model with Initial State Values

Create a diffuse state-space model, where:

• The state $$x_{1,t}$$ is a stationary AR(2) model with $${\varphi }_1=0.6$$, $${\varphi }_2=0.2$$, and a constant 0.5. The state disturbance is a mean zero Gaussian random variable with standard deviation 0.3.

• The state $$x_{4,t}$$ is a random walk. The state disturbance is a mean zero Gaussian random variable with standard deviation 0.05.

• The observation $$y_{1,t}$$ is the difference between the current and previous value in the AR(2) state, plus a mean 0 Gaussian observation innovation with standard deviation 0.1.

• The observation $$y_{2,t}$$ is the random walk state plus a mean 0 Gaussian observation innovation with standard deviation 0.02.

Symbolically, the state-space model is

$$\left[\begin{array}{c}{x}_{1,t}\\ x_{2,t}\\ x_{3,t}\\ x_{4,t}\end{array}\right]=\left[\begin{array}{cccc}0.6& 0.2& 0.5& 0\\ 1& 0& 0& 0\\ 0& 0& 1& 0\\ 0& 0& 0& 1\end{array}\right]\left[\begin{array}{c}{x}_{1,t-1}\\ x_{2,t-1}\\ x_{3,t-1}\\ x_{4,t-1}\end{array}\right]+\left[\begin{array}{cc}0.3& 0\\ 0& 0\\ 0& 0\\ 0& 0.05\end{array}\right]\left[\begin{array}{c}{u}_{1,t}\\ u_{4,t}\end{array}\right]$$

$$\left[\begin{array}{c}{y}_{1,t}\\ y_{2,t}\end{array}\right]=\left[\begin{array}{cccc}1& -1& 0& 0\\ 0& 0& 0& 1\end{array}\right]\left[\begin{array}{c}{x}_{1,t}\\ x_{2,t}\\ x_{3,t}\\ x_{4,t}\end{array}\right]+\left[\begin{array}{cc}0.1& 0\\ 0& 0.02\end{array}\right]\left[\begin{array}{c}{\epsilon }_{1,t}\\ {\epsilon }_{2,t}\end{array}\right].$$

The model has four states: $$x_{1,t}$$ is the AR(2) process, $$x_{2,t}$$ represents $$x_{1,t-1}$$, $$x_{3,t}$$ is the AR(2) model constant, and $$x_{4,t}$$ is the random walk.

Define the state-transition matrix.

A = [0.6 0.2 0.5 0; 1 0 0 0; 0 0 1 0; 0 0 0 1];

Define the state-disturbance-loading matrix.

B = [0.3 0; 0 0; 0 0; 0 0.05];

Define the measurement-sensitivity matrix.

C = [1 -1 0 0; 0 0 0 1];

Define the observation-innovation matrix.

D = [0.1; 0.02];

Use dssm to create the state-space model. Identify the type of initial state distributions (StateType) by noting the following:

• $$x_{1,t}$$ is a stationary AR(2) process.

• $$x_{2,t}$$ is also a stationary AR(2) process.

• $$x_{3,t}$$ is the constant 1 for all periods.

• $$x_{4,t}$$ is nonstationary.

Set the initial state means to 0. The initial state mean for constant states must be 1.

mean0 = [0; 0; 1; 0];     
stateType = [0; 0; 1; 2];
Mdl = dssm(A,B,C,D,Mean0=mean0,StateType=stateType)

Mdl = 
State-space model type: dssm

State vector length: 4
Observation vector length: 2
State disturbance vector length: 2
Observation innovation vector length: 1
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = (0.60)x1(t-1) + (0.20)x2(t-1) + (0.50)x3(t-1) + (0.30)u1(t)
x2(t) = x1(t-1)
x3(t) = x3(t-1)
x4(t) = x4(t-1) + (0.05)u2(t)

Observation equations:
y1(t) = x1(t) - x2(t) + (0.10)e1(t)
y2(t) = x4(t) + (0.02)e1(t)

Initial state distribution:

Initial state means
 x1  x2  x3  x4 
  0   0   1   0 

Initial state covariance matrix
     x1    x2    x3  x4  
 x1  0.21  0.16   0  0   
 x2  0.16  0.21   0  0   
 x3   0     0     0  0   
 x4   0     0     0  Inf 

State types
     x1          x2         x3        x4   
 Stationary  Stationary  Constant  Diffuse 

Mdl is a dssm model object. dssm sets the initial state:

• Covariance matrix for the stationary states to the asymptotic covariance of the AR(2) model

• Variance for constant states to 0

• Variance for diffuse states to Inf

You can display or modify properties of Mdl using dot notation. For example, display the initial state covariance matrix.

Mdl.Cov0

ans = 4×4

    0.2143    0.1607         0         0
    0.1607    0.2143         0         0
         0         0         0         0
         0         0         0       Inf

Reset the initial state means for the stationary states to their asymptotic values.

Mdl.Mean0(1:2) = 0.5/(1-0.2-0.6);
Mdl.Mean0

ans = 4×1

    2.5000
    2.5000
    1.0000
         0

Implicitly Create Time-Invariant State-Space Model

Use a parameter mapping function to create a time-invariant state-space model, where the state model is AR(1) model. The states are observed with bias, but without random error. Set the initial state mean and variance, and specify that the state is stationary.

Write a function that specifies how the parameters in params map to the state-space model matrices, the initial state values, and the type of state. Symbolically, the model is

% Copyright 2015 The MathWorks, Inc.

function [A,B,C,D,Mean0,Cov0,StateType] = timeInvariantParamMap(params)
% Time-invariant state-space model parameter mapping function example. This
% function maps the vector params to the state-space matrices (A, B, C, and
% D), the initial state value and the initial state variance (Mean0 and
% Cov0), and the type of state (StateType). The state model is AR(1)
% without observation error.
    varu1 = exp(params(2)); % Positive variance constraint
    A = params(1);
    B = sqrt(varu1);
    C = params(3);
    D = [];
    Mean0 = 0.5;
    Cov0 = 100;
    StateType = 0;
end

Save this code as a file named timeInvariantParamMap.m to a folder on your MATLAB® path.

Create the state-space model by passing the function timeInvariantParamMap as a function handle to ssm.

Mdl = ssm(@timeInvariantParamMap);

ssm implicitly creates the state-space model. Usually, you cannot verify implicitly defined state-space models.

Convert Standard to Diffuse State-Space Model

By default, ssm assigns a large scalar (1e7) to the initial state variance of all diffuse states in a standard state-space model. Using this specification, the software subsequently estimates, filters, and smooths a standard state-space model using the standard Kalman filter. A standard state-space model treatment is an approximation to results from an analysis that treats diffuse states using infinite variance. To implement the diffuse Kalman filter instead, convert the standard state-space model to a diffuse state-space model. This conversion attributes infinite variance to all diffuse states.

Explicitly create a two-dimensional standard state-space model. Specify that the first state equation is $$x_{1,t}=x_{1,t-1}+u_{1,t}$$ and that the second state equation is $$x_{2,t}=0.2x_{2,t-1}+u_{2,t}$$. Specify that the first observation equation is $$y_{1,t}=x_{1,t}+{\epsilon }_{1,t}$$ and that the second observation equation is $$y_{2,t}=x_{2,t}+{\epsilon }_{2,t}$$. Specify that the states are diffuse and nonstationary, respectively.

A = [1 0; 0 0.2];   
B = [1 0; 0 1]; 
C = [1 0;0 1]; 
D = [1 0; 0 1];
stateType = [2 0];
MdlSSM = ssm(A,B,C,D,StateType=stateType)

MdlSSM = 
State-space model type: ssm

State vector length: 2
Observation vector length: 2
State disturbance vector length: 2
Observation innovation vector length: 2
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = x1(t-1) + u1(t)
x2(t) = (0.20)x2(t-1) + u2(t)

Observation equations:
y1(t) = x1(t) + e1(t)
y2(t) = x2(t) + e2(t)

Initial state distribution:

Initial state means
 x1  x2 
  0   0 

Initial state covariance matrix
     x1        x2   
 x1  1.00e+07   0   
 x2   0        1.04 

State types
    x1        x2     
 Diffuse  Stationary 

MdlSSM is an ssm model object. In some cases, ssm can detect the state type, but it is good practice to specify whether the state is stationary, diffuse, or the constant 1. Because the model does not contain any unknown parameters, ssm infers the initial state distributions.

Convert MdlSSM to a diffuse state-space model.

Mdl = dssm(MdlSSM)

Mdl = 
State-space model type: dssm

State vector length: 2
Observation vector length: 2
State disturbance vector length: 2
Observation innovation vector length: 2
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = x1(t-1) + u1(t)
x2(t) = (0.20)x2(t-1) + u2(t)

Observation equations:
y1(t) = x1(t) + e1(t)
y2(t) = x2(t) + e2(t)

Initial state distribution:

Initial state means
 x1  x2 
  0   0 

Initial state covariance matrix
     x1   x2   
 x1  Inf   0   
 x2  0    1.04 

State types
    x1        x2     
 Diffuse  Stationary 

Mdl is a dssm model object. The structures of Mdl and MdlSSM are equivalent, except that the initial state variance of the state in Mdl is Inf rather than 1e7.

To see the difference between the two models, simulate 10 periods of data from a state-space model that is similar to MdlSSM. Set the initial state covariance matrix to $$I_2$$.

Mdl0 = MdlSSM;
Mdl0.Cov0 = eye(2);
T = 10;
rng(1); % For reproducibility
y = simulate(Mdl0,T);

Obtain filtered and smoothed states from Mdl and MdlSSM using the simulated data.

fY = filter(MdlSSM,y);
fYD = filter(Mdl,y);
sY = smooth(MdlSSM,y);
sYD = smooth(Mdl,y);

Plot the filtered and smoothed states.

figure
tiledlayout(2,1)
nexttile
plot(1:T,y(:,1),"-o",1:T,fY(:,1),"-d",1:T,fYD(:,1),"-*")
title("Filter Estimates of x_{1,t}")
nexttile
plot(1:T,y(:,1),"-o",1:T,sY(:,1),"-d",1:T,sYD(:,1),"-*")
title("Smooth Esimates of x_{1,t}")
legend("Simulated data","State estimates, MdlSSM","State estimates, Mdl", ...
    Location="best")

figure
tiledlayout(2,1)
nexttile
plot(1:T,y(:,2),"-o",1:T,fY(:,2),"-d",1:T,fYD(:,2),"-*")
title("Filtered States of x_{2,t}")
nexttile
plot(1:T,y(:,2),"-o",1:T,sY(:,2),"-d",1:T,sYD(:,2),"-*")
title("Smoothed States of x_{2,t}")
legend("Simulated data","State estimates, MdlSSM","State estimates, Mdl", ...
    Location="best")

In addition to apparent transient behavior in the random walk, the filtered and smoothed states between the standard and diffuse state-space models appear nearly equivalent. The slight difference occurs because filter and smooth set all diffuse state estimates in the diffuse state-space model to 0 while they implement the diffuse Kalman filter. Once the covariance matrices of the smoothed states attain full rank, filter and smooth switch to using the standard Kalman filter. In this case, the switching time occurs after the first period.

More About

Static State

A static state does not change in value throughout the sample, that is, $$P\left(x_{t+1}=x_t\right)=1$$ for all t = 1,...,T.

Tips

• Specify ParamMap in a more general or complex setting, where, for example:

  • The initial state values are parameters.

  • In time-varying models, you want to use the same parameters for more than one period.

  • You want to impose parameter constraints.

• You can create a dssm model object that does not contain any diffuse states. However, subsequent computations, for example, filtering and parameter estimation, can be inefficient. If all states have stationary distributions or are the constant 1, create an ssm model object instead.

Algorithms

• Default values for Mean0 and Cov0:

  • If you explicitly specify the state-space model (that is, you provide the coefficient matrices A, B, C, and optionally D), then:

    • For stationary states, the software generates the initial value using the stationary distribution. If you provide all values in the coefficient matrices (that is, your model has no unknown parameters), then dssm generates the initial values. Otherwise, the software generates the initial values during estimation.

    • For states that are always the constant 1, dssm sets Mean0 to 1 and Cov0 to 0.

    • For diffuse states, the software sets Mean0 to 0 and Cov0 to Inf by default.

  • If you implicitly specify the state-space model (that is, you provide the parameter vector to the coefficient-matrices-mapping function ParamMap), then the software generates the initial values during estimation.

• For static states that do not equal 1 throughout the sample, the software cannot assign a value to the degenerate, initial state distribution. Therefore, set static states to 2 using the name-value pair argument StateType. Subsequently, the software treats static states as nonstationary and assigns the static state a diffuse initial distribution.

• It is best practice to set StateType for each state. By default, the software generates StateType, but this behavior might not be accurate. For example, the software cannot distinguish between a constant 1 state and a static state.

• The software cannot infer StateType from data because the data theoretically comes from the observation equation. The realizations of the state equation are unobservable.

• dssm models do not store observed responses or predictor data. Supply the data wherever necessary using the appropriate input or name-value pair arguments.

• Suppose that you want to create a diffuse state-space model using a parameter-to-matrix mapping function with this signature:

  [A,B,C,D,Mean0,Cov0,StateType,DeflateY] = paramMap(params,Y,Z)

  and you specify the model using an anonymous function

  Mdl = dssm(@(params)paramMap(params,Y,Z))

  The observed responses Y and predictor data Z are not input arguments in the anonymous function. If Y and Z exist in the MATLAB Workspace before you create Mdl, then the software establishes a link to them. Otherwise, if you pass Mdl to estimate, the software throws an error.

  The link to the data established by the anonymous function overrides all other corresponding input argument values of dssm. This distinction is important particularly when conducting a rolling window analysis. For details, see Rolling-Window Analysis of Time-Series Models.

Alternatives

Create an ssm model object instead of a dssm model object when:

• The model does not contain any diffuse states.

• The diffuse states are correlated with each other or to other states.

• You want to implement the standard Kalman filter.

References

[1] Durbin, J, and Siem Jan Koopman. Time Series Analysis by State Space Methods. 2nd ed. Oxford: Oxford University Press, 2012.

Version History

Introduced in R2015b