# estimate

Maximum likelihood parameter estimation of state-space models

## Syntax

``EstMdl = estimate(Mdl,Y,params0)``
``EstMdl = estimate(Mdl,Y,params0,Name,Value)``
``````[EstMdl,estParams,EstParamCov,logL,Output] = estimate(___)``````

## Description

example

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

example

````EstMdl = estimate(Mdl,Y,params0,Name,Value)` estimates the 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.```

example

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

## Examples

collapse all

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

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

`${x}_{t}=0.5{x}_{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;`

`B = NaN;`

Specify the measurement-sensitivity coefficient matrix.

`C = 1;`

Specify the observation-innovation coefficient matrix

`D = NaN;`

Specify the state-space model using the coefficient matrices. Also, specify the initial state mean, variance, and distribution (which is stationary).

```Mean0 = 0; Cov0 = 10; StateType = 0; Mdl = ssm(A,B,C,D,'Mean0',Mean0,'Cov0',Cov0,'StateType',StateType);```

`Mdl` is an `ssm` model. Verify that the model is correctly specified using the 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) Sample size: 100 Logarithmic likelihood: -140.532 Akaike info criterion: 287.064 Bayesian info criterion: 294.879 | Coeff Std Err t Stat Prob ------------------------------------------------- c(1) | 0.45425 0.19870 2.28611 0.02225 c(2) | 0.89013 0.30359 2.93205 0.00337 c(3) | 0.38750 0.57858 0.66975 0.50302 | | Final State Std Dev t Stat Prob x(1) | 1.52989 0.35621 4.29498 0.00002 ```
```EstMdl = State-space model type: ssm 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.45)x1(t-1) + (0.89)u1(t) Observation equation: y1(t) = x1(t) + (0.39)e1(t) Initial state distribution: Initial state means x1 0 Initial state covariance matrix x1 x1 10 State types x1 Stationary ```

`EstMdl` is an `ssm` 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.4543 ```

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

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

`$\begin{array}{l}\left[\begin{array}{c}{x}_{1,t}\\ {x}_{2,t}\end{array}\right]=\left[\begin{array}{cc}\varphi & \theta \\ 0& 0\end{array}\right]\left[\begin{array}{c}{x}_{1,t-1}\\ {x}_{2,t-1}\end{array}\right]+\left[\begin{array}{c}1\\ 1\end{array}\right]{u}_{1,t}\\ {y}_{t}-\beta {Z}_{t}={x}_{1,t}+\sigma {\epsilon }_{t},\end{array}$`

where:

• ${x}_{1,t}$ is the change in the unemployment rate at time t.

• ${x}_{2,t}$ is a dummy state for the MA(1) effect.

• ${y}_{1,t}$ is the observed change in the unemployment being deflated by the growth rate of nGNP (${Z}_{t}$).

• ${u}_{1,t}$ is the Gaussian series of state disturbances having mean 0 and standard deviation 1.

• ${\epsilon }_{t}$ is the Gaussian series of observation innovations having mean 0 and 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 the first difference of each. Also, remove the starting `NaN` values from each series.

```isNaN = any(ismissing(DataTable),2); % Flag periods containing NaNs gnpn = DataTable.GNPN(~isNaN); u = DataTable.UR(~isNaN); T = size(gnpn,1); % Sample size Z = [ones(T-1,1) diff(log(gnpn))]; y = diff(u);```

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

Specify the state-transition coefficient matrix.

`A = [NaN NaN; 0 0];`

`B = [1; 1];`

Specify the measurement-sensitivity coefficient matrix.

`C = [1 0];`

Specify the observation-innovation coefficient matrix.

`D = NaN;`

Specify the state-space model using `ssm`.

`Mdl = ssm(A,B,C,D);`

