Create Continuous State-Space Models for Economic Data Analysis

Econometrics Toolbox™ has a variety of Markovian, discrete-time, state-space models that you can use to analyze multivariate economic time series data. Its continuous state-space functionalities are best suited for economic time series modelling and analysis, but you can use them for other applications. If you have a specialized application, consider these implementations in other MathWorks^® products:

State-Space (Simulink)
Discrete State-Space (Simulink)
ss (Control System Toolbox)
idss (System Identification Toolbox)

For discrete state-space functionalities, which are best suited to model regime shifts, such as threshold- or Markov-switching models, see Regime-Switching Models.

Types of Models

The continuous state-space models in Econometrics Toolbox are dynamic systems that consist of the following types of stochastic equations:

State equations, x_t = f_t(x_t–1;Θ) — Describe how latent processes transition from times t – 1 to t, for t = 1 through T. The left-hand-side m_t-by-1 vector of m_t states x_t contains unique measurements, lags of other states allowing for lags greater than one on the right-hand side, or constants.
Observation (measurement) equations, y_t = g_t(x_t;Θ) — Describe how an observer measures the latent process at each time t. The left-hand-side y_t is an n_t-by-1 vector of n_t observations.

The parameters, state variables, or observation variables can be time invariant or time varying. For a time-varying model, the subscript t of f_t and g_t indicates the possibility of a change during the sample period when:

A parameter changes to a different parameter in Θ, which accommodates models with a structural change or seasonality.
The dimensions of x_t or y_t change, or what they represent changes.

Without the subscript, the model is time invariant—the parameters and variables are the same throughout the sample period.

Regardless of your application, a goal of state-space modeling is to estimate and analyze the latent states x_t and model parameters Θ. With Econometrics Toolbox you can model linear and nonlinear (with respect to parameters), Gaussian and non-Gaussian, and frequentist and Bayesian state-space models. The toolbox has these functions for creating an object that represents a state-space model.

Function	Description	State Equation	Observation Equation	Creation Method
`ssm`	Standard state-space model with finite initial state covariances	Linear model and additive Gaussian noise	Linear model and additive Gaussian noise	Explicit and implicit
`dssm`	Diffuse state-space model, standard state-space model that has at least one state with an infinite initial variance	Linear model and additive Gaussian noise	Linear model and additive Gaussian noise	Explicit and implicit
`bssm`	Bayesian linear state-space model	Linear model and additive Gaussian or Student's t noise	Linear model and additive noise with several distribution options. The supported distributions range in levels of skewness and kurtosis.	Only implicit
`bnlssm`	Bayesian nonlinear non-Gaussian state-space model	Nonlinear model and additive Gaussian noise	Custom distribution	Only implicit

Similar to other Econometrics Toolbox model objects, a state-space model object completely specifies the structure and stochastic properties of the model. The properties (accessible by using dot notation) correspond to the parameter values and model characteristics, either explicitly (where you directly specify coefficient matrices) or implicitly (where you write a function that describes the model and returns model parameters and characteristics). You must supply enough information for MATLAB^® to infer the values of structural parameters of the model, such as the state and observation dimensionalities. However, model coefficients and some error distribution parameters are estimable. If you plan to fit the model to data, you do not specify their values when you create a model object.

Basic Steps

To create a state-space model:

Decide on the model structure and assumptions for your problem.
If the model is time invariant and linear, express it in matrix form.
Choose the creation function for your problem.
In MATLAB, create the inputs that specify the state-space model structure and assumptions.
- Explicitly specify the model — If you can express the model in matrix form, create and specify each coefficient matrix. All coefficients are estimable. Set unknown coefficients that you want to fit to data to NaN. You can use optional name-value arguments to specify model characteristics, such as initial state distribution moments.
- Implicitly specify the model — Regardless of whether you can explicitly specify the model, you can write a custom function that accepts a vector of state-space model parameters Θ, describes the model structure by mapping the parameters to the coefficient matrices, and returns the matrices and model characteristics. All coefficients are estimable; MATLAB prepares variable elements in the output coefficients for estimation. Bayesian models support only implicit model specification.
- For a Bayesian model, specify the log prior distribution of the state-space model parameters π(Θ). Write a custom function that accepts a vector of state-space model parameters and returns the real scalar log prior distribution at the input parameters.
Create the model object representing your state-space model by passing the required structural inputs, and setting any optional inputs, to the appropriate creation function.

