Kalman filter¶

Note that this class inherits from Representation; its documentation should be consulted for additional methods available in KalmanFilter objects.

class dismalpy.ssm.kalman_filter.KalmanFilter(k_endog, k_states, k_posdef=None, loglikelihood_burn=0, tolerance=1e-19, results_class=None, **kwargs)[source]¶

State space representation of a time series process, with Kalman filter

Parameters:

k_endog : array_like or integer

The observed time-series process \(y\) if array like or the number of variables in the process if an integer.

k_states : int

The dimension of the unobserved state process.

k_posdef : int, optional

The dimension of a guaranteed positive definite covariance matrix describing the shocks in the measurement equation. Must be less than or equal to k_states. Default is k_states.

loglikelihood_burn : int, optional

The number of initial periods during which the loglikelihood is not recorded. Default is 0.

tolerance : float, optional

The tolerance at which the Kalman filter determines convergence to steady-state. Default is 1e-19.

results_class : class, optional

Default results class to use to save filtering output. Default is FilterResults. If specified, class must extend from FilterResults.

**kwargs

Keyword arguments may be used to provide values for the filter, inversion, and stability methods. See set_filter_method, set_inversion_method, and set_stability_method. Keyword arguments may be used to provide default values for state space matrices. See Representation for more details.

Notes

There are several types of options available for controlling the Kalman filter operation. All options are internally held as bitmasks, but can be manipulated by setting class attributes, which act like boolean flags. For more information, see the set_* class method documentation. The options are:

filter_method: The filtering method controls aspects of which Kalman filtering approach will be used.
inversion_method: The Kalman filter may contain one matrix inversion: that of the forecast error covariance matrix. The inversion method controls how and if that inverse is performed.
stability_method: The Kalman filter is a recursive algorithm that may in some cases suffer issues with numerical stability. The stability method controls what, if any, measures are taken to promote stability.
conserve_memory: By default, the Kalman filter computes a number of intermediate matrices at each iteration. The memory conservation options control which of those matrices are stored.
filter_timing: By default, the Kalman filter follows Durbin and Koopman, 2012, in initializing the filter with predicted values. Kim and Nelson, 1999, instead initialize the filter with filtered values, which is essentially just a different timing convention.

The filter_method and inversion_method options intentionally allow the possibility that multiple methods will be indicated. In the case that multiple methods are selected, the underlying Kalman filter will attempt to select the optional method given the input data.

For example, it may be that INVERT_UNIVARIATE and SOLVE_CHOLESKY are indicated (this is in fact the default case). In this case, if the endogenous vector is 1-dimensional (k_endog = 1), then INVERT_UNIVARIATE is used and inversion reduces to simple division, and if it has a larger dimension, the Cholesky decomposition along with linear solving (rather than explicit matrix inversion) is used. If only SOLVE_CHOLESKY had been set, then the Cholesky decomposition method would always be used, even in the case of 1-dimensional data.

conserve_memory = 0¶: (int) Memory conservation bitmask.

filter(filter_method=None, inversion_method=None, stability_method=None, conserve_memory=None, filter_timing=None, tolerance=None, loglikelihood_burn=None, results=None)[source]¶

Apply the Kalman filter to the statespace model.

Parameters:

filter_method : int, optional

Determines which Kalman filter to use. Default is conventional.

inversion_method : int, optional

Determines which inversion technique to use. Default is by Cholesky decomposition.

stability_method : int, optional

Determines which numerical stability techniques to use. Default is to enforce symmetry of the predicted state covariance matrix.

conserve_memory : int, optional

Determines what output from the filter to store. Default is to store everything.

filter_timing : int, optional

Determines the timing convention of the filter. Default is that from Durbin and Koopman (2012), in which the filter is initialized with predicted values.

tolerance : float, optional

The tolerance at which the Kalman filter determines convergence to steady-state. Default is 1e-19.

loglikelihood_burn : int, optional

The number of initial periods during which the loglikelihood is not recorded. Default is 0.

