# 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*. The variables

_{t}*x*and

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

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

## Creation

### Syntax

### Description

#### Explicitly Specify Coefficient Matrices

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

= dssm(`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}`dssm`

sets the model properties
`A`

, `B`

, and `C`

from the
corresponding inputs.

additionally specifies the observation-innovation matrix `Mdl`

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

= dssm(___,`Name=Value`

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

returns the diffuse state-space model `Mdl`

= dssm(`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 standard 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 `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

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

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:

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

`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

## Version History

**Introduced in R2015b**