Decide on Model Structure

Before creating a state-space model object in MATLAB, you must decide the model structure and which assumptions apply to your problem. Specifically, you determine the following characteristics:

The latent variables x_t, their dynamic form, and stochastic properties.
How the latent variables combine to form the observations y_t, the stochastic properties of the observations, and whether the observations need to be deflated by exogenous predictors Z_t.
Whether the parametric form of the model varies with time, for example, if a state is introduced midway through sampling or the value of at least one parameter changes midway through sampling due to a structural change.
- In a time-invariant state-space model:
  - The coefficient matrices, more generally, model parameters, are constant throughout the sample.
  - The number of states, state disturbances, observations, and observation innovations are the same for all periods.
  For example, for all t, the following system of equations represents a time-invariant state-space model.
  
  $\begin{matrix} [\begin{matrix} x_{1, t} \\ x_{2, t} \end{matrix}] = [\begin{matrix} ϕ_{1} & 0 \\ 0 & ϕ_{2} \end{matrix}] [\begin{matrix} x_{1, t - 1} \\ x_{2, t - 1} \end{matrix}] + [\begin{matrix} 0.5 & 0 \\ 0 & 2 \end{matrix}] [\begin{matrix} u_{1, t} \\ u_{2, t} \end{matrix}] \\ y_{t} = [\begin{matrix} ϕ_{3} & 1 \end{matrix}] [\begin{matrix} x_{1, t} \\ x_{2, t} \end{matrix}] + 0.2 ε_{t} \end{matrix}$
- In a time-varying state-space model:
  - The coefficient matrices might change from period to period.
  - The number of states, state disturbances, observations, and observation innovations might change from period to period (a dimension-varying model). For example, one state drops out of the model or an observation becomes immeasurable during the sampling time frame.
  For an example of a time-varying model, suppose, for t = 1,..,10
  
  $\begin{matrix} [\begin{matrix} x_{1, t} \\ x_{2, t} \end{matrix}] = [\begin{matrix} ϕ_{1} & 0 \\ 0 & ϕ_{2} \end{matrix}] [\begin{matrix} x_{1, t - 1} \\ x_{2, t - 1} \end{matrix}] + [\begin{matrix} 0.5 & 0 \\ 0 & 2 \end{matrix}] [\begin{matrix} u_{1, t} \\ u_{2, t} \end{matrix}] \\ y_{t} = [\begin{matrix} ϕ_{3} & 1 \end{matrix}] [\begin{matrix} x_{1, t} \\ x_{2, t} \end{matrix}] + 0.2 ε_{t} \end{matrix},$
  for t = 11
  
  $\begin{matrix} x_{1, t} = [\begin{matrix} ϕ_{4} & 0 \end{matrix}] [\begin{matrix} x_{1, t - 1} \\ x_{2, t - 1} \end{matrix}] + 0.5 u_{1, t} \\ y_{t} = ϕ_{5} x_{1, t} + 0.2 ε_{t} \end{matrix},$
  and for t = 12,..,T
  
  $\begin{matrix} x_{1, t} = ϕ_{4} + 0.5 u_{1, t} \\ y_{t} = ϕ_{5} x_{1, t} + 0.2 ε_{t} \end{matrix} .$
  Three sets of state transition matrices are in the model, but the model contains only two sets of coefficient matrices.

Deciding on model structure is application dependent and can require separate analysis or iteration. Regardless, a best practice is to write the system so that all parameters are identifiable. A completely identifiable model is particularly important for a non-Bayesian problem.

For the model-creation workflow in this topic, consider the time-invariant, linear, Gaussian standard state-space model

$\begin{array}{l} w_{t} = a + ϕ w_{t - 1} + b u_{t} \\ y_{t} = w_{t} + d ε_{t} . \end{array}$

w_t is a latent time series variable, u_t and ε_t are mutually independent, iid standard Gaussian series, and y_t is a time series of measurements. All other variables are model parameters.

Express Model in Matrix Form

