kalmanFilter
(Model)
Run Kalman filter and smoother, and estimator of out-of-likelihood parameters
Syntax
[outputDb, outputModel, info] = kalmanFilter(inputModel, inputData, filterRange, ...)
Input arguments
inputModel
[ Model ]
A solved Model object whose state-space representation will be used to run a linear Kalman filter on the
inputData
observations.
inputData
[ struct | Dictionary ]
Input databank from which the observations for measurement variables on the
filterRange
will be taken.
filterRange
[ numeric | char ]
The range on which the Kalman filter will be run.
Output arguments
outputDb
[ struct | Dictionary ]
Output databank (possibly a nested databank) with the requested data; the type of output data are requested through the option
Output=
.
outputModel
[ Model ]
Model object with the std deviation of shocks updated (if
Relative=true
) and/or the out-of-likelihood parameters updated (ifOutlik=
is non-empty).
info
[ struct ]
Output information struct with the following fields:
.V
- Estimated variance scale factor if theRelative=
options is true; otherwiseV
is 1.
.Delta
- Struct with the estimates of out-of-likelihood parameters.
.PE
- Databank with prediction errors for measurement variables.
.SCov
- Sample covariance matrix of smoothed shocks; the covariance matrix is computed using shock estimates in periods that are included in the optionObjRange=
and, at the same time, contain at least one observation of measurement variables.
.init
- Initial conditions used in the Kalman filter;init{1}
is the initial mean of the vector of transformed state variables,init{2}
is the MSE matrix.
Options to control output data returned
"FlattenOutput=true
" [ true
| false
]
Make the
outputDb
as flat as possible by removing nested levels if they are empty or squeezing them if they only contain one field.
MatrixFormat="namedMatrix"
[ "namedMatrix"
| "numeric"
]
Format (class) output matrices included in the output
info
struct:
"namedMatrix"
- return NamedMatrix objects where the individual rows and columns have variable names attached
"numeric"
- return plain numeric arrays
MeanOnly=false
[ true
| false
]
Return the mean data (point estimates) only in the
outputDb
.
OutputData="smooth"
[ string | "predict"
| "filter"
| "smooth"
]
Choose which Kalman filter steps will be included in the
outputDb
:
"smooth"
- include data from the backward smoother (two-sided filtering)
"update"
- include data from the updating steep (one-sided filtering)
"predict"
- include data from the prediction step
ReturnMedian=true
[ true
| false
]
Return a databank with the median estimates of the model variables; the meians are calculated by delogarithmizing the log-variables; the medianss for other variables is identical to the means. This option only works when
MeanOnly=false
.
ReturnBreakdown=false
[ true
| false
]
Return contributions of prediction errors in measurement variables to the estimates of all variables and shocks. This option only works when
MeanOnly=false
.
ReturnMse=true
[ true
| false
]
Return MSE matrices for predetermined state variables; these can be used for settin up initial condition in subsequent call to another
kalmanFilter()
. This option only works whenMeanOnly=false
.
ReturnStd=true
[ true
| false
]
Return databank with std devs of model variables. This option only works when
MeanOnly=false
.
Options to control the calculation within the Kalman filter
Ahead=1
[ numeric ]
Calculate predictions up to
Ahead
periods ahead.
ChkFmse=false
[ 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=false
[ true
| false
]
Treat input and output data as deviations from balanced-growth path.
Dtrends=@auto
[ @auto
| true
| false
]
Measurement data contain deterministic trends;
@auto
meansDTrends=
will be set consistently withDeviation=
.
FmseCondTol=eps( )
[ numeric ]
Tolerance for the FMSE condition number test; not used unless
ChkFmse=true
.
InitCond="Stochastic"
[ "fixed"
| "optimal"
| "stochastic"
| struct ]
The method or data that will be used initialise the Kalman filter; user-supplied initial condition must be a databank with the mean values (in which case the MSE of the initial condition will be set to zero) or a nested databank containing sub-databanks named
.Mean
(or.Median
) and.MSE
.
UnitRootInitials="approxDiffuse"
[ "approxDiffuse"
| "fixedUnknown"
| "preiterate"
]
Method of initializing the MSE matrix for unit root variables; see Description.
Preiterate=0
[ numeric ]
Number of preiteration periods to initialize the MSE matrix for unit root variables when
UnitRootInitials="preiterate"
;Preiterate=0
is equivalent to"UnitRootInitials="fixedUnknown"
.
LastSmooth=Inf
[ numeric ]
Last date up to which to smooth data backward from the end of the filterRange;
Inf
means the smoother will run on the entire filterRange.
Outlik={ }
[ cellstr | empty ]
List of parameters in deterministic trends that will be estimated by concentrating them out of the likelihood function.
ObjFunc='-LogLik'
[ '-LogLik'
| 'PredErr'
]
Objective function computed; can be either minus the log likelihood function or weighted sum of prediction errors.
ObjRange=Inf
[ DateWrapper | Inf
]
The objective function will be computed on the specified filterRange only;
Inf
means the entire filter filterRange.
Relative=true
[ 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.
Weighting=[ ]
[ numeric | empty ]
Weighting vector or matrix for prediction errors when
ObjFunc='PredErr'
; empty means prediction errors are weighted equally.
Options for time-varying std deviations, correlations and means of shocks
Multiply=[ ]
[ struct | empty ]
Databank with time series of possibly time-varying multipliers for std deviations of shocks; the numbers supplied will be multiplied by the std deviations assigned in the model object to calculate the std deviations used in the filter. See Description.
Override=[ ]
[ struct | empty ]
Databank with time series for possibly time-varying paths for std deviations, correlations coefficients, or medians of shocks; these paths will override the values assigned in the model object. See Description.
Options for models with nonlinear equations simulated in prediction step
Simulate=false
[ false
| cell ]
Use the backend algorithms from the
simulate
function to run nonlinear simulation for each prediction step; specify options that will be passed intosimulate
when running a prediction step.
Description
Run a Kalman filter based on the inputModel
The option Ahead=
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).
-
databank (i.e. struct with fields for individual model variables) -- a databank 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.
Initialization of Unit Root (Nonstationary, Diffuse) Processes
Two methods are available to initialize unit-root (nonstationary, diffuse) elements in the state vector. In either case, the Kalman filter works with a system where the state vector is transformed so that its transition matrix is upper diagonal, with unit roots concentrated in the top left corner.
-
Fixed unknown quantities. This is the default method (for backward compatibility reasons), and corresponds to setting
InitUnit='FixedUnknown'
. The initial conditions for unit-root processes are treated as fixed unknown elements, and uses a Rosenberg (1973) algorithm to compute the optimal estimates of these. The algorithm is completely described in section 3.4.4. of Harvey (1990) "Forecasting, Structural Time Series Models and the Kalman Filter", Cambridge University Press. -
Approximate diffuse. The other method is used when
InitUnit='ApproxDiffuse'
. This alternative method treats the initial conditions for unit-root processes as a diffuse distribution (with infinitely large variances) approximating the true diffuse distribution by scaling up the appropriate elements of the initial covariance matrix (by a sufficiently large factor in proportion to the remaining parts of the matrix). This method is described e.g. in Harvey & Phillips (1979) "Maximum Likelihood Estimation of Regression Models with Autoregressive- Moving Average Disturbances" Biometrika 66(1).
Contributions of measurement variables to 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 databank will include one extra subdatabank called .cont
. In
the .cont
subdatabank, 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.
Time variation in std deviations, correlations and means of shocks
The options Multiply=
and Override=
modify the std deviations,
correlation coefficients or medians of shocks within the filter range,
allowing them also to vary over time. Create a time series and specify
observations for each std deviation, correlation coefficient, or median
(mean) that you want to deviate from the values currently assigned in the
model object. The time series supplied do not need to stretch over the
entire filter range: in the periods not specified, the values currently
assigned in the model object will be assumed.
The option Override=
simply overrides the std deviations, correlations
or medians (means) of the shocks whenever specified.
The option Mutliply=
can be used to supply multipliers for std
deviations. The numbers entered will be multiplied by the std deviations
to obtain the final std deviations used in the filter.
To alter the median (mean) of a shock, supply a time series named after
the shock itself. To alter the std deviation of a shock, use the name of
that std deviation, i.e. std_xxx
where xxx
is the name of the shock.
To alter the correlation coefficient between two shocks, use the name of
that correlation coefficient, i.e. corr_xxx__yyy
where xxx
and yyy
are the names of the shocks (mind the double underscore between xxx
and
yyy
).