# dssm class

**Superclasses: **

Create diffuse state-space model

## Description

`dssm`

creates a linear diffuse state-space model with independent Gaussian state disturbances and observation innovations. 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. The software implements the diffuse Kalman filter for filtering, smoothing, and parameter estimation.

You can:

Specify a time-invariant or time-varying model.

Specify whether states are stationary, static, or nonstationary.

Specify the state-transition, state-disturbance-loading, measurement-sensitivity, or observation-innovation matrices:

Explicitly by providing the matrices

Implicitly by providing a function that maps the parameters to the matrices, that is, a parameter-to-matrix mapping function

After creating a diffuse state-space model containing unknown parameters, you can estimate its parameters by passing the created `dssm`

model object and data to `estimate`

. The `estimate`

function builds the likelihood function using the diffuse Kalman filter.

Use a completely specified model (that is, all parameter values of the model are known) to:

## Construction

creates a diffuse state-space model (`Mdl`

= dssm(`A`

,`B`

,`C`

)`Mdl`

) using state-transition matrix `A`

, state-disturbance-loading matrix `B`

, and measurement-sensitivity matrix `C`

.

creates a diffuse state-space model using state-transition matrix `Mdl`

= dssm(`A`

,`B`

,`C`

,`D`

)`A`

, state-disturbance-loading matrix `B`

, measurement-sensitivity matrix `C`

, and observation-innovation matrix `D`

.

uses any of the input arguments in the previous syntaxes and additional options that you specify by one or more `Mdl`

= dssm(___,`Name,Value`

)`Name,Value`

pair arguments.

creates a diffuse state-space model using a parameter-to-matrix mapping function (`Mdl`

= dssm(`ParamMap`

)`ParamMap`

) that you write. The function maps a vector of parameters to the matrices `A`

, `B`

, and `C`

. Optionally, `ParamMap`

can map parameters to `D`

, `Mean0`

, `Cov0`

. To specify the types of states, the function can return `StateType`

. To accommodate a regression component in the observation equation, `ParamMap`

can also return deflated observation data.

converts a state-space model object (`Mdl`

= dssm(`SSMMdl`

)`SSMMdl`

) to a diffuse state-space model object (`Mdl`

). `dssm`

sets all initial variances of diffuse states in `SSMMdl.Cov0`

to `Inf`

.

### Input Arguments

`A`

— State-transition coefficient matrix

matrix | cell vector of matrices

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

The state-transition coefficient matrix, *A _{t}*, specifies how the states,

*x*, are expected to transition from period

_{t}*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*

_{t}*x*