Expressing your state-space model in matrix form in MATLAB means that Econometrics Toolbox can operate on it using fewer function calls, which can speed up computations.

When your state-space model is time-invariant, linear, and Gaussian, you can express it in the following matrix form:

$\begin{array}{l} x_{t} = A x_{t - 1} + B u_{t} \\ y_{t} = C x_{t} + D ε_{t} . \end{array}$

The elements of the matrices A, B, C, and D are known constants or unknown state-space model parameters in Θ.

To write a model in matrix form, first group the parameters:

Θ_A — Factors of x_t–1, any constants in the state equation, and elements that facilitate moving average terms (lags of u_t)
Θ_B — Factors of u_t in the state equation
Θ_C — Factors of x_t
Θ_D — Factors of ε_t in the observation equation

Consider the example system

$\begin{array}{l} w_{t} = a + ϕ w_{t - 1} + b u_{t} \\ y_{t} = w_{t} + d ε_{t} . \end{array}$

In the system,

Θ = {a,ϕ,b,c,d}.
Θ_A = {a,ϕ}.
Θ_B = {b}.
Θ_C = {c}.
Θ_D = {d}.

Next, form the state equation coefficient matrices A and B. A is a linear map from x_{_t–1} to E(x_t|x_{_t–1}), with vectors x_t and x_{_t–1} consisting of the state variables of interest and abstract variables that facilitate other linear terms associated with Θ_A. Specifically, common elements of x_t include:

State variables of interest.
State variables that equal 1 for all t. Associate this state with constant parameters in the state equation.
Placeholders that facilitate including state or state disturbance variables with lags greater than 1.

Typically, B is the square root of the covariance of the state disturbances, with the vector u_t containing only state disturbance variables.

In the example system, x_t = [w_t v_t]′, where v_t = 1 for all t, is a placeholder associated with a. Although two states exist, v_t has no associated disturbance. Therefore, u_t is univariate and appears only in the equation of f_t.

Given the options for elements of x_t and u_t, write A and B as matrices that map x_t–1 and u_t to x_t. In the example system,

$A = [\begin{matrix} ϕ & a \\ 0 & 1 \end{matrix}]$

and

$B = [\begin{matrix} b \\ 0 \end{matrix}] .$

Rewriting the state equation in matrix form,

$\begin{matrix} [\begin{matrix} w_{t} \\ v_{t} \end{matrix}] = [\begin{matrix} ϕ & a \\ 0 & 1 \end{matrix}] [\begin{matrix} w_{t - 1} \\ v_{t - 1} \end{matrix}] + [\begin{matrix} b \\ 0 \end{matrix}] u_{t}, \\ = \begin{array}{l} ϕ w_{t - 1} + a v_{t - 1} + b u_{t} \\ v_{t - 1} \end{array} . \end{matrix}$

The second state equation, v_t = v_t–1, facilitates the creation of the constant term in the equation of w_t. When you create the model in MATLAB, you can specify characteristics of each state, such as which ones are stationary or equal one.

Consider a state that includes lags of state disturbances (moving average terms):

$w_{t} = a + ϕ w_{t - 1} + θ u_{t - 1} + u_{t} .$

The expanded state equation in matrix form for this example is

$[\begin{matrix} w_{t} \\ v_{1, t} \\ v_{2, t} \end{matrix}] = [\begin{matrix} ϕ & a & θ \\ 0 & 1 & 0 \\ 0 & 0 & 0 \end{matrix}] [\begin{matrix} w_{t - 1} \\ v_{1, t - 1} \\ v_{2, t - 1} \end{matrix}] + [\begin{matrix} b \\ 0 \\ 1 \end{matrix}] u_{t} .$

The placeholder variable v_2,t = u_t and the third term in the equation of w_t is θv_2,t–1 = θu_t–1.

After writing the state equation in matrix form, you write the observation equation in matrix form. The forms that C and D take are usually more straightforward than A and B because A and B specify the dynamics of the system, which can be more complex than how the system is measured or observed. Elements of C determine how the states x_t linearly combine to form possibly perturbed observations y_t, and elements of D specify the scale of the perturbations.

In the example system, the expanded observation equation is

