# ssm2bssm

Convert standard state-space model to Bayesian state-space model

Since R2022a

## Syntax

``MdlBSSM = ssm2bssm(MdlSSM)``
``MdlBSSM = ssm2bssm(MdlSSM,ParamDistribution)``

## Description

The `ssm2bssm` function converts a specified standard, linear state-space model (`ssm` object) to a Bayesian state-space model (`bssm` object) specifying the state-space model structure (likelihood) and the joint prior distribution of the parameters θ. Both models have the same state-space structure and use the Kalman filter, but parameter estimation and analysis of the standard model involves maximum likelihood and associated results, while the Bayesian model involves posterior sampling.

Because the `ssm` function enables you to create a standard linear state-space model by explicitly specifying coefficient matrices, standard-to-Bayesian model conversion can be convenient for simpler state-space models. For moderate through complex models, create a Bayesian state-space model directly by using the `bssm` function.

example

````MdlBSSM = ssm2bssm(MdlSSM)` converts the standard, linear state-space model `MdlSSM`, an `ssm` object with unknown parameters, to a Bayesian state-space model `MdlBSSM`, a `bssm` object. Both models have the same state-space structure. The joint prior density Π(θ), which is stored in `MdlBSSM.ParamDistribution`, is proportional to 1.```

example

````MdlBSSM = ssm2bssm(MdlSSM,ParamDistribution)` specifies Π(θ), the log joint prior density function of the state-space model parameters `ParamDistribution`.```

## Examples

collapse all

Create a standard state-space model containing two independent, autoregressive states, where the observations are the sum of the two states plus Gaussian error. Then, convert the model to a Bayesian model.

Symbolically, the equation is

`$\left[\begin{array}{c}{x}_{t,1}\\ {x}_{t,2}\end{array}\right]=\left[\begin{array}{cc}{\varphi }_{1}& 0\\ 0& {\varphi }_{2}\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 = [NaN 0; 0 NaN];`

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

Define the measurement-sensitivity matrix.

`C = [1 1];`

Define the observation-innovation matrix.

`D = NaN;`

Create the state-space model by using `ssm`. Specify that the states are stationary by using the `StateType` name-value argument.

`MdlSSM = ssm(A,B,C,D,StateType=[0 0])`
```MdlSSM = State-space model type: ssm 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: 5 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) + (c3)u1(t) x2(t) = (c2)x2(t-1) + (c4)u2(t) Observation equation: y1(t) = x1(t) + x2(t) + (c5)e1(t) Initial state distribution: Initial state means are not specified. Initial state covariance matrix is not specified. State types x1 x2 Stationary Stationary ```

`MdlSSM` is an `ssm` model containing five unknown parameters. A detailed summary of `Mdl` prints to the command line.

Convert the standard state-space model to a Bayesian model.

`MdlBSSM = ssm2bssm(MdlSSM)`
```MdlBSSM = Mapping that defines a state-space model: @(params)ParamMap2(params,MdlSSM) Log density of parameter prior distribution: @(x)0 ```

`MdlBSSM` is a `bssm` model object. The property `MdlBSSM.ParamMap` contains a function handle that specifies the state-space model structure (the same structure as in `MdlSSM`). The property `MdlBSSM.ParamDistribution` contains a function handle that specifies the joint prior density of the model parameters. In this case, the prior is proportional to 1 everywhere, which is not appropriate for this model because, for example, `c3`, `c4`, and `c5` must be positive, but the prior assigns positive probabilities for nonpositive values.

Create the standard state-space model in Convert Standard State-Space Model to Bayesian. Then, convert the model to a Bayesian model with a flat prior on the parameters.

Define the coefficient matrices.

```A = [NaN 0; 0 NaN]; B = [NaN 0; 0 NaN]; C = [1 1]; D = NaN;```

Create the state-space model by using `ssm`. Specify that the states are stationary by using the `StateType` name-value argument.

`MdlSSM = ssm(A,B,C,D,StateType=[0 0])`
```MdlSSM = State-space model type: ssm 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: 5 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) + (c3)u1(t) x2(t) = (c2)x2(t-1) + (c4)u2(t) Observation equation: y1(t) = x1(t) + x2(t) + (c5)e1(t) Initial state distribution: Initial state means are not specified. Initial state covariance matrix is not specified. State types x1 x2 Stationary Stationary ```

