bnlssm
Description
bnlssm
creates a bnlssm
object, representing a
Bayesian nonlinear nonGaussian statespace
model, from a specified nonlinear mapping function, which defines the statespace
model structure, and the log prior distribution function of the parameters. The statespace
model can be timeinvariant or timevarying, and the state or
observation variables, x_{t} or
y_{t}, respectively, can be multivariate series.
State disturbances are Gaussian random variables, and the observation innovations have a
custom distribution.
In general, a bnlssm
object specifies the joint prior distribution
and characteristics of the statespace model only. That is, the model object is a template
intended for further use.
Alternative statespace models include:
Creation
Syntax
Description
creates the Bayesian nonlinear nonGaussian
statespace model object PriorMdl
= bnlssm(ParamMap
,ParamDistribution
)PriorMdl
.
ParamMap
is a function of the collection of statespace model
parameters Θ that characterizes the nonlinear state dynamics (transition of states
x_{t} from time t – 1 to
t) and nonlinear state measurements (observations)
y_{t}. ParamDistribution
is the log prior density of Θ. The state model has additive linear Gaussian disturbances
u_{t}; the observation model can have additive
linear Gaussian innovations ε_{t} or
y_{t} can have a custom density.
PriorMdl
is a template that specifies the joint prior distribution
of Θ and the structure of the nonlinear statespace model.
sets properties using namevalue
arguments. For example,
PriorMdl
= bnlssm(ParamMap
,ParamDistribution
,Name=Value
)bnlssm(ParamMap,ParamDistribution,ObservationForm="distribution")
specifies that the observation log density
log(p(y_{t}x_{t}))
is custom and defined in ParamMap
.
Input Arguments
ParamMap
— Parameter Θ mapping characterizing statespace model structure
function handle
Parameter Θ mapping characterizing the statespace model structure and determining
the data likelihood, specified as a function handle in the form
@
, where
fcnName
is the function name.
fcnName
ParamMap
sets the ParamMap
property.
This table contains the supported forms for ParamMap
and
their required signatures (For more details on the terms in the equations, see Bayesian nonlinear nonGaussian
statespace model).
The distribution of the observations y_{t}
determines the form and
is the
MATLAB^{®} function name for paramMap
ParamMap
, but you can use a
different name.
Observation Form  Observation Distribution  StateSpace Model  Required ParamMap Signature 

Equation  ε_{t} is an additive linear Gaussian random series. 
$$\begin{array}{l}{x}_{t}={A}_{t}\left({x}_{t1};{\theta}_{{A}_{t}}\right)+{B}_{t}\left({\theta}_{{B}_{t}}\right){u}_{t}\\ {y}_{t}={C}_{t}\left({x}_{t};{\theta}_{{C}_{t}}\right)+{D}_{t}\left({\theta}_{{D}_{t}}\right){\epsilon}_{t}.\end{array}$$

function [A,B,C,D,Mean0,Cov0] = paramMap(theta) 
Distribution You must set
 Custom 
$$\begin{array}{l}{x}_{t}={A}_{t}\left({x}_{t1};{\theta}_{{A}_{t}}\right)+{B}_{t}\left({\theta}_{{B}_{t}}\right){u}_{t}\\ {y}_{t}~\mathrm{log}p\left({y}_{t}{x}_{t};{\theta}_{{y}_{t}}\right).\end{array}$$