$y_{t} = [\begin{matrix} c & 0 \end{matrix}] [\begin{matrix} w_{t} \\ v_{t} \end{matrix}] + d ε_{t} .$

Choose Appropriate Model

The structure of your state-space model and your assumptions suggest which creation function to use.

Standard State-Space Model

A standard state-space model, or a linear, Gaussian state-space model, is linear with respect to the model parameters Θ_t and it has additive, Gaussian state and measurement errors. The ssm function creates a standard state-space model object, ssm.

Symbolically, a standard state-space model, in its most general form, is the following system of equations. The system is time varying. For t = 1,...,T:

$\begin{array}{l} x_{t} = A_{t} x_{t - 1} + B_{t} u_{t} \\ y_{t} - {(Z_{t} β)}^{'} = C_{t} x_{t} + D_{t} ε_{t}, \end{array}$

where:

$x_{t} = [x_{1, t}, ..., x_{m_{t}, t}]'$ is an m_t-dimensional state vector describing the dynamics of some, possibly unobservable, phenomenon at period t. The initial state distribution (x₀) is Gaussian with mean μ₀ and covariance matrix Σ₀. Elements of x_t can represent lags of other elements or constants.
$y_{t} = [y_{1, t}, ..., y_{n_{t}, t}]'$ is an n_t-dimensional observation vector describing how the states are measured by observers at period t.
A_t is the m_t-by-m_{t
– 1} state-transition matrix describing how the states at time t transition to the states at period t – 1.
B_t is the m_t-by-k_t state-disturbance-loading matrix describing how the states at period t combine with the innovations at period t, with elements specifying the intensity of the noise.
C_t is the n_t-by-m_t measurement-sensitivity matrix describing how the observations at period t relate to the states at period t.
D_t is the n_t-by-h_t observation-innovation matrix describing how the observations at period t combine with the observation errors at period t, with elements specifying the intensity of the noise. If the combination of the states is observed without error, D_t = 0 for all t.
The matrices A_t, B_t, C_t, and D_t are coefficient matrices. Let θ_J be the set of all parameters in coefficient matrix J_t, J_t = {A_t,B_t,C_t,D_t} and t = 1,…,T. Θ = {θ_A, θ_B, θ_C, θ_D} is the collection of all parameters in the coefficient matrices. The matrices are estimable, that is, they can contain unknown parameters for fitting to data. Also, you can specify values for some or all of the elements for experimentation or constrained estimation. The subscript t indicates that the coefficient matrices are time varying; you can omit the subscript for simpler time-invariant coefficients or models.
$u_{t} = [u_{1, t}, ..., u_{k_{t}, t}]'$ is a k_t-dimensional, Gaussian, white-noise, unit-variance vector of state disturbances at period t.
$ε_{t} = [ε_{1, t}, ..., ε_{h_{t}, t}]'$ is an h_t-dimensional, Gaussian, white-noise, unit-variance vector of observation innovations at period t.
ε_t and u_t are uncorrelated.
For time-invariant models,
- $Z_{t} = [\begin{matrix} z_{t 1} & z_{t 2} & \dots & z_{t d} \end{matrix}]$ is row t of a T-by-d matrix of predictors Z. Each column of Z corresponds to a predictor, and each successive row to a successive period. If the observations are multivariate, all predictors deflate each observation.
- β is a d-by-n matrix of regression coefficients for Z_t.
Default initial state moments are as follows. You can adjust the defaults by setting the Mean0 and Cov0 properties when you create the model or by using dot notation.
- For stationary states (StateType property is 0), the initial means, variances, and covariances are finite, and the software infers them.
- For states that are the constant one for all periods (StateType property is 1), the initial state means are 1 and covariances are 0.
- For nonstationary states (StateType property is 2), the initial state means are 0 and initial state variance is 1e7.

Not expressed in the system are the m₁-by-1 initial state mean vector μ₀ and the m₁-by-m₁ initial state covariance matrix Σ₀. Although they are estimable for non-Bayesian models, typically, each are set to known constants (either by you or by defaults).

Diffuse State-Space Model

A diffuse state-space model is a standard state-space model that contains at least one state with an infinite initial variance (Inf), called a diffuse state. In addition to having an infinite initial variance, all diffuse states are uncorrelated with all other states in the model. The dssm function creates a diffuse state-space model object, dssm.

You can use a diffuse state-space model when:

Starting points of some nonstationary systems, such as random walk process, lead to initial distribution variances that approach infinity.
An infinite variance specification for an initial state distribution indicates complete ignorance, or no prior knowledge, of the diffuse states. The advantage of this specification is that the analysis of these states is more objective. In other words, the observations, rather than additional distribution assumptions, aid in understanding the diffuse states. The disadvantage is that posterior distributions of the states might be improper, and the likelihood function is unbounded. However, with enough data and an identifiable, Gaussian state-space model, the filtered and smoothed states, and a likelihood based on them, can be computed using the diffuse Kalman filter.
You want to represent a static, initial state as an unknown parameter by attributing to it an infinite variance.

Bayesian Linear State-Space Model

A Bayesian linear state-space model is a Bayesian view of the standard state-space model in which the vector of model parameters Θ are treated as random variables with a joint prior distribution Π(Θ) and a posterior distribution Π(Θ|y_t) composed of the joint prior and data likelihood computed by the standard Kalman filter. The bssm function creates a Bayesian linear state-space model object, bssm.

For filtering, smoothing, and parameter estimation, frequentist analyses rely on closed-form expectations and maximum likelihood estimation. Bayesian analyses typically require numerical integration by Markov chain Monte Carlo (MCMC) sampling. As a result, Bayesian models can be richer, allowing for more complexity, than standard frequentist models. Standard and Bayesian linear state-space models have these notable differences:

Difference	Standard State-Space Model	Bayesian State-Space Model
State disturbance series u_t distribution options	Only multivariate Gaussian	Multivariate Gaussian or Student's t
Observation innovation series ε_t distribution options	Only multivariate Gaussian	Linear observation innovation series ε_t can follow one of these distributions, specified by the `ObservationDistribution` name-value argument: `"Gaussian"` — Multivariate Gaussian `"t"` — Multivariate Student's t `"mixture"` — Univariate finite Gaussian mixture `"Laplace"` — Univariate Laplace `"skewnormal"` — Univariate skew normal
Θ	Vector of state-space model parameters treated as fixed and possibly unknown Estimated by maximum likelihood	Vector of state-space model parameters treated as a random vector with a prior distribution specified as a custom function Posterior distribution approximated by the Metropolis-Hasting MCMC sampler
Model specification	Explicit or implicit	Implicit only

Bayesian Nonlinear Non-Gaussian State-Space Model

Like a Bayesian linear state-space model, a Bayesian nonlinear non-Gaussian state-space model, or simply a Bayesian nonlinear model, takes a Bayesian view of the problem, but the state dynamical behavior is nonlinear and the observations follow a custom distribution. This form enables the model to capture complex nuances in the data or more closely match the sampling scheme. The bnlssm function creates a Bayesian nonlinear state-space model object, bnlssm.

In general, a linear, multivariate, time-varying, Gaussian state-space model can be one of these systems of equation, where A_t through D_t are possibly nonlinear functions:

Equation form — Observations have linear Gaussian error, explicitly

$\begin{array}{l} x_{t} = A_{t} (x_{t - 1}; θ_{A}) + B_{t} (θ_{B}) u_{t} \\ y_{t} = C_{t} (x_{t}; θ_{C}) + D_{t} (θ_{D}) ε_{t} . \end{array}$
Distribution form — Observations follow a custom distribution p(y_t|x_t;Θ,Z_t), explicitly

$\begin{array}{l} x_{t} = A_{t} (x_{t - 1}; Θ) + B_{t} (Θ) u_{t} \\ y_{t} ~ \log p (y_{t} | x_{t}; Θ, Z_{t}) . \end{array}$

Bayesian linear and nonlinear state-space models have these notable differences:

Difference Bayesian Linear State-Space Model Bayesian Nonlinear State-Space Models

Difference	Bayesian Linear State-Space Model	Bayesian Nonlinear State-Space Models
Mappings A_t and C_t	Linear, specified as coefficient matrices	For linear dynamics, specified as coefficient matrices or cell vectors of coefficient matrices For nonlinear dynamics, a function handle to a function that describes the nonlinear dynamics
State disturbance series u_t distribution options	Multivariate Gaussian or Student's t	Only multivariate Gaussian
Observation distribution options	Linear observation innovation series ε_t can follow one of these distributions, specified by the `ObservationDistribution` name-value argument: `"Gaussian"` — Multivariate Gaussian `"t"` — Multivariate Student's t `"mixture"` — Univariate finite Gaussian mixture `"Laplace"` — Univariate Laplace `"skewnormal"` — Univariate skew normal	The `ObservationForm` name-value argument specifies the form that the observation equation takes: `"equation"` (default) — Observations have linear Gaussian innovations, with measurement-sensitivity coefficient matrix or cell vectors of coefficient matrices. `"distribution"` — Observations have a custom distribution.

Mappings A_t and C_t

Linear, specified as coefficient matrices

For linear dynamics, specified as coefficient matrices or cell vectors of coefficient matrices
For nonlinear dynamics, a function handle to a function that describes the nonlinear dynamics

State disturbance series u_t distribution options Multivariate Gaussian or Student's t Only multivariate Gaussian

Observation distribution options

Linear observation innovation series ε_t can follow one of these distributions, specified by the ObservationDistribution name-value argument:

"Gaussian" — Multivariate Gaussian
"t" — Multivariate Student's t
"mixture" — Univariate finite Gaussian mixture
"Laplace" — Univariate Laplace
"skewnormal" — Univariate skew normal

The ObservationForm name-value argument specifies the form that the observation equation takes:

"equation" (default) — Observations have linear Gaussian innovations, with measurement-sensitivity coefficient matrix or cell vectors of coefficient matrices.
"distribution" — Observations have a custom distribution.

Create Structural Inputs and Model Object

After you choose a state-space model for your problem, create the inputs that specify its structure.

Create Standard State-Space Model

To represent a standard state-space model in MATLAB by using the ssm function, consider creating the model

$\begin{array}{l} w_{t} = a + ϕ w_{t - 1} + b u_{t} \\ y_{t} = w_{t} + d ε_{t} . \end{array}$

The model is partially specified, which means its structure is completely specified, but some parameters are unknown. (A fully specified model contains no unknown parameters.) You can express the model in matrix form

$\begin{array}{l} [\begin{matrix} w_{t} \\ v_{t} \end{matrix}] = [\begin{matrix} ϕ & a \\ 0 & 1 \end{matrix}] [\begin{matrix} w_{t - 1} \\ v_{t - 1} \end{matrix}] + [\begin{matrix} b \\ 0 \end{matrix}] u_{t} \\ y_{t} = [\begin{matrix} 1 & 0 \end{matrix}] [\begin{matrix} w_{t} \\ v_{t} \end{matrix}] + d ε_{t} . \end{array}$

Create a matrix for each coefficient matrix. Set elements that represent unknown parameters to NaN.

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

Pass the coefficient matrices to ssm. Specify that the first state variable is stationary (type 0) and the second state variable is the constant 1 (type 1).

stateType = [0; 1];
Mdl = ssm(A,B,C,D,StateType=stateType)

Mdl = 


State-space model type: ssm

State vector length: 2
Observation vector length: 1
State disturbance vector length: 1
Observation innovation vector length: 1
Sample size supported by model: Unlimited
Unknown parameters for estimation: 4

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) + (c2)x2(t-1) + (c3)u1(t)
x2(t) = x2(t-1)

