Create Continuous StateSpace Models for Economic Data Analysis
Econometrics Toolbox™ has a variety of Markovian, discretetime, statespace models that you can use to analyze multivariate economic time series data. Its continuous statespace 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:
StateSpace (Simulink)
Discrete StateSpace (Simulink)
ss
(Control System Toolbox)idss
(System Identification Toolbox)
For discrete statespace functionalities, which are best suited to model regime shifts, such as threshold or Markovswitching models, see RegimeSwitching Models.
Types of Models
The continuous statespace 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 lefthandside m_{t}by1 vector of m_{t} states x_{t} contains unique measurements, lags of other states allowing for lags greater than one on the righthand 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 lefthandside y_{t} is an n_{t}by1 vector of n_{t} observations.
The parameters, state variables, or observation variables can be time invariant or time varying. For a timevarying 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 statespace 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 nonGaussian, and frequentist and Bayesian statespace models. The toolbox has these functions for creating an object that represents a statespace model.
Function  Description  State Equation  Observation Equation  Creation Method 

ssm  Standard statespace model with finite initial state covariances  Linear model and additive Gaussian noise  Linear model and additive Gaussian noise  Explicit and implicit 
dssm  Diffuse statespace model, standard statespace 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 statespace 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 nonGaussian statespace model  Nonlinear model and additive Gaussian noise  Custom distribution  Only implicit 
Similar to other Econometrics Toolbox model objects, a statespace 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 statespace 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 statespace 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 namevalue 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 statespace 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 statespace model parameters π(Θ). Write a custom function that accepts a vector of statespace model parameters and returns the real scalar log prior distribution at the input parameters.
Create the model object representing your statespace model by passing the required structural inputs, and setting any optional inputs, to the appropriate creation function.
Decide on Model Structure
Before creating a statespace 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 timeinvariant statespace 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 timeinvariant statespace model.
$$\begin{array}{c}\left[\begin{array}{c}{x}_{1,t}\\ {x}_{2,t}\end{array}\right]=\left[\begin{array}{cc}{\varphi}_{1}& 0\\ 0& {\varphi}_{2}\end{array}\right]\left[\begin{array}{c}{x}_{1,t1}\\ {x}_{2,t1}\end{array}\right]+\left[\begin{array}{cc}0.5& 0\\ 0& 2\end{array}\right]\left[\begin{array}{c}{u}_{1,t}\\ {u}_{2,t}\end{array}\right]\\ {y}_{t}=\left[\begin{array}{cc}{\varphi}_{3}& 1\end{array}\right]\left[\begin{array}{c}{x}_{1,t}\\ {x}_{2,t}\end{array}\right]+0.2{\epsilon}_{t}\end{array}$$
In a timevarying statespace 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 dimensionvarying 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 timevarying model, suppose, for t = 1,..,10
$$\begin{array}{c}\left[\begin{array}{c}{x}_{1,t}\\ {x}_{2,t}\end{array}\right]=\left[\begin{array}{cc}{\varphi}_{1}& 0\\ 0& {\varphi}_{2}\end{array}\right]\left[\begin{array}{c}{x}_{1,t1}\\ {x}_{2,t1}\end{array}\right]+\left[\begin{array}{cc}0.5& 0\\ 0& 2\end{array}\right]\left[\begin{array}{c}{u}_{1,t}\\ {u}_{2,t}\end{array}\right]\\ {y}_{t}=\left[\begin{array}{cc}{\varphi}_{3}& 1\end{array}\right]\left[\begin{array}{c}{x}_{1,t}\\ {x}_{2,t}\end{array}\right]+0.2{\epsilon}_{t}\end{array},$$
for t = 11
$$\begin{array}{c}{x}_{1,t}=\left[\begin{array}{cc}{\varphi}_{4}& 0\end{array}\right]\left[\begin{array}{c}{x}_{1,t1}\\ {x}_{2,t1}\end{array}\right]+0.5{u}_{1,t}\\ {y}_{t}={\varphi}_{5}{x}_{1,t}+0.2{\epsilon}_{t}\end{array},$$
and for t = 12,..,T
$$\begin{array}{c}{x}_{1,t}={\varphi}_{4}+0.5{u}_{1,t}\\ {y}_{t}={\varphi}_{5}{x}_{1,t}+0.2{\epsilon}_{t}\end{array}.$$
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 nonBayesian problem.
For the modelcreation workflow in this topic, consider the timeinvariant, linear, Gaussian standard statespace model
$$\begin{array}{l}{w}_{t}=a+\varphi {w}_{t1}+b{u}_{t}\\ {y}_{t}={w}_{t}+d{\epsilon}_{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 statespace 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 statespace model is timeinvariant, linear, and Gaussian, you can express it in the following matrix form:
$$\begin{array}{l}{x}_{t}=A{x}_{t1}+B{u}_{t}\\ {y}_{t}=C{x}_{t}+D{\epsilon}_{t}.\end{array}$$
The elements of the matrices A, B, C, and D are known constants or unknown statespace 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+\varphi {w}_{t1}+b{u}_{t}\\ {y}_{t}={w}_{t}+d{\epsilon}_{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=\left[\begin{array}{cc}\varphi & a\\ 0& 1\end{array}\right]$$
and
$$B=\left[\begin{array}{c}b\\ 0\end{array}\right].$$
Rewriting the state equation in matrix form,
$$\begin{array}{c}\left[\begin{array}{c}{w}_{t}\\ {v}_{t}\end{array}\right]=\left[\begin{array}{cc}\varphi & a\\ 0& 1\end{array}\right]\left[\begin{array}{c}{w}_{t1}\\ {v}_{t1}\end{array}\right]+\left[\begin{array}{c}b\\ 0\end{array}\right]{u}_{t},\\ =\begin{array}{l}\varphi {w}_{t1}+a{v}_{t1}+b{u}_{t}\hfill \\ {v}_{t1}\hfill \end{array}.\end{array}$$
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+\varphi {w}_{t1}+\theta {u}_{t1}+{u}_{t}.$$
The expanded state equation in matrix form for this example is
$$\left[\begin{array}{c}{w}_{t}\\ {v}_{1,t}\\ {v}_{2,t}\end{array}\right]=\left[\begin{array}{ccc}\varphi & a& \theta \\ 0& 1& 0\\ 0& 0& 0\end{array}\right]\left[\begin{array}{c}{w}_{t1}\\ {v}_{1,t1}\\ {v}_{2,t1}\end{array}\right]+\left[\begin{array}{c}b\\ 0\\ 1\end{array}\right]{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}=\left[\begin{array}{cc}c& 0\end{array}\right]\left[\begin{array}{c}{w}_{t}\\ {v}_{t}\end{array}\right]+d{\epsilon}_{t}.$$
Choose Appropriate Model
The structure of your statespace model and your assumptions suggest which creation function to use.
Standard StateSpace Model
A standard statespace model, or a linear,
Gaussian statespace 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
statespace model object, ssm
.
Symbolically, a standard statespace 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}_{t1}+{B}_{t}{u}_{t}\\ {y}_{t}{\left({Z}_{t}\beta \right)}^{\prime}={C}_{t}{x}_{t}+{D}_{t}{\epsilon}_{t},\end{array}$$
where:
$${x}_{t}=\left[{x}_{1,t},\mathrm{...},{x}_{{m}_{t},t}\right]\prime $$ is an m_{t}dimensional state vector describing the dynamics of some, possibly unobservable, phenomenon at period t. The initial state distribution (x_{0}) is Gaussian with mean μ_{0} and covariance matrix Σ_{0}. Elements of x_{t} can represent lags of other elements or constants.
$${y}_{t}=\left[{y}_{1,t},\mathrm{...},{y}_{{n}_{t},t}\right]\prime $$ is an n_{t}dimensional observation vector describing how the states are measured by observers at period t.
A_{t} is the m_{t}bym_{t – 1} statetransition matrix describing how the states at time t transition to the states at period t – 1.
B_{t} is the m_{t}byk_{t} statedisturbanceloading 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}bym_{t} measurementsensitivity matrix describing how the observations at period t relate to the states at period t.
D_{t} is the n_{t}byh_{t} observationinnovation 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 timeinvariant coefficients or models.
$${u}_{t}=\left[{u}_{1,t},\mathrm{...},{u}_{{k}_{t},t}\right]\prime $$ is a k_{t}dimensional, Gaussian, whitenoise, unitvariance vector of state disturbances at period t.
$${\epsilon}_{t}=\left[{\epsilon}_{1,t},\mathrm{...},{\epsilon}_{{h}_{t},t}\right]\prime $$ is an h_{t}dimensional, Gaussian, whitenoise, unitvariance vector of observation innovations at period t.
ε_{t} and u_{t} are uncorrelated.
For timeinvariant models,
$${Z}_{t}=\left[\begin{array}{cccc}{z}_{t1}& {z}_{t2}& \cdots & {z}_{td}\end{array}\right]$$ is row t of a Tbyd 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 dbyn matrix of regression coefficients for Z_{t}.
Default initial state moments are as follows. You can adjust the defaults by setting the
Mean0
andCov0
properties when you create the model or by using dot notation.For stationary states (
StateType
property is0
), 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 is1
), the initial state means are 1 and covariances are 0.For nonstationary states (
StateType
property is2
), the initial state means are 0 and initial state variance is1e7
.
Not expressed in the system are the m_{1}by1 initial state mean vector μ_{0} and the m_{1}bym_{1} initial state covariance matrix Σ_{0}. Although they are estimable for nonBayesian models, typically, each are set to known constants (either by you or by defaults).
Diffuse StateSpace Model
A diffuse statespace model is a standard statespace
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
statespace model object, dssm
.
You can use a diffuse statespace 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 statespace 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 StateSpace Model
A Bayesian linear statespace model is
a Bayesian view of the standard statespace 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 statespace model object,
bssm
.
For filtering, smoothing, and parameter estimation, frequentist analyses rely on closedform 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 statespace models have these notable differences:
Difference  Standard StateSpace Model  Bayesian StateSpace 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

