estimates
the parameters of `EstMdl`

= estimate(`Mdl`

,`Y`

,`params0`

)`Mdl`

using the Kalman filter and
maximum likelihood, where:

`Mdl`

is a state-space model (`ssm`

).`Y`

is the observed response series.`params0`

is the vector of initial values for unknown parameters.

The software returns `EstMdl`

, which
is the estimated state-space model (`ssm`

) that stores
the estimated coefficient matrices and initial state means, covariances,
and distributions.

For explicitly specified state-space models (that is, you specified

`Mdl`

without using a parameter-to-matrix mapping function), the software estimates all`NaN`

values in the coefficient matrices (`Mdl.A`

,`Mdl.B`

,`Mdl.C`

, and`Mdl.D`

) and the initial state means and covariance matrix (`Mdl.Mean0`

and`Mdl.Cov0`

).For implicitly specified state-space models (that is, you specified

`Mdl`

using a parameter-to-matrix mapping function, which the software stores in`Mdl.ParamMap`

), you define the model and the location of the unknown parameters using the parameter-to-matrix mapping function. Implicitly specify a state-space model to estimate complex models, impose parameter constraints, and estimate initial states. The parameter-to-mapping function can also accommodate additional output arguments.

estimates
the state-space model `EstMdl`

= estimate(`Mdl`

,`Y`

,`params0`

,`Name,Value`

)`Mdl`

with additional options
specified by one or more `Name,Value`

pair arguments.

For example, pass in predictor data to include a linear regression component to the observation equation, control how the results appear in the Command Window, and indicate which estimation method to use for the parameter covariance matrix.

`[`

additionally returns:`EstMdl`

,`estParams`

,`EstParamCov`

,`logL`

,`Output`

]
= estimate(___)

`estParams`

, a vector containing the estimated parameters`EstParamCov`

, the estimated variance-covariance matrix of the estimated parameters`logL`

, the optimized loglikelihood value`Output`

, optimization diagnostic information structure

using any of the input arguments in the previous syntaxes.

**Constrained likelihood objective function
maximization**

You can specify any combination of linear inequality, linear equality, and upper and lower bound constraints on the parameters.

If a parameter is unbounded below, then set

`'lb',-Inf`

.If a parameter is unbounded above, then set

`'ub',Inf`

.It is good practice to avoid equality and inequality constraints during optimization. For example, if you want to constrain the parameter

*w*to be positive, then implicitly specify the state-space model using a parameter-to-matrix mapping function, set*w*= exp(*s*) within the function, and use unconstrained optimization to estimate*s*. Subsequently,*s*can assume any real value, but*w*must be positive.

**Predictors and corresponding coefficients**

The state-space model

`Mdl`

does not store the predictors (*Z*) nor their corresponding regression coefficients (_{t}*β*). Supply the predictors and their corresponding coefficients wherever necessary using the appropriate name-value pair arguments.The predictor series serve as observation deflators. Subsequently, the deflated data set is

*Y*–_{t}*Z*, where:_{t}β$${Z}_{t}=\left(\begin{array}{cccc}{z}_{1t}& {z}_{2t}& \cdots & {z}_{dt}\end{array}\right).$$, that is,

*Z*is a*T*-by*d*matrix.*z*_{jt}is the period*t*value of predictor*j*.*β*is a*d*-by-*n*matrix of regression coefficients.

To include an overall mean to the observation model, include a column of

`1`

s in*Z*._{t}If you want to account for predictor effects when you simulate (

`simulate`

), then you must deflate the observations manually. To deflate the observations, use $${W}_{t}={Y}_{t}-{Z}_{t}\widehat{\beta}.$$If the state equation requires predictors, then expand the states by the constant 1 and the predictors.

If the regression model is complex, then consider implicitly defining the state space model. For example, define the parameter-to-matrix mapping function using the following syntax pattern.

In this example,function [A,B,C,D,Mean0,Cov0,StateType,DeflateY] = ParamMap(params,Y,Z) ... DeflateY = Y - exp(params(9) + params(10)*Z); ... end

`Y`

is the matrix of observations and`Z`

is the matrix of predictors. The function returns`DeflateY`

, which is the matrix of deflated observations. Specify`Y`

and`Z`

in the MATLAB^{®}Workspace before, and then pass`ParamMap`

to`ssm`

using the following syntax pattern.Mdl = ssm(@(params)ParamMap(params,Y,Z))

This is also useful if each response series requires a distinct set of predictors.

If the state equation requires predictors, then any one of the following:

Expanding the states by including the constant 1 state.

Expanding the states by including the predictors.

If the model is time varying with respect the observed responses, then the software does not support including predictors. If the observation vectors among different periods vary in length, then the software cannot determine which coefficients to use to deflate the observed responses.

**Additional Tips**

The software accommodates missing data. Indicate missing data using

`NaN`

values in the observed responses (`Y`

).It is good practice to check the convergence status of the optimization routine by displaying

`Output.ExitFlag`

.If the optimization algorithm does not converge, then you can increase the number of iterations using the

`'Options'`

name-value pair argument.If the optimization algorithm does not converge, then consider using

`refine`

, which might help you obtain better initial parameter values for optimization.