In the detailed summary of `Mdl`, observe the order of the parameter labels `c``j`, where `j` = 1, ..., 5.

Convert the standard state-space model to a Bayesian model. Specify a handle to the function `flatPriorSSM2BSSM`, which is in Local Functions and has input `theta` whose elements follow the order of the parameters in the display. The function defines a flat prior over the support of the distribution. In other words, the function sets all probabilites outside the following constraints to `-Inf`:

• $|{\varphi }_{1}|<1$.

• $|{\varphi }_{2}|<1$.

• ${\sigma }_{1}>0$.

• ${\sigma }_{2}>0$.

• ${\sigma }_{3}>0$.

`MdlBSSM = ssm2bssm(MdlSSM,@flatPriorSSM2BSSM)`
```MdlBSSM = Mapping that defines a state-space model: @(params)ParamMap2(params,MdlSSM) Log density of parameter prior distribution: @flatPriorSSM2BSSM ```

Local Functions

This example uses the `flatPriorSSM2BSSM` function, which is the log prior distribution of the parameters.

```function logprior = flatPriorSSM2BSSM(theta) paramconstraints = [(abs(theta(1)) >= 1) (abs(theta(2)) >= 1) ... (theta(3) < 0) (theta(4) < 0) (theta(5) < 0)]; if(sum(paramconstraints)) logprior = -Inf; else logprior = 0; end end```

## Input Arguments

collapse all

Standard, linear state-space model, specified as an `ssm` object returned by `ssm`.

Note

The `ssm2bssm` converter is best suited for converting explicitly created, simple state-space models. For moderate through complex models, particularly implicitly created models where a parameter-to-matrix mapping function specifies the state-space, create a Bayesian model directly by using the `bssm` function.

Log of joint probability density function of the state-space model parameters Π(θ), specified as a function handle in the form `@fcnName`, where `fcnName` is the function name. `ParamDistribution` sets the `ParamDistribution` property of `MdlBSSM`.

Suppose `logPrior` is the name of the MATLAB® function defining the joint prior distribution of θ. Then, `logPrior` must have this form.

```function logpdf = logPrior(theta,...otherInputs...) ... end```
where:

• `theta` is a `numParams`-by-1 numeric vector of the linear state-space model parameters θ. Elements of `theta` must correspond to the unknown parameters of `MdlSSM` (see Tips). The function can accept other inputs in subsequent positions.

• `logpdf` is a numeric scalar representing the log of the joint probability density of θ at the input `theta`.

If `ParamDistribution` requires the input parameter vector argument only, you can create the `bssm` object by calling:

`MdlBSSM = ssm2bssm(MdlSSM,@logPrior)`

In general, create the `bssm` object by calling:

`MdlBSSM = ssm2bssm(MdlSSM,@(theta)logPrior(theta,...otherInputArgs...))`

The default `@(x)0` indicates a joint prior density that is proportional to 1 everywhere.

Tip

• The default joint prior is not necessarily a proper density. Consider specifying a proper prior instead.

• Because out-of-bounds prior density evaluation is 0, set the log prior density of out-of-bounds parameter arguments to `-Inf`.

Data Types: `function_handle`

## Output Arguments

collapse all

Bayesian state-space model, returned as a `bssm` object. `MdlBSSM` completely specifies the state-space model structure (likelihood) and joint prior distribution.

## Tips

• To determine the order of the parameters for the first input argument `theta` of the log joint prior density function `ParamDistribution`, display the standard state-space model `MdlSSM` at the command line. MATLAB labels the parameters `cj` under the `State equations` and `Observation equations` headings, where `j` is the index of the parameter in the vector `theta`.

For example, consider the following display of the standard state-space model `MdlSSM`.

```MdlSSM = State-space model type: ssm [ ... ] State equations: x1(t) = (c1)x1(t-1) + (c2)x2(t-1) + (c3)u1(t) x2(t) = x1(t-1) Observation equation: y1(t) = x1(t) + (c4)e1(t) [...]```
In this case, `theta` is a 4-by-1 vector, where:

• `theta(1)` is `c1`, the lag 1 AR coefficient of state variable x1,t.

• `theta(2)` is `c2`, the lag 2 AR coefficient of state variable x1,t.

• `theta(3)` is `c3`, the standard deviation of state disturbance u1,t.

• `theta(4)` is `c4`, the standard deviation of observation innovation ε1,t.

## Version History

Introduced in R2022a