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.

MdlBSSM = ssm2bssm(MdlSSM) converts the input standard, linear state-space model, an ssm object with unknown parameters, to a Bayesian state-space model, 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 input state-space model parameters.

example

Examples

collapse all

Convert Standard State-Space Model to Bayesian

Open Live Script

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

$[\begin{array}{cccccccccccccccccccc} x_{t, 1} \\ x_{t, 2} \end{array}] = [\begin{array}{cccccccccccccccccccc} ϕ_{1} & 0 \\ 0 & ϕ_{2} \end{array}] [\begin{array}{cccccccccccccccccccc} x_{t - 1, 1} \\ x_{t - 1, 2} \end{array}] + [\begin{array}{cccccccccccccccccccc} σ_{1} & 0 \\ 0 & σ_{2} \end{array}] [\begin{array}{cccccccccccccccccccc} u_{t, 1} \\ u_{t, 2} \end{array}]$

$y_{t} = [\begin{array}{cccccccccccccccccccc} 1 & 1 \end{array}] [\begin{array}{cccccccccccccccccccc} x_{t, 1} \\ x_{t, 2} \end{array}] + σ_{3} ε_{t} .$

Define the state-transition matrix.

A = [NaN 0; 0 NaN];

Define the state-disturbance-loading matrix.

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.

Specify Joint Prior Distribution

Open Live Script

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 cj, 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:

$| ϕ_{1} | < 1$ .
$| ϕ_{2} | < 1$ .
$σ_{1} > 0$ .
$σ_{2} > 0$ .
$σ_{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

`MdlSSM` — Standard, linear state-space model
`ssm` object

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.

`ParamDistribution` — Log of joint probability density function of the state-space model parameters Π(θ)
`@(x)0` (default) | function handle

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

`MdlBSSM` — Bayesian state-space model
`bssm` object

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 x_1,t.
- theta(2) is c2, the lag 2 AR coefficient of state variable x_1,t.
- theta(3) is c3, the standard deviation of state disturbance u_1,t.
- theta(4) is c4, the standard deviation of observation innovation ε_1,t.

Version History

Introduced in R2022a

ssm2bssm

Syntax

Description

Examples

Convert Standard State-Space Model to Bayesian

Specify Joint Prior Distribution

Input Arguments

MdlSSM — Standard, linear state-space model ssm object

ParamDistribution — Log of joint probability density function of the state-space model parameters Π(θ) @(x)0 (default) | function handle

Output Arguments

MdlBSSM — Bayesian state-space model bssm object

Tips

Version History

See Also

`MdlSSM` — Standard, linear state-space model
`ssm` object

`ParamDistribution` — Log of joint probability density function of the state-space model parameters Π(θ)
`@(x)0` (default) | function handle

`MdlBSSM` — Bayesian state-space model
`bssm` object