function [A,B,LogY,Mean0,Cov0] = paramMap(theta) 
can accept
additional inputs, such as predictor data for a regression component in the
observation equation, and it can return additional outputs. This signature shows the
reserved, but optional, outputs.paramMap
function [A,B,LogY,Mean0,Cov0,StateType,DeflatedData] = paramMap(theta)
is atheta
numParams
by1 numeric vector of the statespace model parameters Θ as the first input argument. The function accepts inputs in subsequent positions.ParamMap
returns the statespace model parameters in this table.Equation Quantity Output Position Output Statetransition mapping, A_{t} 1 Required output
A
is one of the following quantities:For a linear timeinvariant model,
A
is an mbym coefficient matrix.For a linear timevarying model,
A
is a Tby1 cell vector, where cell t contains the m_{t}bym_{t–1} coefficient matrix.For a nonlinear mapping,
A
is a function handle. The corresponding function must have this signature:function xt = at(lagxt)
lagxt
is a column vector or matrix of states at time t – 1, with m_{t–1} rows.xt
is a column vector or matrix at time t, with m_{t} rows.
The function can accept additional inputs and return additional outputs. For details on input and output matrices, see
Multipoint
.
Statedisturbanceloading coefficient matrix, B_{t} 2 Required output
B
is one of the following mappings for the additive linear Gaussian statedisturbance series u_{t}:For a linear timeinvariant model,
B
is an mbyk coefficient matrix.For a linear timevarying model,
B
is a Tby1 cell vector, where cell t contains the m_{t}byk_{t} coefficient matrix.
Measurementsensitivity mapping, C_{t} 3, for equation form only Required output
C
, for equationform models, is one of the following quantities:For a linear timeinvariant model,
C
is an nbym coefficient matrix.For a linear timevarying model,
C
is a Tby1 cell vector, where cell t contains the n_{t}bym coefficient matrix.For a nonlinear mapping,
C
is a function handle. The corresponding function must have this signature:function yt = ct(xt)
xt
is a column vector or matrix of states at time t, with m_{t} rows.yt
is a column vector or matrix at time t, with m_{t} rows.
The function can accept additional inputs and return additional outputs. For details on input and output matrices, see
Multipoint
.
Observationinnovation coefficient matrix, D_{t} 4, for equation form only Required output
D
, for equationform models, is one of the following mappings for the additive linear Gaussian observationinnovation series ε_{t}:For a linear timeinvariant model,
D
is an nbyh coefficient matrix.For a linear timevarying model,
D
is a Tby1 cell vector, where cell t contains the n_{t}byh_{t} coefficient matrix.
log p(y_{t}x_{t};Θ_{yt}) 3, for distribution form only Required output
LogY
, for distributionform models, is a function handle to the custom log observation density. The corresponding function must have this signature:function p = logyt(yt,xt)
yt
is a column vector of responses at time t y_{t} with n_{t} rows.xt
is a column vector or matrix of states at time t, with m_{t} rows.p
is a scalar or row vector of corresponding log densities.
The function can accept additional inputs and return additional outputs. For details on input and output matrices, see
Multipoint
.Initial state mean vector, μ_{0} 5, for equation form
4, for distribution form
Output
Mean0
is an m_{0}by1 vector.For linear state transition
A
, the default is the mean of the stationary distribution of the states.For nonlinear state transitions, you must specify
Mean0
.
bnlssm
assumes x_{0} ~ N(μ_{0},Σ_{0}) regardless of equation form. For more details, see State Characteristics.Initial state covariance matrix, Σ_{0} 6 Output
Cov0
is an m_{0}bym_{0} matrix.For linear state transition
A
, the default is the covariance of the stationary distribution of the states.For nonlinear state transitions, you must specify
Cov0
.
For more details, see State Characteristics.
State classification vector, StateType
7 Optional output vector of flags specifying the corresponding state type, either stationary (
0
), the constant 1 (1
), or diffuse, static, or nonstationary (2
). For more details, see State Characteristics.DeflatedData
8 Optional output array of response data deflated by predictor data, which accommodates a regression component in the observation equation
The subscript t of functions and parameters indicate that the parameters can be timevarying. Ignore the subscript for timeinvariant functions or parameters.
To skip specifying an optional output argument, set the argument to
[]
in the function body. For example, to skip specifyingStateType
, setStateType = [];
in the function.
Specify parameters to include in the posterior distribution by setting their value
to an entry in the first input argument
and set known entries of the
coefficients to their values. For example, the following lines define the 1D
timeinvariant statespace model theta
$$\begin{array}{l}{x}_{t}=a{x}_{t1}+b{u}_{t}\\ {y}_{t}={x}_{t}+d{\epsilon}_{t}.\end{array}$$
A = theta(1); B = theta(2); C = 1; D = theta(3);
If
requires the input
parameter vector argument only, you can create the paramMap
bnlssm
object
by calling:
Mdl = bnlssm(@paramMap,...)
In general, create the bnlssm
object by calling:
Mdl = bnlssm(@(theta)paramMap(theta,...otherInputArgs...),...)
Example: bnlssm(@(params)
specifies the function paramFun
(theta,y,z),@ParamDistribution)
that
accepts the statespace model parameters paramFun
theta
, observed responses
y
, and predictor data z
.
Tip
Because outofbounds prior density evaluation is 0, set the log prior density of outofbounds parameter arguments to
Inf
.A best practice is to set
StateType
of each state withinParamMap
for both of the following reasons:By default, the software generates
StateType
, but the default choice might not be accurate. For example, the software cannot distinguish between a constant 1 state and a static state.The software cannot infer
StateType
from data because the data theoretically comes from the observation equation. The realizations of the state equation are unobservable.
Data Types: function_handle
ParamDistribution
— Log of joint probability density function of the statespace model parameters Π(Θ)
function handle
Log of joint probability density function of the statespace model parameters
Π(Θ), specified as a function handle in the form
@
, where
fcnName
is the function name.
fcnName
ParamDistribution
sets the ParamDistribution
property.
Suppose
is the name of the
MATLAB function defining the joint prior distribution of Θ. Then,
logPrior
must have this form.logPrior
function logpdf = logPrior(theta,...otherInputs...) ... end
is atheta
numparams
by1 numeric vector of the linear statespace model parameters Θ. Elements of
must correspond to those oftheta
ParamMap
. The function can accept other inputs in subsequent positions.
is a numeric scalar representing the log of the joint probability density of Θ at the inputlogpdf
.theta
If ParamDistribution
requires the input parameter vector
argument only, you can create the bnlssm
object by
calling:
Mdl = bnlssm(...,@logPrior)
In general, create the bnlssm
object by calling:
Mdl = bnlssm(...,@(theta)logPrior(theta,...otherInputArgs...))
Tip
Because outofbounds prior density evaluation is 0, set the log prior density
of outofbounds parameter arguments to Inf
.
Data Types: function_handle
Properties
ObservationForm
— Observation model form
"equation"
(default)  "distribution"
Observation model form, specified as a value in this table.
Value  Observation Distribution  StateSpace Model 

