estimate

Maximum likelihood parameter estimation of diffuse state-space models

Syntax

EstMdl = estimate(Mdl,Y,params0)

EstMdl = estimate(Mdl,Y,params0,Name,Value)

[EstMdl,estParams,EstParamCov,logL,Output] = estimate(___)

Description

EstMdl = estimate(Mdl,Y,params0) returns an estimated diffuse state-space model from fitting the dssm model Mdl to the response data Y. params0 is the vector of initial values for the unknown parameters in Mdl.

EstMdl = estimate(Mdl,Y,params0,Name,Value) estimates the diffuse state-space model with additional options specified by one or more Name,Value pair arguments. For example, you can specify to deflate the observations by a linear regression using predictor data, 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 these arguments using any of the input arguments in the previous syntaxes.

• 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

Input Arguments

Mdl — Diffuse state-space model

dssm model object

Diffuse state-space model containing unknown parameters, specified as a dssm model object returned by dssm.

• For explicitly created state-space models, 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 details on explicit and implicit model creation, see dssm.

• For implicitly created state-space models, you specify the model structure and the location of the unknown parameters using the parameter-to-matrix mapping function. Implicitly create 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.

Note

Mdl does not store observed responses or predictor data. Supply the data wherever necessary using, the appropriate input and name-value pair arguments.

Y — Observed response data

numeric matrix | cell vector of numeric vectors

Observed response data to which Mdl is fit, specified as a numeric matrix or a cell vector of numeric vectors.

• If Mdl is time invariant with respect to the observation equation, then Y is a T-by-n matrix. Each row of the matrix corresponds to a period and each column corresponds to a particular observation in the model. Therefore, T is the sample size and n is the number of observations per period. The last row of Y contains the latest observations.

• If Mdl is time varying with respect to the observation equation, then Y is a T-by-1 cell vector. Y{t} contains an n_t-dimensional vector of observations for period t, where t = 1,...,T. The corresponding dimensions of the coefficient matrices in Mdl.C{t} and Mdl.D{t} must be consistent with the matrix in Y{t} for all periods. The last cell of Y contains the latest observations.

Suppose that you create Mdl implicitly by specifying a parameter-to-matrix mapping function, and the function has input arguments for the observed responses or predictors. Then, the mapping function establishes a link to observed responses and the predictor data in the MATLAB^® workspace, which overrides the value of Y.

NaN elements indicate missing observations. For details on how the Kalman filter accommodates missing observations, see Algorithms.

Data Types: double | cell

params0 — Initial values of unknown parameters

numeric vector

Initial values of unknown parameters for numeric maximum likelihood estimation, specified as a numeric vector.

The elements of params0 correspond to the unknown parameters in the state-space model matrices A, B, C, and D, and, optionally, the initial state mean Mean0 and covariance matrix Cov0.

• If you created Mdl explicitly (that is, by specifying the matrices without a parameter-to-matrix mapping function), then the software maps the elements of params to NaNs in the state-space model matrices and initial state values. The software searches for NaNs column-wise, following the order A, B, C, D, Mean0, Cov0.

• If you created Mdl implicitly (that is, by specifying the matrices with a parameter-to-matrix mapping function), then set initial parameter values for the state-space model matrices, initial state values, and state types within the parameter-to-matrix mapping function.

Data Types: double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'CovMethod','hessian','Display','diagnostics','Predictors',Z specifies to estimate the asymptotic parameter covariance using the negative, inverted Hessian matrix, display optimization diagnostics at the Command Window, and to deflate the observations by a linear regression containing the predictor data Z.

Estimation Options

Beta0 — Initial values of regression coefficients

numeric matrix

Initial values of regression coefficients, specified as the comma-separated pair consisting of 'Beta0' and a d-by-n numeric matrix. d is the number of predictor variables (see Predictors) and n is the number of observed response series (see Y).

By default, Beta0 is the ordinary least-squares estimate of Y onto Predictors.

Data Types: double

CovMethod — Asymptotic covariance estimation method

'opg' (default) | 'hessian' | 'sandwich'

Asymptotic covariance estimation method, specified as the comma-separated pair consisting of 'CovMethod' and a value in this table.

Value	Description
'hessian'	Negative, inverted Hessian matrix
'opg'	Outer product of gradients (OPG)
'sandwich'	Both Hessian and OPG

Example: 'CovMethod','sandwich'