Observation equation:
y1(t) = x1(t) + (c4)e1(t)

Initial state distribution:

Initial state means are not specified.
Initial state covariance matrix is not specified.
State types
     x1         x2    
 Stationary  Constant

The output describes the state-space model, including the model form, which you can use to verify whether you have specified the model correctly. The variables cn, where n is a natural number, represent unknown, estimable parameters.

Alternatively, you can specify the structure of a state-space model by using a custom parameter-to-matrix mapping function, regardless of whether the model can be expressed in matrix form. Using a custom function, you can create more complex models or reparameterize the model to enforce restrictions on the parameters. The function requires an input vector of parameters Θ with other optional inputs and outputs the coefficient matrices and other model characteristics. For more details, see ssm.

Create the following parameter-to-matrix mapping function, which specifies the structure of the example state-space model, and save it to your working directory or create it within a script. Restrict the error scales to be positive.

 function [A,B,C,D,Mean0,Cov0,StateType] = exampleStandardSSM(theta)
    phi = theta(1);
    a = theta(2);
    varU = exp(theta(3));
    b = sqrt(varU);
    varEPS = exp(theta(4));
    d = sqrt(varEPS);    
    A = [phi a; 0 1];
    B = [b; 0];
    C = [1 0];
    D = d;
    Mean0 = [];    % Defer to default
    Cov0 = [];     % Defer to default
    StateType = [0; 1];
