econometron.Models.StateSpace

• SS_Modelclass from the econometron.Models.StateSpace module

Overview

The SS_Model class implements a State Space Model framework for modeling and forecasting multivariate time series data, particularly suited for economic and financial applications. It supports both Maximum Likelihood Estimation (MLE) and Bayesian estimation methods, leveraging the Kalman filter for state estimation and smoothing. The class is designed to work with a linear Dynamic Stochastic General Equilibrium (DSGE) model - class:linear_dsgeor user-defined state-space matrices, offering flexibility for custom state-space representations. The class provides methods to set up the state-space system, estimate parameters, generate predictions, and evaluate model performance through residuals and diagnostics. It supports advanced optimization techniques (e.g., simulated annealing, genetic algorithms) for Maximum Likelihood Estimation and Random Walk Metropolis (RWM) for Bayesian estimation.

Class Definition

The SS_Model class is initialized with observed data, model parameters, and optional configurations for the state-space model, estimation method, and optimizer.

Initialization

from econometron.Models import SS_Model

model = SS_Model(
    data=data,  # Observed data (np.ndarray, pd.DataFrame, or pd.Series)
    parameters={'alpha': 0.5, 'beta': 0.9},  # Model parameters
    model=None,  # Optional linear DSGE model
    name='State Space Model',
    optimizer='L-BFGS-B',  # Optimization algorithm
    estimation_method='MLE',  # 'MLE' or 'Bayesian'
    constraints=None  # Optional constraints for optimization
)

Parameters

Parameter	Type	Description
data	np.ndarray, pd.DataFrame, pd.Series	Observed data (shape: n_vars × time_periods).
parameters	dict	Dictionary of model parameters (e.g., {'alpha': 0.5, 'beta': 0.9}).
model	linear_dsge from econometron.Models	Optional DSGE model to define state-space matrices (default: None).
name	str	Model name (default: "State Space Model").
optimizer	str	Optimization algorithm for MLE ('sa', 'ga', 'trust_constr', 'bfgs', 'powell').
estimation_method	str	Estimation method ('MLE' or 'Bayesian').
constraints	dict	Constraints for optimization (used with 'trust_constr').

Workflow

Working with the SS_Model class follows a structured process:

• Set Up the State-Space System: Define the state-space matrices (A, D, Q, R) directly or use a linear_dsge model to generate them. Matrices can be static or callable functions of parameters.
• Parameter Calibration: Optionally fix certain parameters using calibrate_params() or define derived parameters using define_parameter().
• Model Estimation: Fit the model using fit() with either MLE (via various optimizers) or Bayesian estimation (via Random Walk Metropolis).
• Prediction and Evaluation: Generate forecasts with predict() and evaluate residuals and diagnostics with evaluate().
• Summary and Visualization: Use summary() to display parameter estimates, model fit statistics, and posterior distributions (for Bayesian estimation).

Class Attributes

Attribute	Type	Description
data	np.ndarray	Observed data (shape: n_vars × time_periods).
parameters	dict	Dictionary of model parameters.
model	linear_dsge	Optional DSGE model instance.
A	np.ndarray, Callable	State transition matrix or function.
D	np.ndarray, Callable	Control (observation) matrix or function.
Q	np.ndarray, Callable	State noise covariance matrix or function.
R	np.ndarray, Callable	Observation noise covariance matrix or function.
fixed_params	dict	Dictionary of fixed parameters.
_derived_params	dict	Dictionary of derived parameters (computed from expressions).
_predef_expressions	dict	Dictionary of expressions for derived parameters.
state_updater	Callable	Function to update state-space matrices based on parameters.
result	dict	Results from model fitting (e.g., parameter estimates, log-likelihood).
prior_fn	Callable	Prior function for Bayesian estimation.

Methods

validate_entries_()

Validates model inputs, ensuring data shape, matrix definitions, and estimation settings are consistent.

• Raises:

  • ValueError if data shape, matrices, or estimation settings are invalid.

---

set_transition_mat(A, params=None)

Sets the state transition matrix A.

• Parameters:

  • A: np.ndarray, np.matrix, or Callable returning the transition matrix.
  • params: Optional dictionary of parameters for callable A (default: self.parameters).

• Returns: The set transition matrix.

• Raises:

  • ValueError if A is not square, non-numeric, or incompatible.

---

set_design_mat(C, params=None)

Sets the observation matrix C.

Note: In the code, C is referenced, but D is used elsewhere (assuming D is intended).

• Parameters:

  • C: np.ndarray, np.matrix, or Callable returning the observation matrix.
  • params: Optional dictionary of parameters for callable C.

• Returns: The set observation matrix.

• Raises:

  • ValueError if dimensions are incompatible or values are invalid.

---

set_state_cov(Q, params=None)

Sets the state noise covariance matrix Q.

• Parameters:

  • Q: np.ndarray, np.matrix, or Callable returning the state covariance matrix.
  • params: Optional dictionary of parameters for callable Q.

• Returns: The set state covariance matrix.

• Raises:

  • ValueError if Q is not square, positive semi-definite, or contains invalid values.

---

set_obs_cov(R, params=None)

Sets the observation noise covariance matrix R.

