statsmodels.tsa.statespace.kalman_filter.KalmanFilter¶

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

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

Parameters:¶

k_endog{array_like, int}

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

k_statesint

The dimension of the unobserved state process.

k_posdefint, optional

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

loglikelihood_burnint, optional

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

tolerancefloat, optional

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

results_classclass, 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.

See also

FilterResults

statsmodels.tsa.statespace.representation.Representation

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.

Attributes:¶

design

dtype

(dtype) Datatype of currently active representation matrices

endog

memory_no_filtered

(bool) Flag to prevent storing filtered state and covariance matrices.

memory_no_forecast

(bool) Flag to prevent storing all forecast-related output.

memory_no_predicted

(bool) Flag to prevent storing predicted state and covariance matrices.

obs

(array) Observation vector: \(y~(k\_endog \times nobs)\)

obs_cov

obs_intercept

prefix

(str) BLAS prefix of currently active representation matrices

selection

state_cov

state_intercept

time_invariant

(bool) Whether or not currently active representation matrices are

transition

Methods

bind(endog)	Bind data to the statespace representation
clone(endog, **kwargs)	Clone a state space representation while overriding some elements
diff_endog(new_endog[, tolerance])
extend(endog[, start, end])	Extend the current state space model, or a specific (time) subset
filter([filter_method, inversion_method, ...])	Apply the Kalman filter to the statespace model.
fixed_scale(scale)	Context manager for fixing the scale when FILTER_CONCENTRATED is set
impulse_responses([steps, impulse, ...])	Impulse response function
initialize(initialization[, ...])	Create an Initialization object if necessary
initialize_approximate_diffuse([variance])	Initialize the statespace model with approximate diffuse values.
initialize_components([a, Pstar, Pinf, A, ...])	Initialize the statespace model with component matrices
initialize_diffuse()	Initialize the statespace model as diffuse.
initialize_known(constant, stationary_cov)	Initialize the statespace model with known distribution for initial state.
initialize_stationary()	Initialize the statespace model as stationary.
loglike(**kwargs)	Calculate the loglikelihood associated with the statespace model.
loglikeobs(**kwargs)	Calculate the loglikelihood for each observation associated with the statespace model.
set_conserve_memory([conserve_memory])	Set the memory conservation method
set_filter_method([filter_method])	Set the filtering method
set_filter_timing([alternate_timing])	Set the filter timing convention
set_inversion_method([inversion_method])	Set the inversion method
set_stability_method([stability_method])	Set the numerical stability method
simulate(nsimulations[, measurement_shocks, ...])	Simulate a new time series following the state space model

Properties

conserve_memory	(int) Memory conservation bitmask.
design	(array) Design matrix: \(Z~(k\_endog \times k\_states \times nobs)\)
dtype	(dtype) Datatype of currently active representation matrices
endog	(array) The observation vector, alias for obs.
filter_augmented	(bool) Flag for augmented Kalman filtering.
filter_chandrasekhar	(bool) Flag for filtering with Chandrasekhar recursions.
filter_collapsed	(bool) Flag for Kalman filtering with collapsed observation vector.
filter_concentrated	(bool) Flag for Kalman filtering with concentrated log-likelihood.
filter_conventional	(bool) Flag for conventional Kalman filtering.
filter_exact_initial	(bool) Flag for exact initial Kalman filtering.
filter_extended	(bool) Flag for extended Kalman filtering.
filter_method	(int) Filtering method bitmask.
filter_methods
filter_square_root	(bool) Flag for square-root Kalman filtering.
filter_timing	(int) Filter timing.
filter_univariate	(bool) Flag for univariate filtering of multivariate observation vector.
filter_unscented	(bool) Flag for unscented Kalman filtering.
inversion_method	(int) Inversion method bitmask.
inversion_methods
invert_cholesky	(bool) Flag for Cholesky inversion method.
invert_lu	(bool) Flag for LU inversion method.
invert_univariate	(bool) Flag for univariate inversion method (recommended).
memory_conserve	(bool) Flag to conserve the maximum amount of memory.
memory_no_filtered	(bool) Flag to prevent storing filtered state and covariance matrices.
memory_no_filtered_cov	(bool) Flag to prevent storing filtered state covariance matrices.
memory_no_filtered_mean	(bool) Flag to prevent storing filtered states.
memory_no_forecast	(bool) Flag to prevent storing all forecast-related output.
memory_no_forecast_cov	(bool) Flag to prevent storing forecast error covariance matrices.
memory_no_forecast_mean	(bool) Flag to prevent storing forecasts and forecast errors.
memory_no_gain	(bool) Flag to prevent storing the Kalman gain matrices.
memory_no_likelihood	(bool) Flag to prevent storing likelihood values for each observation.
memory_no_predicted	(bool) Flag to prevent storing predicted state and covariance matrices.
memory_no_predicted_cov	(bool) Flag to prevent storing predicted state covariance matrices.
memory_no_predicted_mean	(bool) Flag to prevent storing predicted states.
memory_no_smoothing	(bool) Flag to prevent storing likelihood values for each observation.
memory_no_std_forecast	(bool) Flag to prevent storing standardized forecast errors.
memory_options
memory_store_all	(bool) Flag for storing all intermediate results in memory (default).
obs	(array) Observation vector: \(y~(k\_endog \times nobs)\)
obs_cov	(array) Observation covariance matrix: \(H~(k\_endog \times k\_endog \times nobs)\)
obs_intercept	(array) Observation intercept: \(d~(k\_endog \times nobs)\)
prefix	(str) BLAS prefix of currently active representation matrices
selection	(array) Selection matrix: \(R~(k\_states \times k\_posdef \times nobs)\)
solve_cholesky	(bool) Flag for Cholesky and linear solver inversion method (recommended).
solve_lu	(bool) Flag for LU and linear solver inversion method.
stability_force_symmetry	(bool) Flag for enforcing covariance matrix symmetry
stability_method	(int) Stability method bitmask.
stability_methods
state_cov	(array) State covariance matrix: \(Q~(k\_posdef \times k\_posdef \times nobs)\)
state_intercept	(array) State intercept: \(c~(k\_states \times nobs)\)
time_invariant	(bool) Whether or not currently active representation matrices are time-invariant
timing_init_filtered	(bool) Flag for the alternate timing convention (Kim and Nelson, 2012).
timing_init_predicted	(bool) Flag for the default timing convention (Durbin and Koopman, 2012).
timing_options
transition	(array) Transition matrix: \(T~(k\_states \times k\_states \times nobs)\)