end

Create the state-space model represented in the function by passing exampleStandardSSM as a function handle to ssm.

Mdl = ssm(@exampleStandardSSM)

Mdl = 
State-space model type: ssm
The state-space model is implicitly defined by the function:
    @exampleStandardSSM

At the time you create an implicitly specified model, MATLAB cannot determine its structure.

Create Diffuse State-Space Model

To represent a diffuse state-space model in MATLAB by using the dssm function, consider creating this fully specified and observed random walk with drift model

$\begin{array}{l} w_{t} = 2 + w_{t - 1} + 0.5 u_{t} \\ y_{t} = w_{t} . \end{array}$

Suppose Var(w₀) is infinite. You can express the model in matrix form

$\begin{array}{l} [\begin{matrix} w_{t} \\ v_{t} \end{matrix}] = [\begin{matrix} 1 & 2 \\ 0 & 1 \end{matrix}] [\begin{matrix} w_{t - 1} \\ v_{t - 1} \end{matrix}] + [\begin{matrix} 0.5 \\ 0 \end{matrix}] u_{t} \\ y_{t} = [\begin{matrix} 1 & 0 \end{matrix}] [\begin{matrix} w_{t} \\ v_{t} \end{matrix}] . \end{array}$

Create a matrix for each coefficient matrix.

