# bssm

Create Bayesian state-space model

## Description

`bssm`

creates a `bssm`

object, representing a Bayesian linear state-space model,
from a specified parameter-to-matrix mapping function, which defines the state-space model
structure, and the log prior distribution function of the parameters. The state-space model
can be time-invariant or time-varying, and the state or
observation variables, *x _{t}* or

*y*, respectively, can be multivariate series. State disturbances and observation innovations are Gaussian or Student's

_{t}*t*random variables.

In general, a `bssm`

object specifies the joint prior distribution and
characteristics of the state-space model only. That is, the model object is a template
intended for further use. Specifically, to incorporate data into the model for posterior
distribution analysis, pass the model object and data to the appropriate object function.

Alternatively, the `ssm`

object provides an alternative to the Bayesian
view of state-space models. In addition to the wide range of state-space model operations that
the `ssm`

object offers, you can use `ssm2bssm`

to switch
to a Bayesian view of a standard linear state-space model by converting a specified
`ssm`

object to a `bssm`

object equivalent. 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.

## Creation

### Syntax

### Description

There are several ways to create a `bssm`

object representing a Bayesian
state-space model:

**Create Prior Model**— Directly create a`bssm`

object, representing a prior model, by using the`bssm`

function and specifying the parameter-to-matrix mapping function and log prior distribution function of the parameters. This method accommodates simple through complex state-space model structures. For more details, see the following syntax.**Convert Standard Model to Bayesian Prior Model**— Convert a specified standard, linear state-space model, an`ssm`

object, to a`bssm`

object by passing the model to the`ssm2bssm`

function. The converted Bayesian model has the same state-space structure as the standard model. Use this method for simple state-space models when you prefer to specify the coefficient matrices explicitly. You can optionally specify the log prior density of the parameters. For details, see`ssm2bssm`

and`ssm`

.**Estimate Posterior Model**— Pass a`bssm`

object representing a prior model, observed response data, and initial parameter values to the`estimate`

function to obtain a`bssm`

object representing a posterior model. For more details, see`estimate`

.

creates the Bayesian state-space model
object `PriorMdl`

= bssm(`ParamMap`

,`ParamDistribution`

)`PriorMdl`

, representing a prior model with Gaussian state
disturbances and observation innovations, using the parameter-to-matrix mapping function
`ParamMap`

, which you write, and the log prior distribution of the
parameters.

The `ParamMap`

function maps the collection of linear state-space
model parameters Θ to the time-invariant or time-varying coefficient matrices
*A*, *B*, *C*, and
*D*. In addition to the coefficient matrices,
`ParamMap`

can optionally map any of the following quantities:

Initial state means and covariances

`Mean0`

and`Cov0`

State types

`StateType`

Deflated observation data

`DeflatedData`

to accommodate a regression component in the observation equation

The `ParamDistribution`

function accepts Θ and returns the
corresponding log density.

`PriorMdl`

is a template that specifies the joint prior distribution
of Θ and the structure of the state-space model.

sets properties
representing the distributions of the state disturbances and observation innovations using
name-value arguments. For example,
`PriorMdl`

= bssm(`ParamMap`

,`ParamDistribution`

,`Name=Value`

)`bssm(ParamMap,ParamDistribution,ObservationDistribution=struct("Name","t","DoF",6))`

specifies *t* distribution with 6 degrees of freedom for all observation
innovation variables *u _{t}* in the Bayesian
state-space model.

### Input Arguments

## Properties

## Object Functions

## Examples

## More About

## Tips

Load the data to the MATLAB workspace before creating the model.

Create the parameter-to-matrix mapping function and log prior distribution function each as their own file.

## Algorithms

For each state variable

, default values of`j`

`Mean0`

and`Cov0`

depend on`StateType(`

:)`j`

If

`StateType(`

(stationary state),) = 0`j`

`bssm`

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

generates the initial values. Otherwise, the software generates the initial values during estimation.If

`StateType(`

(constant state),) = 1`j`

`Mean0(`

is)`j`

`1`

and`Cov0(`

is)`j`

`0`

.If

`StateType(`

(nonstationary or diffuse state),) = 2`j`

`Mean0(`

is 0 and)`j`

`Cov0(`

is)`j`

`1e7`

.

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 the

`StateType`

of static states to`2`

. Consequently, the software treats static states as nonstationary and assigns the static state a diffuse initial distribution.`bssm`

models do not store observed responses or predictor data. Supply the data wherever necessary using the appropriate input or name-value pair arguments.`DeflateY`

is the deflated-observation data, which accommodates a regression component in the observation equation. For example, in this function, which has a linear regression component,`Y`

is the vector of observed responses and`Z`

is the vector of predictor data.function [A,B,C,D,Mean0,Cov0,StateType,DeflateY] =

*ParamFun*(theta,Y,Z) ... DeflateY = Y - params(9) - params(10)*Z; ... end

## References

## Version History

**Introduced in R2022a**