Θ 


Model specification  Explicit or implicit  Implicit only 
Bayesian Nonlinear NonGaussian StateSpace Model
Like a Bayesian linear statespace model, a
Bayesian nonlinear nonGaussian statespace 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 statespace model object,
bnlssm
.
In general, a linear, multivariate, timevarying, Gaussian statespace 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}\left({x}_{t1};{\theta}_{A}\right)+{B}_{t}\left({\theta}_{B}\right){u}_{t}\\ {y}_{t}={C}_{t}\left({x}_{t};{\theta}_{C}\right)+{D}_{t}\left({\theta}_{D}\right){\epsilon}_{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}\left({x}_{t1};\Theta \right)+{B}_{t}\left(\Theta \right){u}_{t}\\ {y}_{t}~\mathrm{log}p\left({y}_{t}{x}_{t};\Theta ,{Z}_{t}\right).\end{array}$$
Bayesian linear and nonlinear statespace models have these notable differences:
Difference  Bayesian Linear StateSpace Model  Bayesian Nonlinear StateSpace Models 

Mappings A_{t} and C_{t}  Linear, specified as coefficient matrices 

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
 The

Create Structural Inputs and Model Object
After you choose a statespace model for your problem, create the inputs that specify its structure.
Create Standard StateSpace Model
To represent a standard statespace model in MATLAB by using the ssm
function, consider creating
the model
$$\begin{array}{l}{w}_{t}=a+\varphi {w}_{t1}+b{u}_{t}\\ {y}_{t}={w}_{t}+d{\epsilon}_{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}\left[\begin{array}{c}{w}_{t}\\ {v}_{t}\end{array}\right]=\left[\begin{array}{cc}\varphi & a\\ 0& 1\end{array}\right]\left[\begin{array}{c}{w}_{t1}\\ {v}_{t1}\end{array}\right]+\left[\begin{array}{c}b\\ 0\end{array}\right]{u}_{t}\\ {y}_{t}=\left[\begin{array}{cc}1& 0\end{array}\right]\left[\begin{array}{c}{w}_{t}\\ {v}_{t}\end{array}\right]+d{\epsilon}_{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 = Statespace 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(t1) + (c2)x2(t1) + (c3)u1(t) x2(t) = x2(t1) 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 statespace model, including the model form, which
you can use to verify whether you have specified the model correctly. The
variables c
, where
n
n
is a natural number, represent unknown,
estimable parameters.
Alternatively, you can specify the structure of a statespace model by using a
custom parametertomatrix 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 parametertomatrix mapping function, which specifies the structure of the example statespace 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 statespace model represented in the function by passing
exampleStandardSSM
as a function handle to
ssm
.
Mdl = ssm(@exampleStandardSSM)
Mdl = Statespace model type: ssm The statespace model is implicitly defined by the function: @exampleStandardSSM
Create Diffuse StateSpace Model
To represent a diffuse statespace 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}_{t1}+0.5{u}_{t}\\ {y}_{t}={w}_{t}.\end{array}$$
Suppose Var(w_{0}) is infinite. You can express the model in matrix form
$$\begin{array}{l}\left[\begin{array}{c}{w}_{t}\\ {v}_{t}\end{array}\right]=\left[\begin{array}{cc}1& 2\\ 0& 1\end{array}\right]\left[\begin{array}{c}{w}_{t1}\\ {v}_{t1}\end{array}\right]+\left[\begin{array}{c}0.5\\ 0\end{array}\right]{u}_{t}\\ {y}_{t}=\left[\begin{array}{cc}1& 0\end{array}\right]\left[\begin{array}{c}{w}_{t}\\ {v}_{t}\end{array}\right].\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 = Statespace 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(t1) + (2)x2(t1) + (0.50)u1(t) x2(t) = x2(t1) 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 StateSpace Model
To represent a Bayesian linear statespace model in MATLAB by using the bssm
function, consider creating the model
$$\begin{array}{l}{w}_{t}=a+\varphi {w}_{t1}+b{u}_{t}\\ {y}_{t}={w}_{t}+d{\epsilon}_{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 parametertomatrix mapping function.
Create the following parametertomatrix mapping function, which specifies the
structure of the example statespace model, and save it to your working
directory or write the function in your script. For details on how to write a
parametertomatrix 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
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 statespace model represented in the functions by
passing the functions as function handles to
bssm
.
Mdl = bssm(@exampleBayesianSSM,@exampleFlatPriorBSSM)
Mdl = Mapping that defines a statespace model: @exampleBayesianSSM Log density of parameter prior distribution: @exampleFlatPriorBSSM
Create Bayesian Nonlinear NonGaussian StateSpace Model
To represent a Bayesian nonlinear, nonGaussian statespace model in
MATLAB by using the bnlssm
function,
consider a statespace 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}\left[\begin{array}{c}{x}_{1,t}\\ {x}_{2,t}\end{array}\right]=\left[\begin{array}{cc}{\theta}_{1}& 0\\ 0& {\theta}_{2}\end{array}\right]\left[\begin{array}{c}{x}_{1,t1}\\ {x}_{2,t1}\end{array}\right]+\left[\begin{array}{cc}{\theta}_{3}& 0\\ 0& {\theta}_{4}\end{array}\right]\left[\begin{array}{c}{u}_{1,t}\\ {u}_{2,t}\end{array}\right]\\ {y}_{t}~p\left({y}_{t};{x}_{t}\right)=\frac{\mathrm{exp}\left({x}_{1,t}\right)}{\mathrm{exp}\left({x}_{1,t}\right)+\mathrm{exp}\left({x}_{2,t}\right)}.\end{array}$$
Implicitly specify the model by describing its structure in a custom
parametertomatrix 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 parametertomatrix 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
θ_{3} > 0 and
θ_{4} > 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 nonGaussian statespace 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.
See Also
Objects
Functions
Related Topics
 Explicitly Create StateSpace Model Containing Known Parameter Values
 Create StateSpace Model with Unknown Parameters
 Create StateSpace Model Containing ARMA State
 Implicitly Create StateSpace Model Containing Regression Component
 Implicitly Create TimeVarying StateSpace Model
 What Is the Kalman Filter?