results : class, object, or {‘loglikelihood’}, optional

If a class which is a subclass of FilterResults, then that class is instantiated and returned with the result of filtering. Classes must subclass FilterResults. If an object, then that object is updated with the new filtering results. If the string ‘loglikelihood’, then only the loglikelihood is returned as an ndarray. If None, then the default results object is updated with the result of filtering.

filter_augmented = False¶: (bool) Flag for augmented Kalman filtering. Not implemented.

filter_collapsed = False¶: (bool) Flag for Kalman filtering with collapsed observation vector.

filter_conventional = False¶: (bool) Flag for conventional Kalman filtering.

filter_exact_initial = False¶: (bool) Flag for exact initial Kalman filtering. Not implemented.

filter_extended = False¶: (bool) Flag for extended Kalman filtering. Not implemented.

filter_method = 1¶: (int) Filtering method bitmask.

filter_square_root = False¶: (bool) Flag for square-root Kalman filtering. Not implemented.

filter_timing = 0¶: (int) Filter timing.

filter_univariate = False¶: (bool) Flag for univariate filtering of multivariate observation vector.

filter_unscented = False¶: (bool) Flag for unscented Kalman filtering. Not implemented.

impulse_responses(steps=1, impulse=0, orthogonalized=False, cumulative=False, **kwargs)[source]¶

Impulse response function

Parameters:

steps : int, optional

The number of steps for which impulse responses are calculated. Default is 1. Note that the initial impulse is not counted as a step, so if steps=1, the output will have 2 entries.

impulse : int or array_like

If an integer, the state innovation to pulse; must be between 0 and k_posdef-1. Alternatively, a custom impulse vector may be provided; must be shaped k_posdef x 1.

orthogonalized : boolean, optional

Whether or not to perform impulse using orthogonalized innovations. Note that this will also affect custum impulse vectors. Default is False.

cumulative : boolean, optional

Whether or not to return cumulative impulse responses. Default is False.

**kwargs

If the model is time-varying and steps is greater than the number of observations, any of the state space representation matrices that are time-varying must have updated values provided for the out-of-sample steps. For example, if design is a time-varying component, nobs is 10, and steps is 15, a (k_endog x k_states x 5) matrix must be provided with the new design matrix values.

Returns:

impulse_responses : array

Responses for each endogenous variable due to the impulse given by the impulse argument. A (steps + 1 x k_endog) array.

Notes

Intercepts in the measurement and state equation are ignored when calculating impulse responses.

inversion_method = 9¶: (int) Inversion method bitmask.

invert_cholesky = False¶: (bool) Flag for Cholesky inversion method.

invert_lu = False¶: (bool) Flag for LU inversion method.

invert_numpy = False¶: (bool) Flag for inversion using numpy (not recommended).

invert_univariate = False¶: (bool) Flag for univariate inversion method (recommended).

loglike(loglikelihood_burn=None, **kwargs)[source]¶

Calculate the loglikelihood associated with the statespace model.

Parameters:

loglikelihood_burn : int, optional

The number of initial periods during which the loglikelihood is not recorded. Default is 0.

**kwargs

Additional keyword arguments to pass to the Kalman filter. See KalmanFilter.filter for more details.

Returns:

loglike : float

The joint loglikelihood.

loglikeobs(loglikelihood_burn=None, **kwargs)[source]¶

Calculate the loglikelihood for each observation associated with the statespace model.

Parameters:

loglikelihood_burn : int, optional

The number of initial periods during which the loglikelihood is not recorded. Default is 0.

**kwargs

Additional keyword arguments to pass to the Kalman filter. See KalmanFilter.filter for more details.

Returns:

loglike : array of float

Array of loglikelihood values for each observation.

Notes

If loglikelihood_burn is positive, then the entries in the returned loglikelihood vector are set to be zero for those initial time periods.

memory_conserve = False¶: (bool) Flag to conserve the maximum amount of memory.

memory_no_filtered = False¶: (bool) Flag to prevent storing filtered state and covariance matrices.

