Main Content

**Superclasses: **

Create state-space model

`ssm`

creates a standard, linear, state-space model object with independent Gaussian state disturbances and observation innovations.

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

Once you have specified a model:

If it contains unknown parameters, then pass the model and data to

`estimate`

, which estimates the parameters.If the state and observation matrices do not contain unknown parameters (for example, an estimated

`ssm`

model), then you can pass it to:`ssm`

supports regression of exogenous predictors. To include a regression component that deflates the observations, see`estimate`

,`filter`

,`forecast`

, and`smooth`

.

creates a state-space model (`Mdl`

= ssm(`A`

,`B`

,`C`

)`Mdl`

) using state-transition matrix `A`

, state-disturbance-loading matrix `B`

, and measurement-sensitivity matrix `C`

.

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

= ssm(`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`

= ssm(___,`Name,Value`

)`Name,Value`

pair arguments.

`Name`

can also be a property name and `Value`

is the corresponding value. `Name`

must appear inside single quotes (`''`

). You can specify several name-value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`

.

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

= ssm(`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`

, or `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 diffuse state-space model object (`Mdl`

= ssm(`DSSMMdl`

)`DSSMMdl`

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

). `ssm`

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

to `1e07`

.

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

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.

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

`ssm`

generates the initial values. Otherwise, the software generates the initial values during estimation.For states that are always the constant 1,

`ssm`

sets`Mean0`

to 1 and`Cov0`

to`0`

.For diffuse states, the software sets

`Mean0`

to 0 and`Cov0`

to`1e7`

by default.

If you implicitly create the state-space model (that is, you provide the parameter vector to the coefficient-matrices-mapping function

`ParamMap`

), then the software generates any 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.`ssm`

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 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 = ssm(@(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.

If the states are observable, and the state equation resembles:

An ARIMA model, then you can specify an

`arima`

model instead.A regression model with ARIMA errors, then you can specify a

`regARIMA`

model instead.A conditional variance model, then you can specify a

`garch`

,`egarch`

, or`gjr`

model instead.A VAR model, then you can estimate such a model using

`varm`

and`estimate`

.

To impose no prior knowledge on the initial state values of diffuse states, and to implement the diffuse Kalman filter, create a

`dssm`

model object instead of an`ssm`

model object.

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