IRIS Toolbox Reference Manual

## filter

Kalman smoother and estimator of out-of-likelihood parameters

#### Syntax

    [M,Outp,V,Delta,PE,SCov] = filter(M,Inp,Range,...)

#### Input arguments

- `M` [ model ] - Solved model object.

- `Inp` [ struct | cell ] - Input database or datapack from which the measurement variables will be taken.

- `Range` [ numeric ] - Filter date range.

#### Output arguments

- `M` [ model ] - Model object with updates of std devs (if `'relative='` is true) and/or updates of out-of-likelihood parameters (if `'outoflik='` is non-empty).

- `Outp` [ struct | cell ] - Output struct with smoother or prediction data.

- `V` [ numeric ] - Estimated variance scale factor if the `'relative='` options is true; otherwise `V` is 1.

- `Delta` [ struct ] - Database with estimates of out-of-likelihood parameters.

- `PE` [ struct ] - Database with prediction errors for measurement variables.

- `SCov` [ numeric ] - Sample covariance matrix of smoothed shocks; the covariance matrix is computed using shock estimates in periods that are included in the option `'objrange='` and, at the same time, contain at least one observation of measurement variables.

#### Options

- `'ahead='` [ numeric | `1` ] - Predictions will be computed this number of period ahead.

- `'chkFmse='` [ `true` | `false` ] - Check the condition number of the forecast MSE matrix in each step of the Kalman filter, and return immediately if the matrix is ill-conditioned; see also the option `'fmseCondTol='`.

- `'condition='` [ char | cellstr | empty ] - List of conditioning measurement variables. Condition time t|t-1 prediction errors (that enter the likelihood function) on time t observations of these measurement variables.

- `'deviation='` [ `true` | `false` ] - Treat input and output data as deviations from balanced-growth path.

- `'dtrends='` [ 'auto' | `true` | `false` ] - Measurement data contain deterministic trends.

- `'data='` [ `'predict'` | `'smooth'` | `'predict,smooth'` ] - Return smoother data or prediction data or both.

- `'fmseCondTol='` [ `eps()` | numeric ] - Tolerance for the FMSE condition number test; not used unless `'chkFmse=' true`.

- `'initCond='` [ `'fixed'` | `'optimal'` | `'stochastic'` | struct ] - Method or data to initialise the Kalman filter; user-supplied initial condition must be a mean database or a mean-MSE struct.

- `'lastSmooth='` [ numeric | `Inf` ] - Last date up to which to smooth data backward from the end of the range; if `Inf` smoother will run on the entire range.

- `'meanOnly='` [ `true` | `false` ] - Return a plain database with mean data only; this option overrides the `'return*='` options, i.e. `'returnCont='`, `'returnMse='`, `'returnStd='`.

- `'outOfLik='` [ cellstr | empty ] - List of parameters in deterministic trends that will be estimated by concentrating them out of the likelihood function.

- `'objFunc='` [ `'-loglik'` | `'prederr'` ] - Objective function computed; can be either minus the log likelihood function or weighted sum of prediction errors.

- `'objRange='` [ numeric | `Inf` ] - The objective function will be computed on this subrange only; `Inf` means the entire filter range.

- `'precision='` [ `'double'` | `'single'` ] - Numeric precision to which output data will be stored; all calculations themselves always run to double precision.

- `'rollback='` [ numeric | empty ] - Date up to which to roll back individual observations on measurement variables from the end of the sample.

- `'relative='` [ `true` | `false` ] - Std devs of shocks assigned in the model object will be treated as relative std devs, and a common variance scale factor will be estimated.

- `'returnCont='` [ `true` | `false` ] - Return contributions of measurement variables to the estimates of all variables and shocks.

- `'returnMse='` [ `true` | `false` ] - Return MSE matrices for predetermined state variables; these can be used for settin up initial condition in subsequent call to another `filter` or `jforecast`.

- `'returnStd='` [ `true` | `false` ] - Return database with std devs of model variables.

- `'weighting='` [ numeric | empty ] - Weighting vector or matrix for prediction errors when `'objective=' 'prederr'`; empty means prediction errors are weighted equally.

#### Options for models with non-linearised equations

- `'nonlinearise='` [ numeric | `0` ] - If non-zero the prediction step in the Kalman filter will be run in an exact non-linear mode using the same technique as `model/simulate`.

- `'simulate='` [ cell | empty ] - Options passed in to `simulate` when invoking the non-linear simulation in the prediction step; only used when `nonlinearise=` is greater than `0`.

#### Description

The `'ahead='` and `'rollback='` options cannot be combined with one another, or with multiple data sets, or with multiple parameterisations.

##### Initial conditions in time domain

By default (with `'initCond=' 'stochastic'`), the Kalman filter starts from the model-implied asymptotic distribution. You can change this behaviour by setting the option `'initCond='` to one of the following four different values:

- `'fixed'` -- the filter starts from the model-implied asymptotic mean (steady state) but with no initial uncertainty. The initial condition is treated as a vector of fixed, non-stochastic, numbers.

- `'optimal'` -- the filter starts from a vector of fixed numbers that is estimated optimally (likelihood maximising).

- database (i.e. struct with fields for individual model variables) -- a database through which you supply the mean for all the required initial conditions, see help on `model/get` for how to view the list of required initial conditions.

- mean-mse struct (i.e. struct with fields `.mean` and `.mse`) -- a struct through which you supply the mean and MSE for all the required initial conditions.

##### Contributions of measurement variables to the estimates of all variables

Use the option `'returnCont=' true` to request the decomposition of measurement variables, transition variables, and shocks into the contributions of each individual measurement variable. The resulting output database will include one extra subdatabase called `.cont`. In the `.cont` subdatabase, each time series will have Ny columns where Ny is the number of measurement variables in the model. The k-th column will be the contribution of the observations on the k-th measurement variable.

The contributions are additive for linearised variables, and multiplicative for log-linearised variables (log-variables). The difference between the actual path for a particular variable and the sum of the contributions (or their product in the case of log-varibles) is due to the effect of constant terms and deterministic trends.

#### Example

IRIS Toolbox. Copyright © 2007—2013 Jaromir Benes.