Data Types: char

Display — Command Window display option

"params" (default) | "diagnostics" | "full'" | "iter" | "off" | string vector | cell vector of character vectors

Command Window display option, specified as one or more of the values in this table.

Value	Information Displayed
"diagnostics"	Optimization diagnostics
"full"	Maximum likelihood parameter estimates, standard errors, t statistics, iterative optimization information, and optimization diagnostics
"iter"	Iterative optimization information
"off"	None
"params"	Maximum likelihood parameter estimates, standard errors, and t statistics and p-values of coefficient significance tests

Example: Display="off" is well suited for running a simulation that estimates many models.

Example: Display=["params" "diagnostics"] displays all estimation results and the optimization diagnostics.

Data Types: char | cell | string

Options — Optimization options

optimoptions optimization controller

Optimization options, specified as the comma-separated pair consisting of 'Options' and an optimoptions optimization controller. Options replaces default optimization options of the optimizer. For details on altering default values of the optimizer, see the optimization controller optimoptions, the constrained optimization function fmincon, or the unconstrained optimization function fminunc in Optimization Toolbox™.

For example, to change the constraint tolerance to 1e-6, set Options = optimoptions(@fmincon,'ConstraintTolerance',1e-6,'Algorithm','sqp'). Then, pass Options into estimate using 'Options',Options.

By default:

• For constrained optimization, estimate maximizes the likelihood objective function using fmincon and its default options, but sets 'Algorithm','interior-point'.

• For unconstrained optimization, estimate maximizes the likelihood objective function using fminunc and its default options, but sets 'Algorithm','quasi-newton'.

Predictors — Predictor data

[] (default) | numeric matrix

Predictor data for the regression component in the observation equation, specified as the comma-separated pair consisting of 'Predictors' and a T-by-d numeric matrix. T is the number of periods and d is the number of predictor variables. Row t corresponds to the observed predictors at period t (Z_t) in the expanded observation equation

$$y_t-Z_t\beta =C{x}_t+D{u}_t.$$

In other words, the predictor series serve as observation deflators. β is a d-by-n time-invariant matrix of regression coefficients that the software estimates with all other parameters.

• For n observations per period, the software regresses all predictor series onto each observation.

• If you specify Predictors, then Mdl must be time invariant. Otherwise, the software returns an error.

• By default, the software excludes a regression component from the state-space model.

Data Types: double

SwitchTime — Final period for diffuse state initialization

positive integer

Final period for diffuse state initialization, specified as the comma-separated pair consisting of 'SwitchTime' and a positive integer. That is, estimate uses the observations from period 1 to period SwitchTime as a presample to implement the exact initial Kalman filter (see Diffuse Kalman Filter and [1]). After initializing the diffuse states, estimate applies the standard Kalman filter to the observations from periods SwitchTime + 1 to T.

The default value for SwitchTime is the last period in which the estimated smoothed state precision matrix is singular (i.e., the inverse of the covariance matrix). This specification represents the fewest number of observations required to initialize the diffuse states. Therefore, it is a best practice to use the default value.

If you set SwitchTime to a value greater than the default, then the effective sample size decreases. If you set SwitchTime to a value that is fewer than the default, then estimate might not have enough observations to initialize the diffuse states, which can result in an error or improper values.

In general, estimating, filtering, and smoothing state-space models with at least one diffuse state requires SwitchTime to be at least one. The default estimation display contains the effective sample size.

Data Types: double

Tolerance — Forecast uncertainty threshold

0 (default) | nonnegative scalar

Forecast uncertainty threshold, specified as the comma-separated pair consisting of 'Tolerance' and a nonnegative scalar.

If the forecast uncertainty for a particular observation is less than Tolerance during numerical estimation, then the software removes the uncertainty corresponding to the observation from the forecast covariance matrix before its inversion.

It is best practice to set Tolerance to a small number, for example, le-15, to overcome numerical obstacles during estimation.

Example: 'Tolerance',le-15

Data Types: double

Univariate — Univariate treatment of multivariate series flag

false (default) | true

Univariate treatment of a multivariate series flag, specified as the comma-separated pair consisting of 'Univariate' and true or false. Univariate treatment of a multivariate series is also known as sequential filtering.

The univariate treatment can accelerate and improve numerical stability of the Kalman filter. However, all observation innovations must be uncorrelated. That is, D_tD_t' must be diagonal, where D_t, t = 1,...,T, is one of the following:

• The matrix D{t} in a time-varying state-space model

• The matrix D in a time-invariant state-space model

Example: 'Univariate',true

Data Types: logical

Constrained Optimization Options for fmincon

Aeq — Linear equality constraint parameter transformer

matrix

Linear equality constraint parameter transformer for constrained likelihood objective function maximization, specified as the comma-separated pair consisting of 'Aeq' and a matrix.

If you specify Aeq and beq, then estimate maximizes the likelihood objective function using the equality constraint $$Aeq\theta =beq,$$ where θ is a vector containing every Mdl parameter.

The number of rows of Aeq is the number of constraints, and the number of columns is the number of parameters that the software estimates. Order the columns of Aeq by Mdl.A, Mdl.B, Mdl.C, Mdl.D, Mdl.Mean0, Mdl.Cov0, and the regression coefficient (if the model has one).

Specify Aeq and beq together, otherwise estimate returns an error.

Aeq directly corresponds to the input argument Aeq of fmincon, not to the state-transition coefficient matrix Mdl.A.

By default, if you did not specify any constraint (linear inequality, linear equality, or upper and lower bound), then estimate maximizes the likelihood objective function using unconstrained maximization.

Aineq — Linear inequality constraint parameter transformer

matrix

Linear inequality constraint parameter transformer for constrained likelihood objective function maximization, specified as the comma-separated pair consisting of 'Aineq' and a matrix.

If you specify Aineq and bineq, then estimate maximizes the likelihood objective function using the inequality constraint $$Aineq\theta \le bineq,$$ where θ is a vector containing every Mdl parameter.

The number of rows of Aineq is the number of constraints, and the number of columns is the number of parameters that the software estimates. Order the columns of Aineq by Mdl.A, Mdl.B, Mdl.C, Mdl.D, Mdl.Mean0, Mdl.Cov0, and the regression coefficient (if the model has one).

Specify Aineq and bineq together, otherwise estimate returns an error.

Aineq directly corresponds to the input argument A of fmincon, not to the state-transition coefficient matrix Mdl.A.

By default, if you did not specify any constraint (linear inequality, linear equality, or upper and lower bound), then estimate maximizes the likelihood objective function using unconstrained maximization.

Data Types: double

beq — Linear equality constraints of transformed parameters

numeric vector

Linear equality constraints of the transformed parameters for constrained likelihood objective function maximization, specified as the comma-separated pair consisting of 'beq' and a numeric vector.

If you specify Aeq and beq, then estimate maximizes the likelihood objective function using the equality constraint $$Aeq\theta =beq,$$ where θ is a vector containing every Mdl parameter..

Specify Aeq and beq together, otherwise estimate returns an error.

beq directly corresponds to the input argument beq of fmincon, and is not associated with any component of Mdl.

By default, if you did not specify any constraint (linear inequality, linear equality, or upper and lower bound), then estimate maximizes the likelihood objective function using unconstrained maximization.

Data Types: double

bineq — Linear inequality constraint upper bounds

numeric vector

Linear inequality constraint upper bounds of the transformed parameters for constrained likelihood objective function maximization, specified as the comma-separated pair consisting of 'bineq' and a numeric vector.

If you specify Aineq and bineq, then estimate maximizes the likelihood objective function using the inequality constraint $$Aineq\theta \le bineq,$$ where θ is a vector containing every Mdl parameter.

Specify Aineq and bineq together, otherwise estimate returns an error.

bineq directly corresponds to the input argument b of fmincon, and is not associated with any component of Mdl.

By default, if you did not specify any constraint (linear inequality, linear equality, or upper and lower bound), then estimate maximizes the likelihood objective function using unconstrained maximization.

Data Types: double

lb — Lower bounds of parameters

numeric vector

Lower bounds of the parameters for constrained likelihood objective function maximization, specified as the comma-separated pair consisting of 'lb' and a numeric vector.

If you specify lb and ub, then estimate maximizes the likelihood objective function subject to$$lb\le \theta \le ub,$$ where θ is a vector containing every Mdl parameter.

Order the elements of lb by Mdl.A, Mdl.B, Mdl.C, Mdl.D, Mdl.Mean0, Mdl.Cov0, and the regression coefficient (if the model has one).