A *state-space model* is
a discrete-time, stochastic model that contains two sets of equations:

One describing how a latent process transitions in time (the

*state equation*)Another describing how an observer measures the latent process at each period (the

*observation equation*)

Symbolically, you can write a linear, multivariate, Gaussian state-space model using the following system of equations

$$\begin{array}{l}{x}_{t}={A}_{t}{x}_{t-1}+{B}_{t}{u}_{t}\\ {y}_{t}-{Z}_{t}\beta ={C}_{t}{x}_{t}+{D}_{t}{\epsilon}_{t},\end{array}$$

for *t* = 1,...,*T*.

$${x}_{t}=\left[{x}_{t1},\mathrm{...},{x}_{t{m}_{t}}\right]\prime $$ is an

*m*-dimensional state vector describing the dynamics of some, possibly unobservable, phenomenon at period_{t}*t*.$${y}_{t}=\left[{y}_{t1},\mathrm{...},{y}_{t{n}_{t}}\right]\prime $$ is an

*n*-dimensional observation vector describing how the states are measured by observers at period_{t}*t*.*A*is the_{t}*m*-by-_{t}*m*_{t – 1}state-transition matrix describing how the states at time*t*transition to the states at period*t*– 1.*B*is the_{t}*m*-by-_{t}*k*state-disturbance-loading matrix describing how the states at period_{t}*t*combine with the innovations at period*t*.*C*is the_{t}*n*-by-_{t}*m*measurement-sensitivity matrix describing how the observations at period_{t}*t*relate to the states at period*t*.*D*is the_{t}*n*-by-_{t}*h*observation-innovation matrix describing how the observations at period_{t}*t*combine with the observation errors at period*t*.The matrices

*A*,_{t}*B*,_{t}*C*, and_{t}*D*are referred to as_{t}*coefficient matrices*, and might contain unknown parameters.$${u}_{t}=\left[{u}_{t1},\mathrm{...},{u}_{t{k}_{t}}\right]\prime $$ is a

*k*-dimensional, Gaussian, white-noise, unit-variance vector of state disturbances at period_{t}*t*.$${\epsilon}_{t}=\left[{\epsilon}_{t1},\mathrm{...},{\epsilon}_{t{h}_{t}}\right]\prime $$ is an

*h*-dimensional, Gaussian, white-noise, unit-variance vector of observation innovations at period_{t}*t*.*ε*and_{t}*u*are uncorrelated._{t}For time-invariant models,

$${Z}_{t}=\left[\begin{array}{cccc}{z}_{t1}& {z}_{t2}& \cdots & {z}_{td}\end{array}\right]$$ 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, then all predictors deflate each observation.*β*is a*d*-by-*n*matrix of regression coefficients for*Z*._{t}

To write a time-invariant state-space model, drop the *t* subscripts
of all coefficient matrices and dimensions.

In a *time-invariant* state-space
model:

The coefficient matrices are equivalent for all periods.

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

$$\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,t-1}\\ {x}_{2,t-1}\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}$$

represents a time-invariant state-space model.

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. For example, this might happen if there is a regime shift or one of the states or observations cannot be measured during the sampling time frame. Also, you can model seasonality using time-varying models.

To illustrate a regime shift, 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,t-1}\\ {x}_{2,t-1}\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,t-1}\\ {x}_{2,t-1}\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}.$$

There are three sets of state transition matrices, whereas there are only two sets of the other coefficient matrices.

For explicitly defined state-space models, the software applies all predictors to each response series. However, each response series has its own set of regression coefficients.

The software estimates regression coefficients along with all other state-space model parameters. The software is flexible enough to allow applying constraints to the regression coefficients using the constrained optimization options for

`fminunc`

.The software passes the name-value pair arguments

`Options`

,`Aineq`

,`bineq`

,`Aeq`

,`beq`

,`lb`

, and`ub`

directly to the optimizer`fmincon`

or`fminunc`

.If you do not specify optimization constraints, then the software uses

`fminunc`

for unconstrained numerical estimation. If you specify any pair of optimization constraints, then the software uses`fmincon`

for constrained numerical estimation. For either type of optimization, optimization options you set using the name-value pair argument`Options`

must be consistent with the options of the optimization algorithm.If you set

`'Univariate',true`

, then, during the filtering algorithm, the software sequentially updates rather then updating all at once. This might accelerate parameter estimation, especially for a low-dimensional, time-invariant model.Suppose that you want to create a state-space model using a parameter-to-matrix mapping function with this signature

and you specify the model using an anonymous function[A,B,C,D,Mean0,Cov0,StateType,DeflateY] = paramMap(params,Y,Z)

The observed responsesMdl = ssm(@(params)paramMap(params,Y,Z))

`Y`

and predictor data`Z`

are not input arguments in the anonymous function. If`Y`

and`Z`

exist in the MATLAB Workspace before creating`Mdl`

, then the software establishes a link to them. Otherwise, if you pass`Mdl`

to`estimate`

, the software throws an error.The link to the data established by the anonymous function overrides all other corresponding input argument values of

`estimate`

. This distinction is important particularly when conducting a rolling window analysis. For details, see Rolling-Window Analysis of Time-Series Models.

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

Was this topic helpful?