econometron.filters.kalman

• Kalman class in the econometron.filters module
• Kalman_objective function from the econometron.filters module
• kalman_smooth function from the econometron.filters module

Overview

The Kalman class implements the Kalman filter and smoother for linear state-space models, estimating unobserved states from observed data. Supports:

• Filtering – real-time estimation of states .
• Smoothing – retrospective estimation using all observations.
• Log Likelihood Computation – Using Kalman Filter to calculate the log-likelihood.

State-space model:

Where:

• – State vector (n × 1)
• – Observation vector (m × 1)
• – State transition matrix (n × n)
• – Observation matrix (m × n)
• – State covariance (n × n)
• – Observation covariance (m × m)
• – Gaussian noise terms

Kalman Class

Initialization

from econometron.filters.kalman import Kalman

kalman = Kalman(params)

Parameters:

• params (dict): Dictionary containing:

  • A: State transition matrix (n × n)
  • D: Observation matrix (m × n)
  • Q: State covariance (n × n)
  • R: Observation covariance (m × m)
  • x0: Initial state estimate (n × 1, optional)
  • P0: Initial state covariance (n × n, optional)

Attributes:

• A, D, Q, R – State-space matrices
• X_0, P_0 – Initial state and covariance
• n – State dimension
• m – Observation dimension

Methods

1. validate_entries()

• Purpose: Validates input matrices and initial values during initialization.

• Parameters: None

• Returns: None (raises ValueError if validation fails)

• Notes:

  • Checks shapes of A, Q, D, R, x0, P0
  • Optional symmetry and PSD checks for Q, R, P0

2. _compute_initial_covariance(P0=None)

• Purpose: Computes the initial state covariance .

• Parameters:

  • P0 (np.ndarray, optional): Provided initial covariance

• Returns: np.ndarray – Computed

• Notes:

  • Uses discrete Lyapunov equation if P0 is None
  • Sets for non-stationary systems
  • Ensures symmetry
  • Raises ValueError if P0 invalid

3. filter(y)

• Purpose: Runs the Kalman filter, estimates states, and computes log-likelihood.

• Parameters:

  • y (np.ndarray): Observations (m × T)

• Returns: dict containing:

  • x_tt – Filtered states (n × T)
  • P_tt – Filtered covariances (n × n × T)
  • x_tt1 – Predicted states (n × T)
  • P_tt1 – Predicted covariances (n × n × T)
  • residuals – Standardized residuals (m × T)
  • log_lik – Negative log-likelihood

• Notes:

  • Handles dimension mismatches
  • Returns large negative log-likelihood for numerical issues
  • Computes standardized residuals using

4. smooth(y)

• Purpose: Runs the Kalman smoother for refined state estimates using all observations.

• Parameters:

  • y (np.ndarray): Observations (m × T)

• Returns: dict containing:

  • Xsm – Smoothed states (n × T)
  • Xtilde – Predicted states (n × T)
  • PP1 – Predicted covariances (n × n × T)
  • residuals – Innovations/residuals (m × T)

• Notes:

  • Uses forward-backward recursion
  • Regularization prevents singular matrices

Function : kalman_smooth(y, update_state_space)

• Purpose: Kalman smoother for a given state-space model; updates matrices via callable.

• Parameters:

  • y (np.ndarray): Observations (m × T)
  • update_state_space (callable): Returns updated matrices given parameters

• Returns: np.ndarray – Smoothed states (n × T)

• Notes: Prints error if smoothing fails

Function :kalman_objective(params, fixed_params, param_names, y, update_state_space)

• Purpose: Objective function for MLE; returns negative log-likelihood.

• Parameters:

  • params (np.ndarray): Parameters to optimize
  • fixed_params (dict): Fixed parameters
  • param_names (list): Names of parameters to optimize
  • y (np.ndarray): Observations (m × T)
  • update_state_space (callable): Updates matrices

• Returns: float – Negative log-likelihood (penalty if error occurs)

• Notes: Combines fixed and optimized parameters; calls filter

Usage Example

# Initialize Kalman filter
kalman = Kalman(params)

# Filter
filter_result = kalman.filter(obs)
print("Log-likelihood:", filter_result['log_lik'])

# Smooth
smooth_result = kalman.smooth(obs)
print("Smoothed states shape:", smooth_result['Xsm'].shape)

# MLE optimization
result = minimize(kalman_objective, initial_params,
                  args=(fixed_params, param_names, obs, update_state_space),
                  method='Nelder-Mead')
print("Optimized parameters:", dict(zip(param_names, result.x)))

---

Notes

• Small regularization ensures numerical stability.
• kalman_objectiveReturns negative log-likelihood for MLE.
• Returns large penalty (9e20) for numerical issues.