By default, if you did not specify any constraint (linear inequality, linear equality, or upper and lower bound), then estimate maximizes the likelihood objective function using unconstrained maximization.

Data Types: double

ub — Upper bounds of parameters

numeric vector

Upper bounds of the parameters for constrained likelihood objective function maximization, specified as the comma-separated pair consisting of 'ub' and a numeric vector.

If you specify lb and ub, then estimate maximizes the likelihood objective function subject to$$lb\le \theta \le ub,$$ where θ is a vector every Mdl parameter.

Order the elements of ub by Mdl.A, Mdl.B, Mdl.C, Mdl.D, Mdl.Mean0, Mdl.Cov0, and the regression coefficient (if the model has one).

By default, if you did not specify any constraint (linear inequality, linear equality, or upper and lower bound), then estimate maximizes the likelihood objective function using unconstrained maximization.

Data Types: double

Output Arguments

EstMdl — Diffuse state-space model containing parameter estimates

dssm model object

Diffuse state-space model containing the parameter estimates, returned as a dssm model object.

estimate uses the diffuse Kalman filter and maximum likelihood to calculate all parameter estimates.

Regardless of how you created Mdl, EstMdl stores:

• The parameter estimates of the coefficient matrices in the properties A, B, C, and D.

• The initial state means and covariance matrix in the properties Mean0 and Cov0.

Note

EstMdl does not store observed responses or predictor data. If you plan to filter (using filter), forecast (using forecast), or smooth (using smooth) using EstMdl, then you need to supply the appropriate data.

estParams — Maximum likelihood estimates of model parameters

numeric vector

Maximum likelihood estimates of the model parameters known to the optimizer, returned as a numeric vector. estParams has the same dimensions as params0.

estimate arranges the estimates in estParams corresponding to unknown parameters in this order.

1. EstMdl.A(:), that is, estimates in EstMdl.A listed column-wise

2. EstMdl.B(:)

3. EstMdl.C(:)

4. EstMdl.D(:)

5. EstMdl.Mean0

6. EstMdl.Cov0(:)

7. In models with predictors, estimated regression coefficients listed column-wise

EstParamCov — Variance-covariance matrix of maximum likelihood estimates

numeric matrix

Variance-covariance matrix of maximum likelihood estimates of the model parameters known to the optimizer, returned as a numeric matrix.

The rows and columns contain the covariances of the parameter estimates. The standard errors of the parameter estimates are the square root of the entries along the main diagonal.

estimate arranges the estimates in the rows and columns of EstParamCov corresponding to unknown parameters in this order.

1. EstMdl.A(:), that is, estimates in EstMdl.A listed column-wise

2. EstMdl.B(:)

3. EstMdl.C(:)

4. EstMdl.D(:)

5. EstMdl.Mean0

6. EstMdl.Cov0(:)

7. In models with predictors, estimated regression coefficients listed column-wise

logL — Optimized loglikelihood value

scalar

Optimized loglikelihood value, returned as a scalar.

Missing observations do not contribute to the loglikelihood. The observations after the first SwitchTime periods contribute to the loglikelihood only.

Output — Optimization information

structure array

Optimization information, returned as a structure array.

This table describes the fields of Output.

Field	Description
ExitFlag	Optimization exit flag that describes the exit condition. For details, see fmincon and fminunc.
Options	Optimization options that the optimizer used for numerical estimation. For details, see optimoptions.

Data Types: struct

Examples

Fit Time-Invariant Diffuse State-Space Model to Data

Generate data from a known model, and then fit a diffuse state-space model to the data.

Suppose that a latent process is this AR(1) process

$$x_t=0.5x_{t-1}+u_t,$$

where $$u_t$$ is Gaussian with mean 0 and standard deviation 1.

Generate a random series of 100 observations from $$x_t$$, assuming that the series starts at 1.5.

T = 100;
ARMdl = arima('AR',0.5,'Constant',0,'Variance',1);
x0 = 1.5;
rng(1); % For reproducibility
x = simulate(ARMdl,T,'Y0',x0);

Suppose further that the latent process is subject to additive measurement error as indicated in the equation

$$y_t=x_t+{\epsilon }_t,$$

where $${\epsilon }_t$$ is Gaussian with mean 0 and standard deviation 0.1.

Use the random latent state process (x) and the observation equation to generate observations.

y = x + 0.1*randn(T,1);