memory_no_forecast = False¶: (bool) Flag to prevent storing forecasts.

memory_no_gain = False¶: (bool) Flag to prevent storing the Kalman gain matrices.

memory_no_likelihood = False¶: (bool) Flag to prevent storing likelihood values for each observation.

memory_no_predicted = False¶: (bool) Flag to prevent storing predicted state and covariance matrices.

memory_no_smoothing = False¶: (bool) Flag to prevent storing temporary values used in smoothing.

memory_store_all = False¶: (bool) Flag for storing all intermediate results in memory (default).

set_conserve_memory(conserve_memory=None, **kwargs)[source]¶

Set the memory conservation method

By default, the Kalman filter computes a number of intermediate matrices at each iteration. The memory conservation options control which of those matrices are stored.

Parameters:

conserve_memory : integer, optional

Bitmask value to set the memory conservation method to. See notes for details.

**kwargs

Keyword arguments may be used to influence the memory conservation method by setting individual boolean flags. See notes for details.

Notes

The memory conservation method is defined by a collection of boolean flags, and is internally stored as a bitmask. The methods available are:

MEMORY_STORE_ALL = 0: Store all intermediate matrices. This is the default value.
MEMORY_NO_FORECAST = 0x01: Do not store the forecast, forecast error, or forecast error covariance matrices. If this option is used, the predict method from the results class is unavailable.
MEMORY_NO_PREDICTED = 0x02: Do not store the predicted state or predicted state covariance matrices.
MEMORY_NO_FILTERED = 0x04: Do not store the filtered state or filtered state covariance matrices.
MEMORY_NO_LIKELIHOOD = 0x08: Do not store the vector of loglikelihood values for each observation. Only the sum of the loglikelihood values is stored.
MEMORY_NO_GAIN = 0x10: Do not store the Kalman gain matrices.
MEMORY_NO_SMOOTHING = 0x20: Do not store temporary variables related to Klaman smoothing. If this option is used, smoothing is unavailable.
MEMORY_CONSERVE: Do not store any intermediate matrices.

If the bitmask is set directly via the conserve_memory argument, then the full method must be provided.

If keyword arguments are used to set individual boolean flags, then the lowercase of the method must be used as an argument name, and the value is the desired value of the boolean flag (True or False).

Note that the memory conservation method may also be specified by directly modifying the class attributes which are defined similarly to the keyword arguments.

The default memory conservation method is MEMORY_STORE_ALL, so that all intermediate matrices are stored.

Examples

>>> mod = dp.ssm.KalmanFilter(1,1)
>>> mod.conserve_memory
0
>>> mod.memory_no_predicted
False
>>> mod.memory_no_predicted = True
>>> mod.conserve_memory
2
>>> mod.set_conserve_memory(memory_no_filtered=True,
                            memory_no_forecast=True)
>>> mod.conserve_memory
7

set_filter_method(filter_method=None, **kwargs)[source]¶

Set the filtering method

The filtering method controls aspects of which Kalman filtering approach will be used.

Parameters:

filter_method : integer, optional

Bitmask value to set the filter method to. See notes for details.

**kwargs

Keyword arguments may be used to influence the filter method by setting individual boolean flags. See notes for details.

Notes

The filtering method is defined by a collection of boolean flags, and is internally stored as a bitmask. The methods available are:

FILTER_CONVENTIONAL = 0x01: Conventional Kalman filter.
FILTER_UNIVARIATE = 0x10: Univariate approach to Kalman filtering. Overrides conventional method if both are specified.
FILTER_COLLAPSED = 0x20: Collapsed approach to Kalman filtering. Will be used in addition to conventional or univariate filtering.

If the bitmask is set directly via the filter_method argument, then the full method must be provided.

If keyword arguments are used to set individual boolean flags, then the lowercase of the method must be used as an argument name, and the value is the desired value of the boolean flag (True or False).

Note that the filter method may also be specified by directly modifying the class attributes which are defined similarly to the keyword arguments.

