# estimate

**Class: **dssm

Maximum likelihood parameter estimation of diffuse state-space models

## Syntax

## Description

estimates
the diffuse state-space model with additional options specified by
one or more `EstMdl`

= estimate(`Mdl`

,`Y`

,`params0`

,`Name,Value`

)`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.

`[`

additionally returns these
arguments using any of the input arguments in the previous syntaxes.`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

## Input Arguments

## Output Arguments

## Examples

## 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

`1`

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

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

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

The observed responsesMdl = dssm(@(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.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**

## See Also

`dssm`

| `optimoptions`

| `fmincon`

| `fminunc`

| `filter`

| `smooth`

| `refine`

### Topics

- Estimate Time-Varying Diffuse State-Space Model
- Estimate Random Parameter of State-Space Model
- Assess State-Space Model Stability Using Rolling Window Analysis
- Choose State-Space Model Specification Using Backtesting
- What Are State-Space Models?
- What Is the Kalman Filter?
- Rolling-Window Analysis of Time-Series Models