_{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

State-disturbance-loading coefficient matrix for explicit state-space model creation, specified as a matrix or cell vector of matrices.

The state disturbances, *u _{t}*, are independent Gaussian random variables with mean 0 and standard deviation 1. The state-disturbance-loading coefficient matrix,

*B*, specifies the additive error structure in the state-transition equation from period

_{t}*t*– 1 to

*t*, for all

*t*= 1,...,

*T*. That is, the state-transition equation at period

*t*is

*x*=

_{t}*A*

_{t}*x*

_{t–1}+

*B*

_{t}*u*.

_{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*state-disturbance-loading coefficient matrix. If the number of states or state disturbances changes at period

_{t}*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

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

The measurement-sensitivity coefficient matrix, *C _{t}*, specifies how the states are expected to linearly combine at period

*t*to form the observations,

*y*, for all

_{t}*t*= 1,...,

*T*. That is, the expected observation equation at period

*t*is

*E*(

*y*|

_{t}*x*

_{t}) =

*C*

_{t}*x*

_{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*measurement-sensitivity coefficient matrix. If the number of states or observations changes at period

_{t}*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

`[]`

(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*, specifies the additive error structure in the observation equation at period

_{t}*t*, for all

*t*= 1,...,

*T*. That is, the observation equation at period

*t*is

*y*=

_{t}*C*

_{t}*x*

_{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*matrix. If the number of observations or observation innovations changes at period

_{t}*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.

You cannot specify `D`

and `ParamMap`

simultaneously.

**Data Types: **`double`

| `cell`

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

`ParamMap`

must be a function that takes at least one input argument and returns at least three output arguments. The requisite input argument is a vector of unknown 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 parameter vector argument only, then implicitly create a diffuse state-space model by entering the following:

Mdl = dssm(@ParamMap)

In general, you can write an intermediate function, for example, `ParamFun`

, using this syntax:

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

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

Mdl = dssm(@(params)ParamMap(params,...otherInputArgs...))

However:

Follow the order of the output arguments.

`params`

is a vector, and each element corresponds to an unknown parameter.`ParamFun`

must return`A`

,`B`

, and`C`

, which correspond to the state-transition, state-disturbance-loading, and measurement-sensitivity coefficient matrices, respectively.If you specify more input arguments than the parameter vector (

`params`

), such as observed responses and predictors, then implicitly create the diffuse state-space model using the syntax patternMdl = dssm(@(params)ParamFun(params,y,z))

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 name-value pair arguments`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(params,Y,Z) ... DeflateY = Y - params(9) - params(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`

, then you cannot specify any name-value pair arguments or any other input arguments.

**Data Types: **`function_handle`

`SSMMdl`

— State-space model

`ssm`

model object

State-space model to convert to a diffuse state-space model, specified as an `ssm`

model object.

`dssm`

sets all initial variances of diffuse states in `SSMMdl.Cov0`

to `Inf`

.

To use the diffuse Kalman filter for filtering, smoothing, and parameter estimation instead of the standard Kalman filter, convert a state-space model to a diffuse state-space model.

**Name-Value Arguments**

Specify optional pairs of arguments as
`Name1=Value1,...,NameN=ValueN`

, where `Name`

is
the argument name and `Value`

is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.

*
Before R2021a, use commas to separate each name and value, and enclose*
`Name`

*in quotes.*

`Mean0`

— Initial state mean

numeric vector

Initial state mean for explicit state-space model creation, specified as the comma-separated pair consisting of `'Mean0'`

and a numeric vector with length equal to the number of initial states. For the default values, see Algorithms.

If you specify `ParamMap`

, then you cannot specify `Mean0`

. Instead, specify the initial state mean in the parameter-to-matrix mapping function.

**Data Types: **`double`

`Cov0`

— Initial state covariance matrix

square matrix

Initial state covariance matrix for explicit state-space model
creation, specified as the comma-separated pair consisting of `'Cov0'`

and
a square matrix with dimensions equal to the number of initial states.
For the default values, see Algorithms.

If you specify `ParamMap`

, then you cannot
specify `Cov0`

. Instead, specify the initial state
covariance in the parameter-to-matrix mapping function.

**Data Types: **`double`

`StateType`

— Initial state distribution indicator

0 | 1 | 2

Initial state distribution indicator for explicit state-space
model creation, specified as the comma-separated pair consisting of `'StateType'`

and
a numeric vector with length equal to the number of initial states.
This table summarizes the available types of initial state distributions.

Value | Initial State Distribution Type |
---|---|

`0` | Stationary (for example, ARMA models) |

`1` | The constant 1 (that is, the state is 1 with probability 1) |

`2` | Diffuse or nonstationary (for example, random walk model, seasonal linear time series) or static state |

For 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.
Specify the initial distribution types by setting ```
'StateType',[0;
2]
```

.

If you specify `ParamMap`

, then you cannot
specify `Mean0`

. Instead, specify the initial state
distribution indicator in the parameter-to-matrix mapping function.

For the default values, see Algorithms.

**Data Types: **`double`

## Properties

`A`

— State-transition coefficient matrix

matrix | cell vector of matrices | empty array (`[]`

)

State-transition coefficient matrix for explicitly created state-space models, specified as a matrix, a cell vector of matrices, or an empty array (`[]`

). For implicitly created state-space models and before estimation, `A`

is `[]`

and read only.

The state-transition coefficient matrix, *A _{t}*, specifies how the states,

*x*, are expected to transition from period

_{t}*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*

_{t}*x*

_{t–1}.

For time-invariant state-space models, `A`

is an *m*-by-*m* matrix, where *m* is the number of states per period.

For time-varying state-space models, `A`

is 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 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`

.

**Data Types: **`double`

| `cell`

`B`

— State-disturbance-loading coefficient matrix

matrix | cell vector of matrices | empty array (`[]`

)

State-disturbance-loading coefficient matrix for explicitly created state-space models, specified as a matrix, a cell vector of matrices, or an empty array (`[]`

). For implicitly created state-space models and before estimation, `B`

is `[]`

and read only.

The state disturbances, *u _{t}*, are independent Gaussian random variables with mean 0 and standard deviation 1. The state-disturbance-loading coefficient matrix,

*B*, specifies the additive error structure in the state-transition equation from period

_{t}*t*– 1 to

*t*, for all

*t*= 1,...,

*T*. That is, the state-transition equation at period

*t*is

*x*=

_{t}*A*

_{t}*x*

_{t–1}+

*B*

_{t}*u*.

_{t}For time-invariant state-space models, `B`

is 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, `B`

is a *T*-dimensional cell array, where `B{t}`

contains an *m _{t}*-by-

*k*state-disturbance-loading coefficient matrix. If the number of states or state disturbances changes at period

_{t}*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 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`

.

**Data Types: **`double`

| `cell`

`C`

— Measurement-sensitivity coefficient matrix

matrix | cell vector of matrices | empty array (`[]`

)

Measurement-sensitivity coefficient matrix for explicitly created state-space models, specified as a matrix, a cell vector of matrices, or an empty array (`[]`

). For implicitly created state-space models and before estimation, `C`

is `[]`

and read only.

The measurement-sensitivity coefficient matrix, *C _{t}*, specifies how the states are expected to combine linearly at period

*t*to form the observations,

*y*, for all

_{t}*t*= 1,...,

*T*. That is, the expected observation equation at period

*t*is

*E*(

*y*|

_{t}*x*

_{t}) =

*C*

_{t}*x*

_{t}.

For time-invariant state-space models, `C`

is 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, `C`

is a *T*-dimensional cell array, where `C{t}`

contains an *n _{t}*-by-

*m*measurement-sensitivity coefficient matrix. If the number of states or observations changes at period

_{t}*t*, then the matrix dimensions between

`C{t-1}`

and `C{t}`

vary.`NaN`

values in any coefficient matrix indicate 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`

.

**Data Types: **`double`

| `cell`

`D`

— Observation-innovation coefficient matrix

matrix | cell vector of matrices | empty array (`[]`

)

Observation-innovation coefficient matrix for explicitly created state-space models, specified as a matrix, a cell vector of matrices, or an empty array (`[]`

). For implicitly created state-space models and before estimation, `D`

is `[]`

and read only.

The observation innovations, *ε _{t}*, are independent Gaussian random variables with mean 0 and standard deviation 1. The observation-innovation coefficient matrix,

*D*, specifies the additive error structure in the observation equation at period

_{t}*t*, for all

*t*= 1,...,

*T*. That is, the observation equation at period

*t*is

*y*=

_{t}*C*

_{t}*x*

_{t}+

*D*

_{t}*ε*.

_{t}For time-invariant state-space models, `D`

is 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, `D`

is a *T*-dimensional cell array, where `D{t}`

contains an *n _{t}*-by-

*h*matrix. If the number of observations or observation innovations changes at period

_{t}*t*, then the matrix dimensions between

`D{t-1}`

and `D{t}`

vary. `D{t}*D{t}'`

is the state-disturbance covariance matrix for period `t`

.`NaN`

values in any coefficient matrix indicate 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`

.

**Data Types: **`double`

| `cell`

`Mean0`

— Initial state mean

numeric vector | empty array (`[]`

)

Initial state mean, specified as a numeric vector or an empty array (`[]`

). `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.

For implicitly created state-space models and before estimation, `Mean0`

is `[]`

and read only. However, `estimate`

specifies `Mean0`

after estimation.

**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 (`[]`

). `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.

For implicitly created state-space models and before estimation, `Cov0`

is `[]`

and read only. However, `estimate`

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.

**Data Types: **`double`

`StateType`

— Initial state distribution type

numeric vector | empty array (`[]`

)

Initial state distribution indicator, specified as a numeric vector or empty array (`[]`

). `StateType`

has length equal to the number of initial states.

For implicitly created state-space models or models with unknown parameters, `StateType`

is `[]`

and read only.

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

For 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. Then, `StateType`

is `[0; 2]`

.

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

function handle | empty array (`[]`

)

Parameter-to-matrix mapping function, specified as a function
handle or an empty array (`[]`

). `ParamMap`

completely
specifies the structure of the state-space model. That is, `ParamMap`

defines `A`

, `B`

, `C`

, `D`

,
and, optionally, `Mean0`

, `Cov0`

,
and `StateType`

. For explicitly created state-space
models, `ParamMap`

is `[]`

and read
only.

**Data Types: **`function_handle`

## Object Functions

### Fit Model to Data

### Estimate State Variables

### Impulse Response Function

### Generate Minimum Mean Square Error Forecasts

`forecast` | Forecast states and observations of diffuse state-space models |

## Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.

## 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 (`Mean0`

) 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.2{x}_{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; subplot(2,1,1) plot(1:T,y(:,1),'-o',1:T,fY(:,1),'-d',1:T,fYD(:,1),'-*'); title('Filtered States for x_{1,t}') legend('Simulated Data','Filtered States -- MdlSSM','Filtered States -- Mdl'); subplot(2,1,2) plot(1:T,y(:,1),'-o',1:T,sY(:,1),'-d',1:T,sYD(:,1),'-*'); title('Smoothed States for x_{1,t}') legend('Simulated Data','Smoothed States -- MdlSSM','Smoothed States -- Mdl');

figure; subplot(2,1,1) plot(1:T,y(:,2),'-o',1:T,fY(:,2),'-d',1:T,fYD(:,2),'-*'); title('Filtered States for x_{2,t}') legend('Simulated Data','Filtered States -- MdlSSM','Filtered States -- Mdl'); subplot(2,1,2) plot(1:T,y(:,2),'-o',1:T,sY(:,2),'-d',1:T,sYD(:,2),'-*'); title('Smoothed States for x_{2,t}') legend('Simulated Data','Smoothed States -- MdlSSM','Smoothed States -- Mdl');

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, then 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:

and you specify the model using an anonymous function[A,B,C,D,Mean0,Cov0,StateType,DeflateY] = paramMap(params,Y,Z)

The observed responsesMdl = dssm(@(params)paramMap(params,Y,Z))

`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

`estimate`

. 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 S. J. Koopman. *Time Series Analysis by State Space Methods*. 2nd ed. Oxford: Oxford University Press, 2012.

## Version History

**Introduced in R2015b**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)