The default filtering method is FILTER_CONVENTIONAL.

Examples

>>> mod = dp.ssm.KalmanFilter(1,1)
>>> mod.filter_method
1
>>> mod.filter_conventional
True
>>> mod.filter_univariate = True
>>> mod.filter_method
17
>>> mod.set_filter_method(filter_univariate=False,
                          filter_collapsed=True)
>>> mod.filter_method
33
>>> mod.set_filter_method(filter_method=1)
>>> mod.filter_conventional
True
>>> mod.filter_univariate
False
>>> mod.filter_collapsed
False
>>> mod.filter_univariate = True
>>> mod.filter_method
17

set_filter_timing(alternate_timing=None, **kwargs)[source]¶

Set the filter timing convention

By default, the Kalman filter follows Durbin and Koopman, 2012, in initializing the filter with predicted values. Kim and Nelson, 1999, instead initialize the filter with filtered values, which is essentially just a different timing convention.

Parameters:

alternate_timing : integer, optional

Whether or not to use the alternate timing convention. Default is unspecified.

**kwargs

Keyword arguments may be used to influence the memory conservation method by setting individual boolean flags. See notes for details.

set_inversion_method(inversion_method=None, **kwargs)[source]¶

Set the inversion method

The Kalman filter may contain one matrix inversion: that of the forecast error covariance matrix. The inversion method controls how and if that inverse is performed.

Parameters:

inversion_method : integer, optional

Bitmask value to set the inversion method to. See notes for details.

**kwargs

Keyword arguments may be used to influence the inversion method by setting individual boolean flags. See notes for details.

Notes

The inversion method is defined by a collection of boolean flags, and is internally stored as a bitmask. The methods available are:

INVERT_UNIVARIATE = 0x01: If the endogenous time series is univariate, then inversion can be performed by simple division. If this flag is set and the time series is univariate, then division will always be used even if other flags are also set.
SOLVE_LU = 0x02: Use an LU decomposition along with a linear solver (rather than ever actually inverting the matrix).
INVERT_LU = 0x04: Use an LU decomposition along with typical matrix inversion.
SOLVE_CHOLESKY = 0x08: Use a Cholesky decomposition along with a linear solver.
INVERT_CHOLESKY = 0x10: Use an Cholesky decomposition along with typical matrix inversion.
INVERT_NUMPY = 0x20: Use the numpy inversion function. This is not recommended except for testing as it will be substantially slower than the other methods.

If the bitmask is set directly via the inversion_method argument, then the full method must be provided.

If keyword arguments are used to set individual boolean flags, then the lowercase of the method must be used as an argument name, and the value is the desired value of the boolean flag (True or False).

Note that the inversion method may also be specified by directly modifying the class attributes which are defined similarly to the keyword arguments.

The default inversion method is INVERT_UNIVARIATE | SOLVE_CHOLESKY

Several things to keep in mind are:

If the filtering method is specified to be univariate, then simple division is always used regardless of the dimension of the endogenous time series.
Cholesky decomposition is about twice as fast as LU decomposition, but it requires that the matrix be positive definite. While this should generally be true, it may not be in every case.
Using a linear solver rather than true matrix inversion is generally faster and is numerically more stable.

Examples

>>> mod = dp.ssm.KalmanFilter(1,1)
>>> mod.inversion_method
1
>>> mod.solve_cholesky
True
>>> mod.invert_univariate
True
>>> mod.invert_lu
False
>>> mod.invert_univariate = False
>>> mod.inversion_method
8
>>> mod.set_inversion_method(solve_cholesky=False,
                             invert_cholesky=True)
>>> mod.inversion_method
16

set_stability_method(stability_method=None, **kwargs)[source]¶

Set the numerical stability method

The Kalman filter is a recursive algorithm that may in some cases suffer issues with numerical stability. The stability method controls what, if any, measures are taken to promote stability.

Parameters:

stability_method : integer, optional