"equation"  ε_{t} is an additive linear Gaussian random series. 
$$\begin{array}{l}{x}_{t}={A}_{t}\left({x}_{t1};{\theta}_{{A}_{t}}\right)+{B}_{t}\left({\theta}_{{B}_{t}}\right){u}_{t}\\ {y}_{t}={C}_{t}\left({x}_{t};{\theta}_{{C}_{t}}\right)+{D}_{t}\left({\theta}_{{D}_{t}}\right){\epsilon}_{t}.\end{array}$$

"distribution"  Custom 
$$\begin{array}{l}{x}_{t}={A}_{t}\left({x}_{t1};{\theta}_{{A}_{t}}\right)+{B}_{t}\left({\theta}_{{B}_{t}}\right){u}_{t}\\ {y}_{t}~\mathrm{log}p\left({y}_{t}{x}_{t};{\theta}_{{y}_{t}}\right).\end{array}$$

Example: ObservationForm="distribution"
Data Types: char
 string
Multipoint
— Multipoint evaluation of nonlinear functions
empty array ([]
) (default)  "A"
 "C"
 "LogY"
 string vector
Multipoint evaluation of nonlinear functions of ParamMap
A
, C
and LogY
, specified as a
"A"
, "C"
, "LogY"
, or a string
vector of such values. Specify Multipoint
to speed up particle
filtering routines.
For the specified nonlinear functions, bnlssm
object functions
can evaluate multiple points simultaneously. For example, suppose
x_{1} and
x_{2} are two points (state particles) to be
evaluated by
A_{t}(x_{t})
and Multipoint="A"
. The function
A_{t}
evaluates the concatenated points
A_{t}([x_{1}
x_{2}]) =
[Z_{1}
Z_{2}].
You must write the functions so that they can evaluate
numpaticles
points, or states, simultaneously. To write nonlinear
functions to support multipoint evaluation:
For
A
= A_{t}, the function must accept an m_{t–1}bynumparticles
matrix of state particles at time t, and return a 1bynumparticles
row vector of corresponding evaluations. For example,A = x(1,:)./x(2,:)
.For
C
= C_{t}, the function must accept an n_{t}by1 column vector responses at time t and an m_{t}bynumparticles
matrix of state particles at time t, and return a 1bynumparticles
row vector of corresponding evaluations. At time t, the software applies each observation to all state particles. For example,C = theta(2)*x(1,:).*x(2,:)
.For
LogY
= log p(y_{t}x_{t};Θ_{yt}), the function must accept an n_{t}by1 column vector responses at time t and an m_{t}bynumparticles
matrix of state particles at time t, and return a 1bynumparticles
row vector of corresponding log density evaluations. At time t, the software applies each observation to all state particles.
If you disable multipoint evaluation (the default), functions process points sequentially, for example, functions evaluate A_{t}(x_{1}) = Z_{1}, and then they evaluate A_{t}(x_{2}) = Z_{2}.
When A_{t} or C_{t} are coefficient matrices, functions always apply multipoint evaluation because, for example, A_{t}[x_{1} x_{2}] is welldefined.
Example: Multipoint=["A" "LogY"]
indicates that
bnlssm
object functions can evaluate multiple points of the
nonlinear functions A
and LogY
simultaneously.
Data Types: char
 string