A = [1 2; 0 1];
B = [0.5; 0];
C = [1 0];
D = 0;

Pass the coefficient matrices to dssm. Specify that the first state variable is stationary (type 0) and the second state variable is the constant 1 (type 1).

stateType = [0; 1];
Mdl = dssm(A,B,C,D,StateType=stateType)

Mdl = 


State-space model type: dssm

State vector length: 2
Observation vector length: 1
State disturbance vector length: 1
Observation innovation vector length: 1
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = x1(t-1) + (2)x2(t-1) + (0.50)u1(t)
x2(t) = x2(t-1)

Observation equation:
y1(t) = x1(t)

Initial state distribution:

Initial state means
 x1  x2 
  0   1 

Initial state covariance matrix
     x1   x2 
 x1  Inf   0 
 x2  0     0 

State types
     x1         x2    
 Stationary  Constant

The output indicates that all parameters are known and the initial variance of w_t is infinite.

Create Bayesian Linear State-Space Model

To represent a Bayesian linear state-space model in MATLAB by using the bssm function, consider creating the model

$\begin{array}{l} w_{t} = a + ϕ w_{t - 1} + b u_{t} \\ y_{t} = w_{t} + d ε_{t} . \end{array}$

Despite the fact that you can write the model in matrix form, you must implicitly specify a Bayesian model by describing its structure in a custom parameter-to-matrix mapping function.

Create the following parameter-to-matrix mapping function, which specifies the structure of the example state-space model, and save it to your working directory or write the function in your script. For details on how to write a parameter-to-matrix mapping function, see bssm.

 function [A,B,C,D,Mean0,Cov0,StateType] = exampleBayesianSSM(theta)
    phi = theta(1);
    a = theta(2);
    b = theta(3);
    d = theta(4);    
    A = [phi a; 0 1];
    B = [b; 0];
    C = [1 0];
    D = d;
    Mean0 = [];    % Defer to default
    Cov0 = [];     % Defer to default
    StateType = [0; 1];
end

Although you can write the function exampleBayesianSSM to impose constraints on parameters, you can impose constraints in the log prior distribution function more easily.