Together, the latent process and observation equations compose a state-space model. Supposing that the coefficients and variances are unknown parameters, the state-space model is

$$\begin{array}{c}{x}_t=\varphi x_{t-1}+{\sigma }_1{u}_t\\ y_t=x_t+{\sigma }_2{\epsilon }_t.\end{array}$$

Specify the state-transition matrix. Use NaN values for unknown parameters.

A = NaN;

Specify the state-disturbance-loading coefficient matrix.

B = NaN;

Specify the measurement-sensitivity coefficient matrix.

C = 1;

Specify the observation-innovation coefficient matrix

D = NaN;

Create the state-space model using the coefficient matrices and specify that the state variable is diffuse. A diffuse state specification indicates complete ignorance on the values of the states.

StateType = 2;
Mdl = dssm(A,B,C,D,'StateType',StateType);

Mdl is a dssm model. Verify that the model is correctly specified by viewing its display in the Command Window.

Pass the observations to estimate to estimate the parameter. Set a starting value for the parameter to params0. $${\sigma }_1$$ and $${\sigma }_2$$ must be positive, so set the lower bound constraints using the 'lb' name-value pair argument. Specify that the lower bound of $$\varphi$$ is -Inf.

params0 = [0.9; 0.5; 0.1];
EstMdl = estimate(Mdl,y,params0,'lb',[-Inf; 0; 0])

Method: Maximum likelihood (fmincon)
Effective Sample size:             99
Logarithmic  likelihood:     -138.968
Akaike   info criterion:      283.936
Bayesian info criterion:      291.752
      |     Coeff      Std Err   t Stat    Prob  
-------------------------------------------------
 c(1) | 0.56114       0.18045   3.10975  0.00187 
 c(2) | 0.75836       0.24569   3.08661  0.00202 
 c(3) | 0.57129       0.27455   2.08086  0.03745 
      |                                          
      |  Final State   Std Dev   t Stat    Prob  
 x(1) | 1.24096       0.46532   2.66690  0.00766 

EstMdl = 
State-space model type: dssm

State vector length: 1
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 equation:
x1(t) = (0.56)x1(t-1) + (0.76)u1(t)

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

Initial state distribution:

Initial state means
 x1 
  0 

Initial state covariance matrix
     x1  
 x1  Inf 

State types
    x1   
 Diffuse 

EstMdl is a dssm model. The results of the estimation appear in the Command Window, contain the fitted state-space equations, and contain a table of parameter estimates, their standard errors, t statistics, and p-values.

Use dot notation to use or display the fitted state-transition matrix.

EstMdl.A

ans = 
0.5611

Pass EstMdl to forecast to forecast observations, or to simulate to conduct a Monte Carlo study.

Estimate Diffuse State-Space Model Containing Regression Component

Suppose that the linear relationship between unemployment rate and the nominal gross national product (nGNP) is of interest. Suppose further that unemployment rate is an AR(1) series. Symbolically, and in state-space form, the model is

$$\begin{array}{l}{x}_t=\varphi x_{t-1}+\sigma u_t\\ y_t-\beta Z_t=x_t,\end{array}$$

where:

• $$x_t$$ is the unemployment rate at time t.

• $$y_t$$ is the observed change in the unemployment rate being deflated by the return of nGNP ($$Z_t$$).

• $$u_t$$ is the Gaussian series of state disturbances having mean 0 and unknown standard deviation $$\sigma$$.

Load the Nelson-Plosser data set, which contains the unemployment rate and nGNP series, among other things.

load Data_NelsonPlosser

Preprocess the data by taking the natural logarithm of the nGNP series and removing the starting NaN values from each series.

isNaN = any(ismissing(DataTable),2);       % Flag periods containing NaNs
gnpn = DataTable.GNPN(~isNaN);
y = diff(DataTable.UR(~isNaN));
T = size(gnpn,1);                          % The sample size
Z = price2ret(gnpn);

This example continues using the series without NaN values. However, using the Kalman filter framework, the software can accommodate series containing missing values.

Specify the coefficient matrices.

A = NaN;
B = NaN;
C = 1;

Create the state-space model using dssm by supplying the coefficient matrices and specifying that the state values come from a diffuse distribution. The diffuse specification indicates complete ignorance about the moments of the initial distribution.

StateType = 2;
Mdl = dssm(A,B,C,'StateType',StateType);