• Parameters:

  • R: np.ndarray, np.matrix, or Callable returning the observation covariance matrix.
  • params: Optional dictionary of parameters for callable R.

• Returns: The set observation covariance matrix.

• Raises:

  • ValueError if R is not square, positive semi-definite, or contains invalid values.

---

set_Design_mat(D, params=None)

Sets the control (observation) matrix D.

• Parameters:

  • D: np.ndarray, np.matrix, or Callable returning the control matrix.
  • params: Optional dictionary of parameters for callable D.

• Returns: The set control matrix.

• Raises:

  • ValueError if dimensions are incompatible or values are invalid.

---

define_parameter(definition)

Defines derived parameters using expressions based on existing parameters.

• Parameters:

  • definition: Dictionary of parameter names and their expressions (e.g., {'gamma': 'alpha * beta'}).

• Raises:

  • ValueError if expressions are invalid or reference undefined parameters.

---

calibrate_params(fixed_params)

Fixes specified parameters to given values.

• Parameters:

  • fixed_params: List of tuples (param, value) to fix parameters.

• Returns: Dictionary of fixed parameters.

• Raises:

  • KeyError if parameters are not in self.parameters.

---

_set_priors(priors, bounds)

Sets prior distributions for Bayesian estimation.

• Parameters:

  • priors: Dictionary of {param: (dist_obj, params_dict)} for prior distributions.
  • bounds: List of (lower, upper) bounds for free parameters.

• Returns: Prior function.

• Raises:

  • ValueError if priors or bounds are invalid.

---

fit(Lower_bound, Upper_bound, prior_specs=None, …)

Fits the model using MLE or Bayesian estimation.

• Parameters:

  • Lower_bound, Upper_bound: Lists of parameter bounds.
  • prior_specs: Dictionary of prior specifications for Bayesian estimation.
  • seed: Random seed for reproducibility.
  • Additional parameters for optimization (e.g., T0, rt for simulated annealing; pop_size, n_gen for genetic algorithm; n_iter, burn_in for Bayesian).

• Returns: None (stores results in self.result).

---

summary()

Generates a summary of model fit.

• Output: Prints parameter estimates, fit statistics (AIC, BIC, HQIC), and posterior distributions (Bayesian) or Kalman smoother results.

---

predict(steps=5, test_data=None, plot=True)

Generates out-of-sample predictions.

• Parameters:

  • steps: Number of future time steps to predict.
  • test_data: Optional test data (n_vars × T_test).
  • plot: Whether to plot residuals (if test_data provided).

• Returns: Dictionary with predictions, smoothed states, metrics (if test_data provided), and residuals.

---

evaluate(data=None, plot=True)

Evaluates model residuals and diagnostics.

• Parameters:

  • data: Data to evaluate (defaults to self.data).
  • plot: Whether to plot residuals and diagnostics.

• Returns: Dictionary with residuals, diagnostics (mean, std, Shapiro-Wilk, skewness, kurtosis, ACF, Breusch-Pagan), and metrics (MSE, RMSE, MAE, MAPE).

Example Usage

1. Set Up and Fit a State-Space Model

import numpy as np
import pandas as pd
from econometron.Models import SS_Model
# Generate sample data
np.random.seed(42)
n_obs = 100
data = np.random.randn(2, n_obs)  # 2 variables, 100 time points
parameters = {'alpha': 0.5, 'beta': 0.9}

# Define state-space matrices
A = np.array([[0.8, 0.1], [0.2, 0.7]])  # Transition matrix
D = np.array([[1.0, 0.0], [0.0, 1.0]])  # Observation matrix
Q = np.eye(2) * 0.1  # State noise covariance
R = np.eye(2) * 0.2  # Observation noise covariance

# Initialize model
model = SS_Model(
    data=data,
    parameters=parameters,
    optimizer='sa',
    estimation_method='MLE'
)

# Set state-space matrices
model.set_transition_mat(A)
model.set_Design_mat(D)
model.set_state_cov(Q)
model.set_obs_cov(R)

# Fit model
model.fit(
    Lower_bound=[0.0, 0.0],
    Upper_bound=[1.0, 1.0],
    seed=42,
    T0=5.0,
    rt=0.9,
    nt=2,
    ns=2
)

2. Generate Summary and Diagnostics

# Display model summary
model.summary()

# Evaluate residuals on training data
results = model.evaluate(plot=True)

3. Make Predictions

# Predict 5 steps ahead
predictions = model.predict(steps=5, test_data=data[:, :5], plot=True)

Notes

• Flexibility Supports both DSGE models and user-defined state-space matrices, allowing for a wide range of applications.

• Estimation

  • MLE: Supports multiple optimizers (simulated annealing, genetic algorithms, etc.).
  • Bayesian: Uses Random Walk Metropolis with customizable priors.

• Diagnostics The evaluate() method provides comprehensive residual diagnostics, including:

  • Normality tests (Shapiro-Wilk)
  • Skewness and kurtosis
  • Autocorrelation
  • Heteroskedasticity tests (Breusch-Pagan)

• Visualization

  • Posterior plots for Bayesian estimation
  • Residual diagnostics plots for model evaluation, enhancing interpretability