Bitmask value to set the stability method to. See notes for details.

**kwargs

Keyword arguments may be used to influence the stability method by setting individual boolean flags. See notes for details.

Notes

The stability method is defined by a collection of boolean flags, and is internally stored as a bitmask. The methods available are:

STABILITY_FORCE_SYMMETRY = 0x01: If this flag is set, symmetry of the predicted state covariance matrix is enforced at each iteration of the filter, where each element is set to the average of the corresponding elements in the upper and lower triangle.

If the bitmask is set directly via the stability_method argument, then the full method must be provided.

If keyword arguments are used to set individual boolean flags, then the lowercase of the method must be used as an argument name, and the value is the desired value of the boolean flag (True or False).

Note that the stability method may also be specified by directly modifying the class attributes which are defined similarly to the keyword arguments.

The default stability method is STABILITY_FORCE_SYMMETRY

Examples

>>> mod = dp.ssm.KalmanFilter(1,1)
>>> mod.stability_method
1
>>> mod.stability_force_symmetry
True
>>> mod.stability_force_symmetry = False
>>> mod.stability_method
0

simulate(nsimulations, measurement_shocks=None, state_shocks=None, initial_state=None)[source]¶

Simulate a new time series following the state space model

Parameters:

nsimulations : int

The number of observations to simulate. If the model is time-invariant this can be any number. If the model is time-varying, then this number must be less than or equal to the number

measurement_shocks : array_like, optional

If specified, these are the shocks to the measurement equation, \(\varepsilon_t\). If unspecified, these are automatically generated using a pseudo-random number generator. If specified, must be shaped nsimulations x k_endog, where k_endog is the same as in the state space model.

state_shocks : array_like, optional

If specified, these are the shocks to the state equation, \(\eta_t\). If unspecified, these are automatically generated using a pseudo-random number generator. If specified, must be shaped nsimulations x k_posdef where k_posdef is the same as in the state space model.

initial_state : array_like, optional

If specified, this is the state vector at time zero, which should be shaped (k_states x 1), where k_states is the same as in the state space model. If unspecified, but the model has been initialized, then that initialization is used. If unspecified and the model has not been initialized, then a vector of zeros is used. Note that this is not included in the returned simulated_states array.

Returns:

simulated_obs : array

An (nsimulations x k_endog) array of simulated observations.

simulated_states : array

An (nsimulations x k_states) array of simulated states.

solve_cholesky = False¶: (bool) Flag for Cholesky and linear solver inversion method (recommended).

solve_lu = False¶: (bool) Flag for LU and linear solver inversion method.

stability_force_symmetry = False¶: (bool) Flag for enforcing covariance matrix symmetry

stability_method = 1¶: (int) Stability method bitmask.

timing_init_filtered = False¶: (bool) Flag for the alternate timing convention (Kim and Nelson, 2012).

timing_init_predicted = False¶: (bool) Flag for the default timing convention (Durbin and Koopman, 2012).

class dismalpy.ssm.kalman_filter.FilterResults(model)[source]¶

Results from applying the Kalman filter to a state space model.

Parameters:

model : Representation

A Statespace representation

Attributes