Estimate the parameters. Specify the regression component and its initial value for optimization using the 'Predictors' and 'Beta0' name-value pair arguments, respectively. Display the estimates and all optimization diagnostic information. Restrict the estimate of $$\sigma$$ to all positive, real numbers.

params0 = [0.3 0.2]; % Initial values chosen arbitrarily
Beta0 = 0.1;
EstMdl = estimate(Mdl,y,params0,'Predictors',Z,'Display','full',...
    'Beta0',Beta0,'lb',[-Inf 0 -Inf]);

____________________________________________________________
   Diagnostic Information

Number of variables: 3

Functions 
Objective:                            @(c)-fML(c,Mdl,Y,Predictors,unitFlag,sqrtFlag,mexFlag,mexTvFlag,tol,ind,switchTime,precaution)
Gradient:                             finite-differencing
Hessian:                              bfgs

Constraints
Nonlinear constraints:                do not exist
 
Number of linear inequality constraints:    0
Number of linear equality constraints:      0
Number of lower bound constraints:          1
Number of upper bound constraints:          0

Algorithm selected
   interior-point


____________________________________________________________
   End diagnostic information
                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
    0       4    5.084683e+03    0.000e+00    5.096e+04
    1       8    6.405732e+02    0.000e+00    7.720e-02    1.457e+04
    2      12    6.405620e+02    0.000e+00    7.713e-02    1.058e-01
    3      16    6.405063e+02    0.000e+00    7.683e-02    5.285e-01
    4      20    6.402322e+02    0.000e+00    7.531e-02    2.632e+00
    5      24    6.389682e+02    0.000e+00    6.816e-02    1.289e+01
    6      28    6.346900e+02    0.000e+00    4.146e-02    5.821e+01
    7      32    6.314789e+02    0.000e+00    1.601e-02    8.771e+01
    8      36    6.307024e+02    0.000e+00    7.462e-03    5.266e+01
    9      40    6.304200e+02    0.000e+00    4.104e-03    4.351e+01
   10      44    6.303324e+02    0.000e+00    4.116e-03    3.167e+01
   11      48    6.303036e+02    0.000e+00    4.120e-03    2.418e+01
   12      52    6.302943e+02    0.000e+00    4.121e-03    1.813e+01
   13      56    6.302913e+02    0.000e+00    4.121e-03    1.377e+01
   14      60    6.302903e+02    0.000e+00    4.121e-03    1.054e+01
   15      64    6.302899e+02    0.000e+00    4.121e-03    8.514e+00
   16      68    6.302897e+02    0.000e+00    4.121e-03    6.414e+00
   17      72    6.302895e+02    0.000e+00    4.121e-03    1.473e+01
   18      77    6.302888e+02    0.000e+00    4.121e-03    3.693e+01
   19      82    6.302888e+02    0.000e+00    4.121e-03    9.659e+00
   20      86    6.302888e+02    0.000e+00    4.121e-03    3.747e+00
   21      90    6.302888e+02    0.000e+00    4.121e-03    1.636e+00
   22      94    6.302888e+02    0.000e+00    4.121e-03    7.311e-01
   23      98    6.302887e+02    0.000e+00    4.121e-03    2.570e+00
   24     102    6.302884e+02    0.000e+00    4.121e-03    5.536e+00
   25     106    6.302879e+02    0.000e+00    4.121e-03    4.704e+00
   26     110    6.302850e+02    0.000e+00    4.121e-03    1.319e+01
   27     114    6.302775e+02    0.000e+00    4.122e-03    1.043e+01
   28     118    6.302263e+02    0.000e+00    4.123e-03    3.985e+01
   29     122    6.300733e+02    0.000e+00    4.130e-03    5.389e+01
   30     126    6.285455e+02    0.000e+00    1.027e-02    4.891e+02

                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
   31     130    6.221921e+02    0.000e+00    8.010e-02    3.036e+03
   32     134    5.783191e+02    0.000e+00    3.672e-01    6.748e+03
   33     139    5.469912e+02    0.000e+00    8.592e-01    2.099e+03
   34     144    5.289896e+02    0.000e+00    2.206e+00    1.055e+03
   35     149    5.212317e+02    0.000e+00    5.408e+00    5.302e+02
   36     154    4.762810e+02    0.000e+00    1.009e+01    2.670e+02
   37     159    3.950959e+02    0.000e+00    1.412e+01    1.344e+02
   38     164    3.123782e+02    0.000e+00    4.446e+00    6.761e+01
   39     170    3.031269e+02    0.000e+00    1.426e+01    1.699e+01
   40     175    2.752681e+02    0.000e+00    2.376e+01    2.539e+01
   41     181    2.693457e+02    0.000e+00    3.818e+00    6.388e+00
   42     188    2.692219e+02    0.000e+00    9.327e+00    2.585e+00
   43     193    2.691856e+02    0.000e+00    2.360e+00    1.401e+00
   44     197    2.684493e+02    0.000e+00    1.064e+00    2.720e+00
   45     201    2.682262e+02    0.000e+00    1.040e+00    9.688e-01
   46     205    2.666842e+02    0.000e+00    9.162e+00    7.987e+00
   47     209    2.619443e+02    0.000e+00    2.550e+01    2.709e+01
   48     213    2.109143e+02    0.000e+00    4.111e+01    1.310e+02
   49     218    1.491443e+02    0.000e+00    1.686e+01    4.840e+01
   50     224    1.419609e+02    0.000e+00    2.894e+01    1.114e+01
   51     230    1.404849e+02    0.000e+00    4.590e+01    2.384e+00
   52     234    1.390759e+02    0.000e+00    3.303e+01    7.990e+00
   53     238    1.336615e+02    0.000e+00    2.421e+01    4.426e+00
   54     242    1.265960e+02    0.000e+00    2.718e+01    3.314e+00
   55     247    1.222370e+02    0.000e+00    5.928e+01    5.867e+00
   56     251    1.130348e+02    0.000e+00    9.454e+00    1.853e+00
   57     255    1.109453e+02    0.000e+00    4.978e+00    1.710e+00
   58     259    1.106272e+02    0.000e+00    3.155e+00    4.086e-01
   59     263    1.104927e+02    0.000e+00    1.494e+00    2.692e-01
   60     267    1.104775e+02    0.000e+00    1.889e-01    6.233e-02

                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
   61     271    1.104772e+02    0.000e+00    5.404e-02    3.187e-02
   62     275    1.104771e+02    0.000e+00    1.616e-02    8.914e-03
   63     279    1.104771e+02    0.000e+00    2.622e-03    6.138e-03
   64     283    1.104771e+02    0.000e+00    6.555e-04    4.428e-04
   65     287    1.104771e+02    0.000e+00    1.311e-04    1.071e-05
   66     291    1.104771e+02    0.000e+00    1.311e-06    2.817e-06
   67     295    1.104771e+02    0.000e+00    9.537e-07    1.194e-07

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