ParamMap
— Parameter Θ mapping characterizing statespace model structure
function handle
Parameter Θ mapping characterizing statespace model structure, stored as a function
handle and set by the ParamMap
input argument.
ParamMap
completely specifies the structure of the statespace
model.
Data Types: function_handle
ParamDistribution
— Parameter distribution representation
function handle  numeric matrix
Parameter distribution representation, stored as a function handle or a
numparams
bynumdraws
numeric matrix.
ParamDistribution
is a function handle for the log prior distribution of the parametersParamDistribution
when you createPriorMdl
directly by usingbnlssm
.ParamDistribution
is anumparams
bynumdraws
numeric matrix containing random draws from the posterior distribution of the parameters when you sample from the posterior using an object function. Rows correspond to the elements of
and columns correspond to subsequent draws of the pseudomarginal and particlemarginal MetropolisHastings samplers [1][2][3].theta
Data Types: function_handle
Object Functions
filter  Forward recursion of Bayesian nonlinear nonGaussian statespace model 
Examples
Create Bayesian Nonlinear Model in Equation Form
This example shows how to create the following Bayesian nonlinear statespace model in equation form by using bnlssm
. The statespace model contains two independent, stationary, autoregressive states each with a model constant. The observations are a nonlinear function of the states with Gaussian noise. The prior distribution of the parameters is flat. Symbolically, the system of equations is
$$\left[\begin{array}{c}{x}_{t,1}\\ {x}_{t,2}\\ {x}_{t,3}\\ {x}_{t,4}\end{array}\right]=\left[\begin{array}{cccc}{\theta}_{1}& {\theta}_{2}& 0& 0\\ 0& 1& 0& 0\\ 0& 0& {\theta}_{3}& {\theta}_{4}\\ 0& 0& 0& 1\end{array}\right]\left[\begin{array}{c}{x}_{t1,1}\\ {x}_{t1,2}\\ {x}_{t1,3}\\ {x}_{t1,4}\end{array}\right]+\left[\begin{array}{cc}{\theta}_{5}& 0\\ 0& 0\\ 0& {\theta}_{6}\\ 0& 0\end{array}\right]\left[\begin{array}{c}{u}_{t,1}\\ {u}_{t,3}\end{array}\right]$$
$${y}_{t}=\mathrm{log}(\mathrm{exp}({x}_{t,1}{\mu}_{1})+\mathrm{exp}({x}_{t,3}{\mu}_{3}))+{\theta}_{7}{\epsilon}_{t}.$$
${\mu}_{1}$ and ${\mu}_{3}$ are the unconditional means of the corresponding states. The initial distribution moments of each state are their unconditional mean and covariance.
Create a Bayesian nonlinear statespace model characterized by the system. The observation equation is in equation form, that is, the function composing the states is nonlinear and the innovation series ${\epsilon}_{\mathit{t}}$ is additive, linear, and Gaussian. The Local Functions section contains two functions required to specify the Bayesian nonlinear statespace model: the statespace model parameter mapping function and the prior distribution of the parameters. You can use the functions only within this script.
Mdl = bnlssm(@paramMap,@priorDistribution)
Mdl = bnlssm with properties: ParamMap: @paramMap ParamDistribution: @priorDistribution ObservationForm: "equation" Multipoint: [1x0 string]
Mdl
is a bnlssm
model specifying the statespace model structure and prior distribution of the statespace model parameters. Because Mdl
contains unknown values, it serves as a template for posterior analysis with observations.
Local Functions
These functions specify the statespace model parameter mappings, in equation form, and log prior distribution of the parameters.
function [A,B,C,D,Mean0,Cov0,StateType] = paramMap(theta) A = @(x)blkdiag([theta(1) theta(2); 0 1],[theta(3) theta(4); 0 1])*x; B = [theta(5) 0; 0 0; 0 theta(6); 0 0]; C = @(x)log(exp(x(1)theta(2)/(1theta(1))) + ... exp(x(3)theta(4)/(1theta(3)))); D = theta(7); Mean0 = [theta(2)/(1theta(1)); 1; theta(4)/(1theta(3)); 1]; Cov0 = diag([theta(5)^2/(1theta(1)^2) 0 theta(6)^2/(1theta(3)^2) 0]); StateType = [0; 1; 0; 1]; % Stationary state and constant 1 processes end function logprior = priorDistribution(theta) paramconstraints = [(abs(theta([1 3])) >= 1) (theta(5:7) <= 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 Bayesian Nonlinear Model in Distribution Form
This example shows how to create the following Bayesian nonlinear statespace model in distribution form by using bnlssm
. The statespace model contains 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 is
$$\left[\begin{array}{c}{x}_{t,1}\\ {x}_{t,2}\end{array}\right]=\left[\begin{array}{cc}{\theta}_{1}& 0\\ 0& {\theta}_{2}\end{array}\right]\left[\begin{array}{c}{x}_{t1,1}\\ {x}_{t1,2}\end{array}\right]+\left[\begin{array}{cc}{\theta}_{3}& 0\\ 0& {\theta}_{4}\end{array}\right]\left[\begin{array}{c}{u}_{t,1}\\ {u}_{t,2}\end{array}\right]$$
$${y}_{t}\sim p({y}_{t};{x}_{t}).$$
$\mathit{p}\left({\mathit{y}}_{\mathit{t}};{\mathit{x}}_{\mathit{t}}\right)$ is the Bernoulli probability distribution with probability of success $\frac{\mathrm{exp}\left({\mathit{x}}_{\mathit{t},1}\right)}{\mathrm{exp}\left({\mathit{x}}_{\mathit{t},1}\right)+\mathrm{exp}\left({\mathit{x}}_{\mathit{t},2}\right)}$. Arbitrarily assume that the initial distribution of each state has a mean and standard deviation of 0.5, and assume the states are initially uncorrelated.
Create a Bayesian nonlinear statespace model characterized by the system. The observation equation is in distribution form, that is, the function representing the observation model is a probability distribution. Specify that the observation model is in distribution form.
The Local Functions section contains two functions required to specify the Bayesian nonlinear statespace model. You can use the functions only within this script.
Mdl = bnlssm(@paramMap,@priorDistribution,ObservationForm="distribution")
Mdl = bnlssm with properties: ParamMap: @paramMap ParamDistribution: @priorDistribution ObservationForm: "distribution" Multipoint: [1x0 string]
Local Functions
These functions specify the statespace model parameter mappings, in equation form, and log prior distribution of the parameters.
function [A,B,LogY,Mean0,Cov0,StateType] = paramMap(theta) A = @(x)[theta(1) 0; 0 theta(2)]*x; 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 function logprior = priorDistribution(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
Prepare Model for Multipoint Evaluation
Multipoint evaluation can speed up particle filtering routines. This example shows how to prepare the Bayesian nonlinear statespace model in Create Bayesian Nonlinear Model in Distribution Form for multipoint evaluation.
Because A
is a linear function, it is prepared for multipoint evaluation. However, the following line in the local functions of Create Bayesian Nonlinear Model in Distribution Form does not evaluate points columnwise with respect to input x
.
... LogY = @(y,x)sum(log(binopdf(y,1,exp(x(1))/(exp(x(2))+exp(x(1)))))); ...
You can rewrite the log density of ${\mathit{y}}_{\mathit{t}}$ so that it evaluates the Bernoulli density for each state particle (column) of x
.
... LogY = @(y,x)logbernpdf(y,x); ... function bpdf = logbernpdf(y,x) p = exp(x(1,:))./(exp(x(2,:)) + exp(x(1,:))); bpdf = sum((y.*log(p)+(1y).*log(1p)),1); end
Create a Bayesian nonlinear statespace model characterized by the system.
The observation equation is in distribution form, that is, the function representing the observation model is a probability distribution. Specify that the observation model is in distribution form.
The function
A
andLogY
are in a form that allows for simultaneous function evaluations during the particle filtering routines ofbnlssm
object functions.
The Local Functions section contains two functions required to specify the Bayesian nonlinear statespace model. You can use the functions only within this script.
Mdl = bnlssm(@paramMap,@priorDistribution,ObservationForm="distribution", ... Multipoint=["A" "LogY"])
Mdl = bnlssm with properties: ParamMap: @paramMap ParamDistribution: @priorDistribution ObservationForm: "distribution" Multipoint: ["A" "LogY"]
Local Functions
These functions specify the statespace model parameter mappings, in equation form, and log prior distribution of the parameters.
function [A,B,LogY,Mean0,Cov0,StateType] = paramMap(theta) A = @(x)[theta(1) 0; 0 theta(2)]*x; B = [theta(3) 0; 0 theta(4)]; LogY = @(y,x)logbernpdf(y,x); Mean0 = [1; 1]; Cov0 = eye(2); StateType = [2; 2]; % Nonstationary state process end function bpdf = logbernpdf(y,x) p = exp(x(1,:))./(exp(x(2,:)) + exp(x(1,:))); bpdf = sum((y.*log(p)+(1y).*log(1p)),1); end function logprior = priorDistribution(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
More About
Bayesian Nonlinear NonGaussian StateSpace Model
A Bayesian nonlinear nonGaussian statespace model is a Bayesian view of a statespace model with possibly nonlinear dynamics and nonGaussian observations.
In general, a linear, multivariate, timevarying, Gaussian statespace model is the system of equations
$$\begin{array}{l}{x}_{t}={A}_{t}\left({x}_{t1};\theta \right)+{B}_{t}\left(\theta \right){u}_{t}\\ {y}_{t}~p\left({y}_{t}{x}_{t};\theta ,{Z}_{t}\right).\end{array}$$
for t = 1, ..., T and where:
$${x}_{t}=\left[{x}_{t1},\mathrm{...},{x}_{t{m}_{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} ~ N(μ_{0}, Σ_{0}), where
Mean0
= μ_{0} andCov0
= Σ_{0}.$${y}_{t}=\left[{y}_{t1},\mathrm{...},{y}_{t{n}_{t}}\right]\prime $$ is an n_{t}dimensional observation vector describing how the states are measured by observers at period t.
$${\epsilon}_{t}=\left[{\epsilon}_{t1},\mathrm{...},{\epsilon}_{t{h}_{t}}\right]\prime $$ is an h_{t}dimensional whitenoise vector of observation innovations at period t. All innovations are multivariate Gaussian distributed.
p(y_{t}x_{t};Θ,Z_{t}) characterizes the distribution of the observations at time t. p(y_{t}x_{t};Θ,Z_{t} can take this general form or p(y_{t}x_{t};Θ,Z_{t} = C_{t}(x_{t};Θ) + D_{t}ε_{t}.
$${u}_{t}=\left[{u}_{t1},\mathrm{...},{u}_{t{k}_{t}}\right]\prime $$ is a k_{t}dimensional whitenoise vector of state disturbances at period t. All disturbances are multivariate Gaussian distributed.
ε_{t} and u_{t} are uncorrelated.
A_{t}(x_{t–1}) is the statetransition mapping, a possibly nonlinear function of the previous state x_{t–1} that characterizes the dynamics of the statespace model at time t.
B_{t} is the linear statedisturbanceloading coefficient matrix at time t for the additive Gaussian state disturbances u_{t}.
C_{t}(x_{t}) is the measurementsensitivity mapping, a possibly nonlinear function of the current state x_{t} that characterizes how the latent states are observed at time t.
D_{t} is the linear observationinnovation coefficient matrix at time t for the additive Gaussian observation innovations ε_{t}.
The vector of model parameters Θ are treated as random variables with a joint prior distribution Π(Θ) =
ParamDistribution
For timeinvariant statespace 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, then all predictors deflate each observation.
β is a dbyn matrix of regression coefficients for Z_{t}.
The parameters in the functions or coefficients A_{t}, B_{t}, C_{t}, D_{t}, and β (when present) are model parameters arbitrarily collected in the vector Θ.
StateTransition Mapping A_{t}
The statetransition mapping
A_{t} is a function that specifies how the states
x_{t} are expected to transition from period
t – 1 to t, for all t =
1,...,T. In other words, the expected statetransition equation at
period t is E(x_{t}x_{t–1})
=
A_{t}(x_{t–1}). The corresponding output A
of the
ParamMap
input can have the following forms:
For linear timeinvariant transitions,
A
is an mbym matrix, where m is the number of state variables.For linear timevarying transitions,
A
is a series of matrices represented by a Tby1 cell vector, whereA{t}
contains an m_{t}bym_{t – 1} statetransition coefficient matrix. If the number of state variables changes from period t – 1 to t, m_{t} ≠ m_{t – 1}.an mbym matrix.For timeinvariant or timevarying transitions,
A
is a function handle corresponding to the function the governs how states transition for each time t – 1 to t.
StateDisturbanceLoading Coefficient Matrix B_{t}
The statedisturbanceloading coefficient matrix B_{t} is a matrix or cell vector of matrices that specifies the additive error structure of the state disturbances u_{t} in the statetransition equation from period t – 1 to t, for all t = 1,...,T. In other words, the statetransition equation at period t is x_{t} = A_{t}x_{t–1} + B_{t}u_{t}.
For timeinvariant statespace models, the output B
is an mbyk matrix, where m is the number of state variables and k is the number of state disturbances. The quantity B*(B')
is the statedisturbance covariance matrix for all periods.
For timevarying statespace models, B
is a Tdimensional cell array, where B{t}
contains an m_{t}byk_{t} statedisturbanceloading coefficient matrix. If the number of state variables or state disturbances changes at period t, the matrix dimensions between B{t1}
and B{t}
vary. The quantity B{t}*(B{t}')
is the statedisturbance covariance matrix for period t
.
MeasurementSensitivity Mapping C_{t}
The measurementsensitivity mapping
C_{t} is a function that specifies how the states
x_{t} are expected to combine at period
t to form the observations,
y_{t}, for all t =
1,...,T. In other words, the expected observation equation at period
t is E(y_{t}x_{t})
=
C_{t}(x_{t}). The corresponding output C
of the
ParamMap
input can have the following forms:
For linear timeinvariant model,
C
is an nbym matrix, where n is the number of observation variables and m is the number of state variables.For linear timevarying model,
C
is a series of matrices represented by a Tby1 cell vector, whereC{t}
contains an n_{t}bym_{t} measurementsensitivity coefficient matrix. If the number of state or observation variables changes at period t, the matrix dimensions betweenC{t1}
andC{t}
vary.For a timeinvariant or timevarying model,
C
is a function handle corresponding to the function the governs how states combine to form observations at each time t.
ObservationInnovation Coefficient Matrix D_{t}
The observationinnovation coefficient matrix D_{t} is a matrix or cell vector of matrices that specifies the additive error structure of the observation innovations ε_{t} in the observation equation at period t, for all t = 1,...,T. In other words, the observation equation at period t is y_{t} = C_{t}x_{t} + D_{t}ε_{t}.
For timeinvariant statespace models, the output D
is an nbyh matrix, where n is the number of observation variables and h is the number of observation innovations. The quantity D*(D')
is the observationinnovation covariance matrix for all periods.
For timevarying statespace models, the output D
is a Tdimensional cell array, where D{t}
contains an n_{t}byh_{t} matrix. If the number of observation variables or observation innovations changes at period t, then the matrix dimensions between D{t1}
and D{t}
vary. The quantity D{t}*(D{t}')
is the observationinnovation covariance matrix for period t
.
State Characteristics
Other state characteristics include initial state moments and a description of the dynamic behavior of each state.
You can specify the state characteristics by including them as output arguments in
ParamMap
in their appropriate positions.
Mean0
— Initial state mean μ_{0}, an mby1 numeric vector, where m is the number of states in x_{1}.Cov0
— Initial state covariance matrix Σ_{0}, an mbym positive semidefinite matrix.StateType
— State dynamic behavior indicator, an mby1 numeric vector. This table summarizes the available types of initial state distributions.Value State Dynamic Behavior Indicator 0
Stationary (for example, ARMA models) 1
The constant 1 (that is, the state is 1 with probability 1) 2
Diffuse, nonstationary (for example, random walk model, seasonal linear time series), or static state For example, suppose that the state equation has two state variables: The first state variable is an AR(1) process, and the second state variable is a random walk. Specify the initial distribution types by setting
StateType=[0; 2];
within theParamMap
function.
Static State
A static state does not change in value throughout the sample, that is, $$P\left({x}_{t+1}={x}_{t}\right)=1$$ for all t = 1,...,T.
Tips
Load the data to the MATLAB workspace before creating the model.
Create the parametertomatrix mapping function and log prior distribution function each as their own file.
The equationform model is a special case of the distributionform model, with
LogY
=@(y,x) log(mvnpdf(y,C(x),D*D'))
.
Algorithms
When A_{t} is a coefficient matrix, For each state variable
, default values ofj
Mean0
andCov0
depend onStateType(
:j
)If
StateType(
(stationary state),j
) = 0bnlssm
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),bnlssm
generates the initial values. Otherwise, the software generates the initial values during estimation.If
StateType(
(constant state),j
) = 1Mean0(
isj
)1
andCov0(
isj
)0
.If
StateType(
(nonstationary or diffuse state),j
) = 2Mean0(
is 0 andj
)Cov0(
isj
)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 to2
. Consequently, the software treats static states as nonstationary and assigns the static state a diffuse initial distribution.bnlssm
models do not store observed responses or predictor data. Supply the data wherever necessary using the appropriate input or namevalue pair arguments.DeflateY
is the deflatedobservation 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 andZ
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
[1] Andrieu, Christophe, Arnaud Doucet, and Roman Holenstein. "Particle Markov Chain Monte Carlo Methods." Journal of the Royal Statistical Society Series B: Statistical Methodology 72 (June 2010): 269–342. https://doi.org/10.1111/j.14679868.2009.00736.x.
[2] Andrieu, Christophe, and Gareth O. Roberts. "The PseudoMarginal Approach for Efficient Monte Carlo Computations." Ann. Statist. 37 (April 2009): 697–725. https://dx.doi.org/10.1214/07AOS574.
[3] Durbin, J, and Siem Jan Koopman. Time Series Analysis by State Space Methods. 2nd ed. Oxford: Oxford University Press, 2012.
Version History
Introduced in R2023b
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)