nobs	(int) Number of observations.
k_endog	(int) The dimension of the observation series.
k_states	(int) The dimension of the unobserved state process.
k_posdef	(int) The dimension of a guaranteed positive definite covariance matrix describing the shocks in the measurement equation.
dtype	(dtype) Datatype of representation matrices
prefix	(str) BLAS prefix of representation matrices
shapes	(dictionary of name,tuple) A dictionary recording the shapes of each of the representation matrices as tuples.
endog	(array) The observation vector.
design	(array) The design matrix, \(Z\).
obs_intercept	(array) The intercept for the observation equation, \(d\).
obs_cov	(array) The covariance matrix for the observation equation \(H\).
transition	(array) The transition matrix, \(T\).
state_intercept	(array) The intercept for the transition equation, \(c\).
selection	(array) The selection matrix, \(R\).
state_cov	(array) The covariance matrix for the state equation \(Q\).
missing	(array of bool) An array of the same size as endog, filled with boolean values that are True if the corresponding entry in endog is NaN and False otherwise.
nmissing	(array of int) An array of size nobs, where the ith entry is the number (between 0 and k_endog) of NaNs in the ith row of the endog array.
time_invariant	(bool) Whether or not the representation matrices are time-invariant
initialization	(str) Kalman filter initialization method.
initial_state	(array_like) The state vector used to initialize the Kalamn filter.
initial_state_cov	(array_like) The state covariance matrix used to initialize the Kalamn filter.
filter_method	(int) Bitmask representing the Kalman filtering method
inversion_method	(int) Bitmask representing the method used to invert the forecast error covariance matrix.
stability_method	(int) Bitmask representing the methods used to promote numerical stability in the Kalman filter recursions.
conserve_memory	(int) Bitmask representing the selected memory conservation method.
filter_timing	(int) Whether or not to use the alternate timing convention.
tolerance	(float) The tolerance at which the Kalman filter determines convergence to steady-state.
loglikelihood_burn	(int) The number of initial periods during which the loglikelihood is not recorded.
converged	(bool) Whether or not the Kalman filter converged.
period_converged	(int) The time period in which the Kalman filter converged.
filtered_state	(array) The filtered state vector at each time period.
filtered_state_cov	(array) The filtered state covariance matrix at each time period.
predicted_state	(array) The predicted state vector at each time period.
predicted_state_cov	(array) The predicted state covariance matrix at each time period.
kalman_gain	(array) The Kalman gain at each time period.
forecasts	(array) The one-step-ahead forecasts of observations at each time period.
forecasts_error	(array) The forecast errors at each time period.
forecasts_error_cov	(array) The forecast error covariance matrices at each time period.
llf_obs	(array) The loglikelihood values at each time period.
collapsed_forecasts	(array) If filtering using collapsed observations, stores the one-step-ahead forecasts of collapsed observations at each time period.
collapsed_forecasts_error	(array) If filtering using collapsed observations, stores the one-step-ahead forecast errors of collapsed observations at each time period.
collapsed_forecasts_error_cov	(array) If filtering using collapsed observations, stores the one-step-ahead forecast error covariance matrices of collapsed observations at each time period.

predict(start=None, end=None, dynamic=None, **kwargs)[source]¶

In-sample and out-of-sample prediction for state space models generally

Parameters:

start : int, optional

Zero-indexed observation number at which to start forecasting, i.e., the first forecast will be at start.

end : int, optional

Zero-indexed observation number at which to end forecasting, i.e., the last forecast will be at end.

dynamic : int, optional

Offset relative to start at which to begin dynamic prediction. Prior to this observation, true endogenous values will be used for prediction; starting with this observation and continuing through the end of prediction, forecasted endogenous values will be used instead.

**kwargs

If the prediction range is outside of the sample range, any of the state space representation matrices that are time-varying must have updated values provided for the out-of-sample range. For example, of obs_intercept is a time-varying component and the prediction range extends 10 periods beyond the end of the sample, a (k_endog x 10) matrix must be provided with the new intercept values.

Returns:

results : PredictionResults

A PredictionResults object.

Notes

All prediction is performed by applying the deterministic part of the measurement equation using the predicted state variables.

Out-of-sample prediction first applies the Kalman filter to missing data for the number of periods desired to obtain the predicted states.

standardized_forecasts_error¶: Standardized forecast errors

update_filter(kalman_filter)[source]¶

Update the filter results

Parameters:

kalman_filter : KalmanFilter

The model object from which to take the updated values.

Notes

This method is rarely required except for internal usage.

update_representation(model, only_options=False)[source]¶

Update the results to match a given model

Parameters:

model : Representation

The model object from which to take the updated values.

only_options : boolean, optional

If set to true, only the filter options are updated, and the state space representation is not updated. Default is False.

Notes

This method is rarely required except for internal usage.