spillover_processor module

Market Spillover Effects Analysis Module - Standard Diebold-Yilmaz Implementation.

This module implements the standard Diebold-Yilmaz (2012) methodology for measuring spillover effects between financial markets using Vector Autoregression (VAR) models and Forecast Error Variance Decomposition (FEVD).

Key Components: - fit_var_model: Fit Vector Autoregression model to returns data - calculate_fevd: Calculate Forecast Error Variance Decomposition - calculate_spillover_index: Calculate Total Connectedness Index and directional spillovers - run_diebold_yilmaz_analysis: Complete Diebold-Yilmaz spillover analysis - test_granger_causality: Granger causality testing (supplementary)

The methodology follows these steps: 1. Fit VAR model to stationary returns 2. Calculate FEVD at specified horizon 3. Compute spillover indices from FEVD matrix 4. Extract directional and net spillovers

References: - Diebold, F.X. & Yilmaz, K. (2012). Better to Give than to Receive:

Predictive Directional Measurement of Volatility Spillovers. International Journal of Forecasting, 28(1), 57-66.

timeseries_compute.spillover_processor.calculate_fevd(var_model: Any, horizon: int = 10, normalize: bool = True) → ndarray[source]

Calculate Forecast Error Variance Decomposition (FEVD) from fitted VAR model.

Parameters:

  • var_model – Fitted VAR model from statsmodels

  • horizon – Forecast horizon for variance decomposition

  • normalize – Whether to normalize FEVD to sum to 100% (recommended: True)

Returns:

FEVD matrix of shape (n_variables, n_variables) where entry (i,j) represents the percentage of forecast error variance of variable i explained by shocks to variable j

Example

>>> # After fitting VAR model
>>> fevd_matrix = calculate_fevd(fitted_var, horizon=10)
>>> print(f"FEVD shape: {fevd_matrix.shape}")
>>> print(f"Row sums: {fevd_matrix.sum(axis=1)}")  # Should be ~100 if normalized
timeseries_compute.spillover_processor.calculate_spillover_index(fevd_matrix: ndarray, variable_names: list) → Dict[str, Any][source]

Calculate Diebold-Yilmaz spillover indices from FEVD matrix.

Parameters:

  • fevd_matrix – FEVD matrix from calculate_fevd()

  • variable_names – Names of the variables (assets)

Returns:

  • total_spillover_index: Total Connectedness Index (TCI) in percentage

  • directional_spillovers: Dict with ‘to’ and ‘from’ spillovers for each variable

  • net_spillovers: Net spillover for each variable (to - from)

  • pairwise_spillovers: Matrix of pairwise spillovers

  • fevd_table: FEVD table as DataFrame for inspection

Return type:

Dictionary containing

Example

>>> fevd = np.array([[80, 15, 5], [10, 75, 15], [5, 20, 75]])
>>> names = ['AAPL', 'MSFT', 'TSLA']
>>> spillovers = calculate_spillover_index(fevd, names)
>>> print(f"Total spillover: {spillovers['total_spillover_index']:.1f}%")
timeseries_compute.spillover_processor.fit_var_model(returns_df: DataFrame, max_lags: int = 5, ic: str = 'aic') → Tuple[Any, int][source]

Fit Vector Autoregression (VAR) model to returns data.

Parameters:

  • returns_df – DataFrame of stationary returns for multiple assets

  • max_lags – Maximum number of lags to consider

  • ic – Information criterion for lag selection (‘aic’, ‘bic’, ‘hqic’, ‘fpe’)

Returns:

Tuple of (fitted VAR model, selected lag order)

Example

>>> returns = pd.DataFrame({'AAPL': [0.01, -0.02], 'MSFT': [0.015, -0.01]})
>>> model, lag = fit_var_model(returns, max_lags=3)
>>> print(f"Selected lag order: {lag}")
timeseries_compute.spillover_processor.run_diebold_yilmaz_analysis(returns_df: DataFrame, horizon: int = 10, max_lags: int = 5, ic: str = 'aic', include_granger: bool = True, significance_level: float = 0.05) → Dict[str, Any][source]

Complete Diebold-Yilmaz spillover analysis.

This is the main function that implements the standard Diebold-Yilmaz methodology: 1. Fit VAR model to returns 2. Calculate FEVD 3. Compute spillover indices 4. Optionally include Granger causality tests

Parameters:

  • returns_df – DataFrame of stationary returns for multiple assets

  • horizon – Forecast horizon for FEVD calculation

  • max_lags – Maximum lags for VAR model selection

  • ic – Information criterion for VAR lag selection

  • include_granger – Whether to include Granger causality tests

  • significance_level – Significance level for Granger tests

Returns:

  • var_model: Fitted VAR model

  • var_lag: Selected VAR lag order

  • fevd_matrix: FEVD matrix

  • spillover_results: All spillover indices and measures

  • granger_causality: Granger causality test results (if requested)

Return type:

Dictionary containing complete spillover analysis results

Example

>>> returns = pd.DataFrame({
...     'AAPL': np.random.normal(0, 0.02, 100),
...     'MSFT': np.random.normal(0, 0.02, 100),
...     'TSLA': np.random.normal(0, 0.03, 100)
... })
>>> results = run_diebold_yilmaz_analysis(returns, horizon=10)
>>> print(f"Total spillover: {results['spillover_results']['total_spillover_index']:.1f}%")
timeseries_compute.spillover_processor.test_granger_causality(series1: Series, series2: Series, max_lag: int = 5, significance_level: float = 0.05) → Dict[str, Any][source]

Test if series1 Granger-causes series2.

This is a supplementary analysis to the main Diebold-Yilmaz methodology. Now includes multi-level significance testing (1% and 5%) like stationarity tests.

Parameters:

  • series1 – Potential cause series

  • series2 – Potential effect series

  • max_lag – Maximum number of lags to test

  • significance_level – p-value threshold for significance (kept for backward compatibility)

Returns:

Dictionary with causality test results including multi-level significance