Method: Maximum likelihood (fmincon)
Effective Sample size:             60
Logarithmic  likelihood:     -110.477
Akaike   info criterion:      226.954
Bayesian info criterion:      233.287
           |      Coeff       Std Err    t Stat    Prob 
--------------------------------------------------------
 c(1)      |   0.59436       0.09408     6.31738  0     
 c(2)      |   1.52554       0.10758    14.17991  0     
 y <- z(1) | -24.26161       1.55730   -15.57930  0     
           |                                            
           |    Final State   Std Dev     t Stat   Prob 
 x(1)      |   2.54764        0           Inf     0     

Optimization information and a table of estimates and statistics output to the Command Window. EstMdl is an ssm model, and you can access its properties using dot notation.

Change Switching Time for Diffuse Model Estimation

For diffuse state-space models, the software implements the diffuse Kalman filter until it satisfies a regularity condition. To meet the condition, the software requires enough presample data. After the software satisfies the condition, it switches to using the standard Kalman filter. By default, the software determines how much presample data it requires and only uses as much as it needs. However, you can experiment by specifying other values for the SwitchTime name-value pair argument.

For this example, use the same data and model as in Estimate Diffuse State-Space Model Containing Regression Component.

Load the Nelson-Plosser data set.

load Data_NelsonPlosser

isNaN = any(ismissing(DataTable),2);
gnpn = DataTable.GNPN(~isNaN);
y = DataTable.UR(~isNaN);
T = size(gnpn,1);                          
Z = log(gnpn);

Specify the coefficient matrices.

A = NaN;
B = NaN;
C = 1;

Create the state-space model using dssm by supplying the coefficient matrices and specifying that the state values come from a diffuse distribution. The diffuse specification indicates complete ignorance about the moments of the initial distribution.