Assuming the prior distribution π(Θ) is flat, create the log prior distribution function representing log π(Θ). Include the following parameter constraints by setting the probability outside the boundary to 0 (or –Inf for the log probability):

ϕ is in the unit circle (that is, enforce a stationary AR(1) state).
Error standard deviations b > 0 and d > 0.

function logprior = exampleFlatPriorBSSM(theta)
    phigte1 = theta(1) >= 1;
    nonposb = theta(3) <= 0;
    nonposd = theta(4) <= 0;
    
    paramconstraints = [phigte1 nonposb nonposd];
    if sum(paramconstraints) > 0
        logprior = -Inf;
    else
        logprior = 0;   % Prior density is proportional to 1 
                        % for all values in the parameter space.
    end
end

Create the Bayesian linear state-space model represented in the functions by passing the functions as function handles to bssm.

Mdl = bssm(@exampleBayesianSSM,@exampleFlatPriorBSSM)

Mdl = 
Mapping that defines a state-space model:
    @exampleBayesianSSM

Log density of parameter prior distribution:
    @exampleFlatPriorBSSM

Create Bayesian Nonlinear Non-Gaussian State-Space Model

To represent a Bayesian nonlinear, non-Gaussian state-space model in MATLAB by using the bnlssm function, consider a state-space model that has these characteristics:

The state equation has two independent, nonstationary states.
The states combine to form the probability of success for a series of Bernoulli observations.
The two states contain white Gaussian noise.
The prior distribution of the parameters is flat.

Symbolically, the system of equations, in distribution form, is

$\begin{array}{l} [\begin{matrix} x_{1, t} \\ x_{2, t} \end{matrix}] = [\begin{matrix} θ_{1} & 0 \\ 0 & θ_{2} \end{matrix}] [\begin{matrix} x_{1, t - 1} \\ x_{2, t - 1} \end{matrix}] + [\begin{matrix} θ_{3} & 0 \\ 0 & θ_{4} \end{matrix}] [\begin{matrix} u_{1, t} \\ u_{2, t} \end{matrix}] \\ y_{t} ~ p (y_{t}; x_{t}) = \frac{\exp (x_{1, t})}{\exp (x_{1, t}) + \exp (x_{2, t})} . \end{array}$

Implicitly specify the model by describing its structure in a custom parameter-to-matrix mapping function. Save the function to your working directory or write the function in your script. Because the equation is in distribution form, return the log of the joint observation density log p(y_t;x_t). For details on how to write a parameter-to-matrix mapping function, see bnlssm.

function [A,B,LogY,Mean0,Cov0,StateType] = exampleBayesianNLSSM(theta)
    A = [theta(1) 0; 0 theta(2)]; 
    B = [theta(3) 0; 0 theta(4)];
    LogY = @(y,x)sum(log(binopdf(y,1,exp(x(1))/(exp(x(2))+exp(x(1))))));
    Mean0 = [0.5; 0.5];
    Cov0 = eye(2);
    StateType = [2; 2];     % Nonstationary state processes
end

Assuming the prior distribution π(Θ) is flat, create the log prior distribution function representing log π(Θ). Constrain the error standard deviations θ₃ > 0 and θ₄ > 0 by setting the prior probability outside the boundary to 0 (or –Inf for the log probability).

function logprior = exampleFlatPriorBNLSSM(theta)
    paramconstraints = (theta(3:4) <= 0);
    if(sum(paramconstraints))
        logprior = -Inf;
    else 
        logprior = 0;   % Prior density is proportional to 1 
                        % for all values in the parameter space.
    end
end

Create the Bayesian nonlinear non-Gaussian state-space model represented in the functions by passing the functions as function handles to bnlssm. Specify that the observation equation is in distribution form.

Mdl = bnlssm(@exampleBayesianNLSSM,@exampleFlatPriorBNLSSM, ...
    ObservationForm="distribution")

Mdl = 

  bnlssm with properties:

             ParamMap: @exampleBayesianNLSSM
    ParamDistribution: @exampleFlatPriorBNLSSM
      ObservationForm: "distribution"
           Multipoint: [1×0 string]

References

[1] Durbin J., and S. J. Koopman. Time Series Analysis by State Space Methods. 2nd ed. Oxford: Oxford University Press, 2012.