Kalman filter and smoother

KalmanSettings(...)

Define an immutable structure that includes all the Kalman filter and smoother inputs.

Model

The state space model used below is,

$Y_{t} = B*X_{t} + e_{t}$

$X_{t} = C*X_{t-1} + D*U_{t}$

where $e_{t} \sim N(0_{nx1}, R)$ and $U_{t} \sim N(0_{mx1}, Q)$.

Fields

• Y: Observed measurements (nxT)
• B: Measurement equations' coefficients
• R: Covariance matrix of the measurement equations' error terms
• C: Transition equations' coefficients
• D: Transition equations' coefficients associated to the error terms
• Q: Covariance matrix of the transition equations' error terms
• X0: Mean vector for the states at time $t=0$
• P0: Covariance matrix for the states at time $t=0$
• DQD: Covariance matrix of $D*U_{t}$ (i.e., $D*Q*D'$)
• m: Number of latent states
• compute_loglik: Boolean (true for computing the loglikelihood in the Kalman filter)
• store_history: Boolean (true to store the history of the filter and smoother)

KalmanSettings(Y::Union{FloatMatrix, JMatrix{Float64}}, B::FloatMatrix, R::Union{UniformScaling{Float64}, SymMatrix}, C::FloatMatrix, Q::SymMatrix; kwargs...)

KalmanSettings constructor.

Arguments

• Y: Observed measurements (nxT)
• B: Measurement equations' coefficients
• R: Covariance matrix of the measurement equations' error terms
• C: Transition equations' coefficients
• Q: Covariance matrix of the transition equations' error terms

Keyword arguments

• compute_loglik: Boolean (true for computing the loglikelihood in the Kalman filter - default: true)
• store_history: Boolean (true to store the history of the filter and smoother - default: true)

Notes

This particular constructor sets D to be an identity matrix, X0 to be a vector of zeros and computes P0 via solve_discrete_lyapunov(C, Q).

KalmanSettings(Y::Union{FloatMatrix, JMatrix{Float64}}, B::FloatMatrix, R::Union{UniformScaling{Float64}, SymMatrix}, C::FloatMatrix, D::FloatMatrix, Q::SymMatrix; kwargs...)

KalmanSettings constructor.

Arguments

• Y: Observed measurements (nxT)
• B: Measurement equations' coefficients
• R: Covariance matrix of the measurement equations' error terms
• C: Transition equations' coefficients
• D: Transition equations' coefficients associated to the error terms
• Q: Covariance matrix of the transition equations' error terms

Keyword arguments

• compute_loglik: Boolean (true for computing the loglikelihood in the Kalman filter - default: true)
• store_history: Boolean (true to store the history of the filter and smoother - default: true)

Notes

This particular constructor sets X0 to be a vector of zeros and computes P0 via solve_discrete_lyapunov(C, Q).

KalmanSettings(Y::Union{FloatMatrix, JMatrix{Float64}}, B::FloatMatrix, R::Union{UniformScaling{Float64}, SymMatrix}, C::FloatMatrix, D::FloatMatrix, Q::SymMatrix, X0::FloatVector, P0::SymMatrix; kwargs...)

KalmanSettings constructor.

Arguments

• Y: Observed measurements (nxT)
• B: Measurement equations' coefficients
• R: Covariance matrix of the measurement equations' error terms
• C: Transition equations' coefficients
• D: Transition equations' coefficients associated to the error terms
• Q: Covariance matrix of the transition equations' error terms
• X0: Mean vector for the states at time $t=0$
• P0: Covariance matrix for the states at time $t=0$

Keyword arguments

• compute_loglik: Boolean (true for computing the loglikelihood in the Kalman filter - default: true)
• store_history: Boolean (true to store the history of the filter and smoother - default: true)

OnlineKalmanStatus(...)

Define a mutable structure to handle minimal Kalman filter output.

The Kalman filter history is not stored. This makes it ideal for online filtering problems. However, it is incompatible with the kalman smoother implementation.

Arguments

• t: Current point in time
• loglik: Loglikelihood
• X_prior: Latest a-priori X
• X_post: Latest a-posteriori X
• P_prior: Latest a-priori P
• P_post: Latest a-posteriori P
• e: Forecast error
• inv_F: Inverse of the forecast error covariance
• L: Convenient shortcut for the filter and smoother
• buffer_J1, buffer_J2, buffer_m_m, buffer_m_n_obs: Buffer arrays used for low-level matrix operations

OnlineKalmanStatus()

Return an initialised OnlineKalmanStatus.

DynamicKalmanStatus(...)

Define a mutable structure to handle any type of Kalman filter output.

The Kalman filter history is stored when store_history is set to true in the filter settings.

Arguments

• t: Current point in time
• loglik: Loglikelihood
• X_prior: Latest a-priori X
• X_post: Latest a-posteriori X
• P_prior: Latest a-priori P
• P_post: Latest a-posteriori P
• e: Forecast error
• inv_F: Inverse of the forecast error covariance
• L: Convenient shortcut for the filter and smoother
• buffer_J1, buffer_J2, buffer_m_m, buffer_m_n_obs: Buffer arrays used for low-level matrix operations
• history_X_prior: History of a-priori X
• history_X_post: History of a-posteriori X
• history_P_prior: History of a-priori P
• history_P_post: History of a-posteriori P
• history_e: History of the forecast error
• history_inv_F: History of the inverse of the forecast error covariance
• history_L: History of the shortcut L

DynamicKalmanStatus()

Return an initialised DynamicKalmanStatus.

SizedKalmanStatus(...)

Define an immutable structure that always store the filter history up to time $T$.

Arguments

• online_status: OnlineKalmanStatus struct
• history_length: History length
• history_X_prior: History of a-priori X
• history_X_post: History of a-posteriori X
• history_P_prior: History of a-priori P
• history_P_post: History of a-posteriori P
• history_e: History of the forecast error
• history_inv_F: History of the inverse of the forecast error covariance
• history_L: History of the shortcut L

kfilter!(settings::KalmanSettings, status::KalmanStatus)

Kalman filter: a-priori prediction and a-posteriori update.

Arguments

• settings: KalmanSettings struct
• status: KalmanStatus struct

kfilter_full_sample(settings::KalmanSettings, status::KalmanStatus=DynamicKalmanStatus())

Run Kalman filter for $t=1, \ldots, T$ and return status.

kfilter_full_sample!(settings::KalmanSettings, status::SizedKalmanStatus)

Run Kalman filter from t=1 to history_length and update status in-place.

kforecast(settings::KalmanSettings, X::Union{FloatVector, Nothing}, h::Int64)

Forecast X up to h steps ahead.

Arguments

• settings: KalmanSettings struct

• X: State vector

• h: Forecast horizon

  kforecast(settings::KalmanSettings, X::Union{FloatVector, Nothing}, P::Union{SymMatrix, Nothing}, h::Int64)

Forecast X and P up to h steps ahead.

Arguments

• settings: KalmanSettings struct
• X: State vector
• P: Covariance matrix of the states
• h: Forecast horizon

ksmoother(settings::KalmanSettings, status::KalmanStatus, t_stop::Int64=1)

Kalman smoother: RTS smoother from the last evaluated time period in status up to $t==0$.

The smoother is implemented following the approach proposed in Durbin and Koopman (2012).

Arguments

• settings: KalmanSettings struct
• status: KalmanStatus struct
• t_stop: Optional argument that can be used to define the last smoothing period (default: 1)