StateType = 2;
Mdl = dssm(A,B,C,'StateType',StateType);

Estimate the parameters several times. For each time, change the period to switch to the standard Kalman filter.

params0 = [0.3 0.2]; % Initial values chosen arbitrarily
Beta0 = 0.1;

[~,estParams1] = estimate(Mdl,y,params0,'Predictors',Z,'Display','off',...
    'Beta0',Beta0,'lb',[-Inf 0 -Inf],'SwitchTime',1);
[~,estParams5] = estimate(Mdl,y,params0,'Predictors',Z,'Display','off',...
    'Beta0',Beta0,'lb',[-Inf 0 -Inf],'SwitchTime',5);
[~,estParams10] = estimate(Mdl,y,params0,'Predictors',Z,'Display','off',...
    'Beta0',Beta0,'lb',[-Inf 0 -Inf],'SwitchTime',10);

Compare the parameter estimates.

estParams1

estParams1 = 1×3

    1.0101    1.3574  -24.4585

estParams5

estParams5 = 1×3

    1.0102    1.3832  -24.4852

estParams10

estParams10 = 1×3

    1.0094    1.2735  -26.4448

Because estimate uses fewer data points for subsequent estimations, the estimates are slightly different.

Limitations

• 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.

• If a diffuse state-space model has identifiability issues (i.e., at least two sets of distinct parameters values yield the same likelihood value for all observations), then estimate cannot properly initialize the diffuse states, and results are not predictable.

Tips

Constrained likelihood objective function maximization

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

• Good practice is to avoid equality and inequality constraints during optimization. For example, to constrain the parameter w to be positive, implicitly specify the state-space model using a parameter-to-matrix mapping function. Within the function, set w = exp(s) within the function. Then, use unconstrained optimization to estimate s. Consequently, s can assume any real value, but w must be positive.

Predictors and corresponding coefficients

• To include an overall mean to the observation model, include a column of 1s in Z_t.

• To account for predictor effects when you simulate, you must deflate the observations manually. To deflate the observations, use $$W_t=Y_t-Z_t\widehat{\beta }.$$

• 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 include the predictors as additional state variables. Since predictor data varies with time, a state-space model with predictors as states is time varying.

Diffuse State-Space Models

• You cannot use the square root method to filter and smooth diffuse state-space models. As a workaround, you can convert a diffuse state-space model to a standard state-space model using ssm, and then you can filter using the square root method. Upon conversion, all diffuse states have a finite, albeit large, initial distribution variance of 1e7.

• Best practice is to let estimate determine the value of SwitchTime. However, in rare cases, you might experience numerical issues during estimation, filtering, or smoothing diffuse state-space models. For such cases, try experimenting with various SwitchTime specifications, or consider a different model structure. In other words, simplify the model or verify that the model is identifiable. For example, convert the diffuse state-space model to a standard state-space model using ssm.

Additional Tips

• The software accommodates missing data. Indicate missing data using NaN values in the observed responses (Y).

• Good practice is 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.

Algorithms

• The Kalman filter accommodates missing data by not updating filtered state estimates corresponding to missing observations. In other words, suppose there is a missing observation at period t. Then, the state forecast for period t based on the previous t – 1 observations and filtered state for period t are equivalent.

• The diffuse Kalman filter requires presample data. If missing observations begin the time series, then the diffuse Kalman filter must gather enough nonmissing observations to initialize the diffuse states.

• For explicitly created state-space models, estimate applies all predictors to each response series. However, each response series has its own set of regression coefficients.

• If you do not specify optimization constraints, then estimate uses fminunc for unconstrained numerical estimation. If you specify any pair of optimization constraints, then estimate 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.

• estimate passes the name-value pair arguments Options, Aineq, bineq, Aeq, beq, lb, and ub directly to the optimizer fmincon or fminunc.

• estimate fits regression coefficients along with all other state-space model parameters. The software is flexible enough to allow applying constraints to the regression coefficients using constrained optimization options. For more details, see the Name,Value pair arguments and fmincon.

• If you set 'Univariate',true then, during the filtering algorithm, the software sequentially updates rather then updating all at once. This practice 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 = dssm(@(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.

• For diffuse state-space models, estimate usually switches from the diffuse Kalman filter to the standard Kalman filter when the number of cumulative observations and the number of diffuse states are equal.

References

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

Version History

Introduced in R2015b