Documentation |
EstMdl = estimate(Mdl,Y,params0) estimates the parameters of 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.
EstMdl = estimate(Mdl,Y,params0,Name,Value) estimates the state-space model 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.
[EstMdl,estParams,EstParamCov,logL,Output] = estimate(___) additionally returns:
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_{t}) nor their corresponding regression coefficients (β). 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_{t}β, where:
$${Z}_{t}=\left(\begin{array}{cccc}{z}_{1t}& {z}_{2t}& \cdots & {z}_{dt}\end{array}\right).$$, that is, Z is a T-byd 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 1s 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.
function [A,B,C,D,Mean0,Cov0,StateType,DeflateY] = ParamMap(params,Y,Z) ... DeflateY = Y - exp(params(9) + params(10)*Z); ... end
In this example, 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_{t}-dimensional state vector describing the dynamics of some, possibly unobservable, phenomenon at period t.
$${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.
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.
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.
The matrices A_{t}, B_{t}, C_{t}, and D_{t} are referred to as coefficient matrices, and might contain unknown parameters.
$${u}_{t}=\left[{u}_{t1},\mathrm{...},{u}_{t{k}_{t}}\right]\prime $$ is a k_{t}-dimensional, Gaussian, white-noise, unit-variance vector of state disturbances at period t.
$${\epsilon}_{t}=\left[{\epsilon}_{t1},\mathrm{...},{\epsilon}_{t{h}_{t}}\right]\prime $$ 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}=\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
[A,B,C,D,Mean0,Cov0,StateType,DeflateY] = paramMap(params,Y,Z)
and you specify the model using an anonymous function
Mdl = ssm(@(params)paramMap(params,Y,Z))
The observed responses 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.