Kalman smoother¶

Note that this class inherits from Kalman filter; its documentation should be consulted for additional methods available in KalmanSmoother objects.

class dismalpy.ssm.kalman_smoother.KalmanSmoother(k_endog, k_states, k_posdef=None, results_class=None, **kwargs)[source]¶

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

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.

results_class : class, optional

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

**kwargs

Keyword arguments may be used to provide default values for state space matrices, for Kalman filtering options, or for Kalman smoothing options. See Representation for more details.

set_smoother_output(smoother_output=None, **kwargs)[source]¶

Set the smoother output

The smoother can produce several types of results. The smoother output variable controls which are calculated and returned.

Parameters:

smoother_output : integer, optional

Bitmask value to set the smoother output to. See notes for details.

**kwargs

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

Notes

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

SMOOTHER_STATE = 0x01: Calculate and return the smoothed states.
SMOOTHER_STATE_COV = 0x02: Calculate and return the smoothed state covariance matrices.
SMOOTHER_DISTURBANCE = 0x04: Calculate and return the smoothed state and observation disturbances.
SMOOTHER_DISTURBANCE_COV = 0x08: Calculate and return the covariance matrices for the smoothed state and observation disturbances.
SMOOTHER_ALL: Calculate and return all results.

If the bitmask is set directly via the smoother_output 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 smoother output may also be specified by directly modifying the class attributes which are defined similarly to the keyword arguments.

The default smoother output is SMOOTHER_ALL.

If performance is a concern, only those results which are needed should be specified as any results that are not specified will not be calculated. For example, if the smoother output is set to only include SMOOTHER_STATE, the smoother operates much more quickly than if all output is required.

Examples

>>> mod = dp.ssm.KalmanFilter(1,1)
>>> mod.smoother_output
15
>>> mod.set_smoother_output(smoother_output=0)
>>> mod.smoother_state = True
>>> mod.smoother_output
1
>>> mod.smoother_state
True

smooth(smoother_output=None, results=None, prefix=None)[source]¶

Apply the Kalman smoother to the statespace model.

Parameters:

smoother_output : int, optional

Determines which Kalman smoother output calculate. Default is all (including state, disturbances, and all covariances).

results : class or object, optional

If a class, then that class is instantiated and returned with the result of both filtering and smoothing. If an object, then that object is updated with the smoothing data. If None, then a FilterResults object is returned with both filtering and smoothing results.

prefix : string

The prefix of the datatype. Usually only used internally.

Returns

——-

FilterResults object

class dismalpy.ssm.kalman_smoother.SmootherResults(model)[source]¶

Results from applying the Kalman smoother and/or 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.
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.
loglikelihood	(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.
standardized_forecast_error	(array) The standardized forecast errors
smoother_output	(int) Bitmask representing the generated Kalman smoothing output
scaled_smoothed_estimator	(array) The scaled smoothed estimator at each time period.
scaled_smoothed_estimator_cov	(array) The scaled smoothed estimator covariance matrices at each time period.
smoothing_error	(array) The smoothing error covariance matrices at each time period.
smoothed_state	(array) The smoothed state at each time period.
smoothed_state_cov	(array) The smoothed state covariance matrices at each time period.
smoothed_measurement_disturbance	(array) The smoothed measurement at each time period.
smoothed_state_disturbance	(array) The smoothed state at each time period.
smoothed_measurement_disturbance_cov	(array) The smoothed measurement disturbance covariance matrices at each time period.
smoothed_state_disturbance_cov	(array) The smoothed state disturbance covariance matrices at each time period.

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 smoother and 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.

update_smoother(smoother)[source]¶

Update the smoother results

Parameters:

smoother : KalmanSmoother

The model object from which to take the updated values.

Notes

This method is rarely required except for internal usage.