Estimate the model 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 0.1]; % Chosen arbitrarily EstMdl = estimate(Mdl,y,params0,'Predictors',Z,'Display','full',... 'Beta0',[0.1 0.2],'lb',[-Inf,-Inf,0,-Inf,-Inf]);```
```____________________________________________________________ Diagnostic Information Number of variables: 5 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 6 2.579611e+02 0.000e+00 4.601e+01 1 20 2.556482e+02 0.000e+00 3.652e+01 1.392e-01 2 27 2.503349e+02 0.000e+00 4.319e+01 1.908e-01 3 35 2.379654e+02 0.000e+00 1.294e+01 1.083e+01 4 41 1.946975e+02 0.000e+00 1.947e+01 7.160e+00 5 47 1.600478e+02 0.000e+00 2.123e+02 1.185e+01 6 53 1.257101e+02 0.000e+00 9.100e+01 1.584e+00 7 59 1.112365e+02 0.000e+00 1.019e+01 2.431e+00 8 65 1.057826e+02 0.000e+00 1.322e+01 1.608e+00 9 71 1.038437e+02 0.000e+00 8.182e+00 1.270e+00 10 79 1.016763e+02 0.000e+00 4.046e+00 1.017e+00 11 85 1.008654e+02 0.000e+00 3.983e+00 9.373e-01 12 91 1.001161e+02 0.000e+00 2.640e+00 1.330e+00 13 97 9.984377e+01 0.000e+00 1.216e+00 2.509e-01 14 103 9.974672e+01 0.000e+00 9.290e-01 4.018e-01 15 109 9.973448e+01 0.000e+00 7.202e-01 1.514e-01 16 115 9.973150e+01 0.000e+00 5.665e-01 7.941e-02 17 121 9.973097e+01 0.000e+00 5.594e-01 2.317e-03 18 127 9.973033e+01 0.000e+00 5.217e-01 2.628e-03 19 133 9.972771e+01 0.000e+00 3.272e-01 1.239e-02 20 139 9.972600e+01 0.000e+00 2.392e-01 1.381e-02 21 145 9.972538e+01 0.000e+00 1.024e-01 1.115e-02 22 151 9.972525e+01 0.000e+00 1.000e-01 4.115e-03 23 157 9.972458e+01 0.000e+00 2.085e-02 7.839e-03 24 163 9.972454e+01 0.000e+00 1.740e-03 2.359e-03 25 169 9.972454e+01 0.000e+00 2.000e-04 1.739e-04 26 175 9.972454e+01 0.000e+00 9.537e-06 3.271e-05 27 181 9.972454e+01 0.000e+00 2.000e-06 4.559e-07 28 188 9.972454e+01 0.000e+00 1.010e-06 2.292e-07 29 195 9.972454e+01 0.000e+00 2.014e-06 2.440e-07 30 201 9.972454e+01 0.000e+00 1.949e-06 1.012e-07 First-order Norm of Iter F-count f(x) Feasibility optimality step 31 207 9.972454e+01 0.000e+00 9.948e-07 2.062e-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. Method: Maximum likelihood (fmincon) Sample size: 61 Logarithmic likelihood: -99.7245 Akaike info criterion: 209.449 Bayesian info criterion: 220.003 | Coeff Std Err t Stat Prob ---------------------------------------------------------- c(1) | -0.34098 0.29608 -1.15164 0.24948 c(2) | 1.05003 0.41377 2.53771 0.01116 c(3) | 0.48592 0.36790 1.32079 0.18657 y <- z(1) | 1.36121 0.22338 6.09358 0 y <- z(2) | -24.46711 1.60018 -15.29024 0 | | Final State Std Dev t Stat Prob x(1) | 1.01264 0.44690 2.26592 0.02346 x(2) | 0.77718 0.58917 1.31912 0.18713 ```

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.

The software implements the Kalman filter using the covariance filter by default, but you can specify to use the square-root filter instead. This example compares estimates from each method using simulated data.

Suppose that a latent process is an AR(1). The state equation is

`${x}_{t}=0.5{x}_{t-1}+{u}_{t},$`

where ${u}_{t}$ is Gaussian with mean 0 and standard deviation 0.3.

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',0.3^2); 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. The observation equation is

`${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 parameter, 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 coefficient matrix. Use `NaN` values for unknown parameters.

`A = NaN;`

`B = NaN;`

Specify the measurement-sensitivity coefficient matrix.

`C = 1;`

Specify the observation-innovation coefficient matrix.

`D = NaN;`

Specify the state-space model using the coefficient matrices. Also, specify the initial state mean, variance, and distribution (which is stationary).

```Mean0 = 0; Cov0 = 10; StateType = 0; Mdl = ssm(A,B,C,D,'Mean0',Mean0,'Cov0',Cov0,'StateType',StateType);```

`Mdl` is an `ssm` model.

Estimate the parameters using `estimate` two ways:

• Using the default, simple Kalman filter

• Using the square root filter variation

In both cases, specify that no output should be returned to the Command Window. This is good practice if you plan on running `estimate` multiple times (such as a Monte Carlo simulation).

```params0 = [10,10,10]; [~,estParamsSKF,EstParamCovSKF,logLSKF,OutputSKF] = estimate(Mdl,y,params0,... 'Display','off'); [~,estParamsSR,EstParamCovSR,logLSR,OutputSR] = estimate(Mdl,y,params0,... 'Squareroot',true,'Display','off');```

Check that the algorithms converged properly by printing the exit flag properties of `OutputSKF` and `OutputSR`.

`exitFlagSKF = OutputSKF.ExitFlag`
```exitFlagSKF = 1 ```
`exitFlagSR = OutputSR.ExitFlag`
```exitFlagSR = 1 ```

Both algorithms have an exit flag of `1`, which indicates that the software met the convergence criteria.

Compare the estimates from each algorithm.

`fprintf('\n Parameter Estimates\n')`
``` Parameter Estimates ```
```table(estParamsSKF',estParamsSR','VariableNames',... {'SimpleKalmanFilter','SquarerootFilter'})```
```ans=3×2 table SimpleKalmanFilter SquarerootFilter __________________ ________________ 0.51057 0.51057 0.23436 0.23436 -0.17904 -0.17904 ```
`fprintf('\nEstimated Parameter Covariance Matrix\n')`
```Estimated Parameter Covariance Matrix ```
```table(EstParamCovSKF,EstParamCovSR,'VariableNames',... {'SimpleKalmanFilter','SquarerootFilter'})```
```ans=3×2 table SimpleKalmanFilter SquarerootFilter ___________________________________ ___________________________________ 0.036669 -0.013302 -0.014012 0.036669 -0.013302 -0.014012 -0.013302 0.0070187 0.0072533 -0.013302 0.0070187 0.0072533 -0.014012 0.0072533 0.0089019 -0.014012 0.0072533 0.0089019 ```

In this case, the results are the same.

If you use the default, covariance filter method, and you run into numerical problems during estimation, filtering, or smoothing, try using the squareroot method.

## Input Arguments

collapse all

Standard state-space model containing unknown parameters, specified as an `ssm` model object returned by `ssm`.

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

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

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

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 `NaN`s in the state-space model matrices and initial state values. The software searches for `NaN`s 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

collapse all

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`

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

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

Example: `'CovMethod','sandwich'`

Data Types: `char`

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

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

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

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 (Zt) 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`

Square root filter method flag, specified as the comma-separated pair consisting of `'SquareRoot'` and `true` or `false`. If `true`, then `estimate` applies the square root filter method when implementing the Kalman filter.

If you suspect that the eigenvalues of the filtered state or forecasted observation covariance matrices are close to zero, then specify `'SquareRoot',true`. The square root filter is robust to numerical issues arising from finite the precision of calculations, but requires more computational resources.

Example: `'SquareRoot',true`

Data Types: `logical`

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 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, DtDt' must be diagonal, where Dt, 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

collapse all

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.

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`

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`

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`

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`

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

collapse all

State-space model containing the parameter estimates, returned as an `ssm` model object.

`estimate` uses the Kalman filter and maximum likelihood to estimate all unknown parameters.

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

For the estimated regression coefficient matrix, see `estParams`.

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 might need to supply the appropriate data.

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

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

Optimized loglikelihood value, returned as a scalar.

Missing observations do not contribute to the loglikelihood.

Optimization information, returned as a structure array.

This table describes the fields of `Output`.

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

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

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

• 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}\stackrel{^}{\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.

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

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

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