# ssm

Create standard linear Gaussian state-space model

## Description

The `ssm`

function returns an
`ssm`

object specifying the functional form and storing the parameter
values of a standard linear Gaussian state-space model for a latent
state process *x _{t}* possibly imperfectly observed
through the variable

*y*. The variables

_{t}*x*and

_{t}*y*can be univariate or multivariate and the model parameters can be time-invariant or time-varying.

_{t}The key components of an `ssm`

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

object, pass it to an object function.

Alternative state-space models include:

## Creation

### Syntax

### Description

#### Explicitly Specify Coefficient Matrices

returns the standard linear Gaussian state-space model
`Mdl`

= ssm(`A`

,`B`

,`C`

)`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}* =

`C`

*x*is observed without error.

_{t}`ssm`

sets the model properties
`A`

, `B`

, and `C`

from the
corresponding inputs.

additionally specifies the observation-innovation matrix `Mdl`

= ssm(`A`

,`B`

,`C`

,`D`

)`D`

and sets
the property `D`

.

sets properties that describe the initial state distribution using name-value arguments,
and using any input-argument combination in the previous syntaxes. For example,
`Mdl`

= ssm(___,`Name=Value`

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

returns the state-space model `Mdl`

= ssm(`ParamMap`

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

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

to `1e07`

.

Because `Mdl`

is a standard state-space model,
`ssm`

object functions apply the standard Kalman filter,
instead of the diffuse Kalman filter, for filtering, smoothing, and parameter
estimation.

### Input Arguments

## Properties

## Object Functions

## Examples

## More About

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

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

`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 nonstationary states,

`ssm`

sets`Cov0`

to`1e7`

by default. Subsequently, the software implements the Kalman filter for filtering, smoothing, and parameter estimation. This specification imposes relatively weak knowledge on the initial state values of diffuse states, and uses initial state covariance terms between all states.

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

## Alternatives

If the states are observable, and the state equation resembles any of the following models, use the associated function instead.

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.For a Bayesian view of a standard state-space model, use

`bssm`

.

## References

## Version History

**Introduced in R2014a**