Documentation

## Create State-Space Model with Unknown Parameters

### Explicitly Create State-Space Model Containing Unknown Parameters

This example shows how to create a time-invariant, state-space model containing unknown parameter values using `ssm`.

Define a state-space model containing two dependent MA(1) states, and an additive-error observation model. Symbolically, the equation is

`$\left[\begin{array}{c}{x}_{t,1}\\ {x}_{t,2}\\ {x}_{t,3}\\ {x}_{t,4}\end{array}\right]=\left[\begin{array}{cccc}0& {\theta }_{1}& {\lambda }_{1}& 0\\ 0& 0& 0& 0\\ 0& 0& 0& {\theta }_{3}\\ 0& 0& 0& 0\end{array}\right]\left[\begin{array}{c}{x}_{t-1,1}\\ {x}_{t-1,2}\\ {x}_{t-1,3}\\ {x}_{t-1,4}\end{array}\right]+\left[\begin{array}{cc}{\sigma }_{1}& 0\\ 1& 0\\ 0& {\sigma }_{2}\\ 0& 1\end{array}\right]\left[\begin{array}{c}{u}_{t,1}\\ {u}_{t,2}\end{array}\right]$`

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

Note that the states ${x}_{t,1}$ and ${x}_{t,3}$ are the two dependent MA(1) processes. The states ${x}_{t,2}$ and ${x}_{t,4}$ help construct the lag-one, MA effects. For example, ${x}_{t,2}$ picks up the first disturbance (${u}_{t,1}$), and ${x}_{t,1}$ picks up ${x}_{t-1,2}={u}_{t-1,1}$. In all, ${x}_{t,1}={\lambda }_{1}{x}_{t-1,3}+{u}_{t,1}+{\theta }_{1}{u}_{t-1,1}$, which is an MA(1) with ${x}_{t-1,3}$ as an input.

Specify the state-transition coefficient matrix. Use `NaN` values to indicate unknown parameters.

`A = [0 NaN NaN 0; 0 0 0 0; 0 0 0 NaN; 0 0 0 0];`

`B = [NaN 0; 1 0; 0 NaN; 0 1];`

Specify the measurement-sensitivity coefficient matrix.

`C = [1 0 0 0; 0 0 1 0];`

Specify the observation-innovation coefficient matrix.

`D = [NaN 0; 0 NaN];`

Use `ssm` to define the state-space model.

`Mdl = ssm(A,B,C,D)`
```Mdl = State-space model type: ssm State vector length: 4 Observation vector length: 2 State disturbance vector length: 2 Observation innovation vector length: 2 Sample size supported by model: Unlimited Unknown parameters for estimation: 7 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)x2(t-1) + (c2)x3(t-1) + (c4)u1(t) x2(t) = u1(t) x3(t) = (c3)x4(t-1) + (c5)u2(t) x4(t) = u2(t) Observation equations: y1(t) = x1(t) + (c6)e1(t) y2(t) = x3(t) + (c7)e2(t) Initial state distribution: Initial state means are not specified. Initial state covariance matrix is not specified. State types are not specified. ```

`Mdl` is an `ssm` model containing unknown parameters. A detailed summary of `Mdl` prints to the Command Window. It is good practice to verify that the state and observations equations are correct.

Pass `Mdl` and data to `estimate` to estimate the unknown parameters.

### Implicitly Create Time-Invariant State-Space Model

This example shows how to create a time-invariant state-space model by passing a parameter-mapping function describing the model to `ssm` (that is, implicitly create a state-space model). 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.

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

The software implicitly defines the state-space model. Usually, you cannot verify state-space models that you implicitly define.

`Mdl` is an `ssm` model object containing unknown parameters. You can estimate the unknown parameters by passing `Mdl` and response data to `estimate`.