pyconnectedness 0.1.0__py3-none-any.whl

pyconnectedness/__init__.py

@@ -0,0 +1,35 @@
+"""
+Connectedness measures
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+__version__ = version("pyconnectedness")
+
+from .connectedness import (
+                            ConnectednessResult,
+                            DynamicConnectednessResult,
+                            FrequencyConnectednessResult,
+                            VARFit,
+                            dynamic_connectedness,
+                            fit_var,
+                            frequency_connectedness,
+                            generalized_fevd,
+                            normalize_fevd,
+                            orthogonalized_fevd,
+                            static_connectedness,
+)
+
+__all__ = ["fit_var", "VARFit",
+           "generalized_fevd", "normalize_fevd", "orthogonalized_fevd",
+           "ConnectednessResult", "static_connectedness",
+           "DynamicConnectednessResult", "dynamic_connectedness",
+           "FrequencyConnectednessResult", "frequency_connectedness",
+           "__version__",
+           ]
+
+
+
+

pyconnectedness/connectedness/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .decomposition import generalized_fevd, normalize_fevd, orthogonalized_fevd
+from .dynamic import DynamicConnectednessResult, dynamic_connectedness
+from .frequency import FrequencyConnectednessResult, frequency_connectedness
+from .static import ConnectednessResult, static_connectedness
+from .var import VARFit, fit_var
+
+__all__ = [
+    "fit_var",
+    "VARFit",
+    "static_connectedness",
+    "ConnectednessResult",
+    "generalized_fevd",
+    "orthogonalized_fevd",
+    "normalize_fevd",
+    "dynamic_connectedness",
+    "DynamicConnectednessResult",
+    "frequency_connectedness",
+    "FrequencyConnectednessResult",
+]
+
+

pyconnectedness/connectedness/decomposition.py

@@ -0,0 +1,135 @@
+r"""
+Forecast error variance decompositions for connectedness analysis.
+
+Two schemes are provided:
+
+* :func:`generalized_fevd` — the generalized decomposition of Pesaran and
+  Shin (1998), invariant to variable ordering (Diebold-Yilmaz 2012/2014).
+* :func:`orthogonalized_fevd` — the Cholesky decomposition of Diebold and
+  Yilmaz (2009), which depends on variable ordering.
+
+References
+----------
+Pesaran and Shin (1998) Generalized impulse response analysis in linear
+multivariate models. Economics Letters, 58, 17-29.
+
+Diebold and Yilmaz (2009) Measuring financial asset return and volatility
+spillovers, with application to global equity markets. The Economic Journal,
+119, 158-171.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def generalized_fevd(ma_coefficients: np.ndarray, sigma: np.ndarray) -> np.ndarray:
+    r"""
+    Generalized forecast error variance decomposition (Pesaran-Shin 1998).
+
+    Parameters
+    ----------
+    ma_coefficients : ndarray (H x k x k)
+        Moving-average matrices :math:`\Phi_0, \ldots, \Phi_{H-1}`.
+    sigma : ndarray (k x k)
+        Residual covariance matrix :math:`\Sigma_u`.
+
+    Notes
+    -----
+    The share of the H-step forecast error variance of variable i due to
+    shocks in variable j is
+
+    .. math::
+
+        \theta_{ij}(H) = \frac{\sigma_{jj}^{-1}
+            \sum_{h=0}^{H-1} (e_i' \Phi_h \Sigma e_j)^2}
+            {\sum_{h=0}^{H-1} e_i' \Phi_h \Sigma \Phi_h' e_i}
+
+    where :math:`e_i` is a selection vector and :math:`\sigma_{jj}` the j-th
+    diagonal element of :math:`\Sigma`. Rows do not sum to one under this
+    scheme; apply :func:`normalize_fevd`.
+
+    Returns
+    -------
+    ndarray (k x k)
+        Matrix theta with theta[i, j] the contribution of j to i.
+    """
+    ma = np.asarray(ma_coefficients)
+    sigma = np.asarray(sigma)
+    H, k, _ = ma.shape
+
+    sigma_jj = np.diag(sigma)
+    numerator = np.zeros((k, k))
+    denominator = np.zeros(k)
+    for h in range(H):
+        phi = ma[h]
+        phi_sigma = phi @ sigma          # entry [i, j] = e_i' Phi_h Sigma e_j
+        numerator += phi_sigma ** 2
+        denominator += np.diag(phi_sigma @ phi.T)
+
+    return (numerator / sigma_jj[np.newaxis, :]) / denominator[:, np.newaxis]
+
+
+def orthogonalized_fevd(ma_coefficients: np.ndarray, sigma: np.ndarray) -> np.ndarray:
+    r"""
+    Orthogonalized (Cholesky) forecast error variance decomposition (DY 2009).
+
+    Parameters
+    ----------
+    ma_coefficients : ndarray (H x k x k)
+        Moving-average matrices :math:`\Phi_0, \ldots, \Phi_{H-1}`.
+    sigma : ndarray (k x k)
+        Residual covariance matrix :math:`\Sigma_u`.
+
+    Notes
+    -----
+    Uses the Cholesky factor :math:`P` with :math:`\Sigma = P P'`:
+
+    .. math::
+
+        \theta_{ij}(H) = \frac{\sum_{h=0}^{H-1} (e_i' \Phi_h P e_j)^2}
+            {\sum_{h=0}^{H-1} e_i' \Phi_h \Sigma \Phi_h' e_i}
+
+    Rows sum to one by construction. The result depends on the column order
+    of the data — the known ordering sensitivity of the DY-2009 method.
+
+    Returns
+    -------
+    ndarray (k x k)
+        Matrix theta with theta[i, j] the contribution of j to i.
+    """
+    ma = np.asarray(ma_coefficients)
+    sigma = np.asarray(sigma)
+    H, k, _ = ma.shape
+
+    P = np.linalg.cholesky(sigma)        # Sigma = P P', lower triangular
+    numerator = np.zeros((k, k))
+    denominator = np.zeros(k)
+    for h in range(H):
+        phi = ma[h]
+        phi_P = phi @ P
+        numerator += phi_P ** 2
+        denominator += np.diag(phi @ sigma @ phi.T)
+
+    return numerator / denominator[:, np.newaxis]
+
+
+def normalize_fevd(theta: np.ndarray) -> np.ndarray:
+    """
+    Normalize a decomposition row-wise so each row sums to one.
+
+    Parameters
+    ----------
+    theta : ndarray (k x k)
+
+    Notes
+    -----
+    Required after :func:`generalized_fevd`. A no-op after
+    :func:`orthogonalized_fevd`, whose rows already sum to one.
+
+    Returns
+    -------
+    ndarray (k x k)
+    """
+    theta = np.asarray(theta)
+    return theta / theta.sum(axis=1, keepdims=True)

pyconnectedness/connectedness/dynamic.py

@@ -0,0 +1,153 @@
+"""
+Rolling-window (dynamic) connectedness measures
+
+References
+----------
+Diebold and Yilmaz (2009) Measuring financial asset return and volatility
+spillovers, with application to global equity markets. The Economic Journal,
+119, 158-171.
+Diebold and Yilmaz (2012) Better to give than to receive: predictive
+directional measurement of volatility spillovers. International Journal of
+Forecasting, 28, 57-66.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from .static import static_connectedness
+from .var import fit_var
+
+
+@dataclass
+class DynamicConnectednessResult:
+    """
+    Rolling-window connectedness measures.
+
+    Parameters
+    ----------
+    total : Series (T,)
+        Total connectedness (spillover) index per window, in percent.
+    directional_to : DataFrame (T x k)
+        Contribution of each variable to the forecast error variance of all
+        others, off-diagonal column sums.
+    directional_from : DataFrame (T x k)
+        Contribution received by each variable from all others, off-diagonal
+        row sums
+    net : DataFrame (T x k)
+        TO minus FROM. Sums to zero across variables in every window.
+    fevd : ndarray (T x k x k)
+    pairwise_net: ndarray (T x k x k)
+    names : list of str
+    window, horizon, lag_order : int
+    method : str
+
+
+    """
+
+    total: pd.Series
+    directional_to: pd.DataFrame
+    directional_from: pd.DataFrame
+    net: pd.DataFrame
+    fevd: np.ndarray
+    pairwise_net: np.ndarray
+    names: list
+    window: int
+    horizon: int
+    lag_order: int
+    method: str = "generalized"
+
+    @property
+    def k(self):
+        return len(self.names)
+
+    @property
+    def n_windows(self):
+        return len(self.total)
+
+
+def dynamic_connectedness(
+    data, window, horizon=10, *, method="generalized", lags=None, **fit_kwargs
+):
+    r"""
+    Connectedness measures over a rolling estimation window
+
+    Parameters
+    ----------
+    data : DataFrame (n x k)
+        Observations in rows, variables in columns
+    window : int
+        Number of observations per estimation window
+    horizon : int
+        Forecast horizon H of the variance decomposition.
+    method : {"generalized", "orthogonalized"}
+        Decomposition applied in every window, passed on to
+        static_connectedness. DY-2009 is Cholesky, DY-2012 onward generalized.
+    lags : int or None
+        VAR order, held fixed across windows. If None it is selected once on
+        the full sample and then frozen; see Notes.
+    **fit_kwargs
+        Further arguments for fit_var, e.g. ``ic="aic"``, ``trend="c"``.
+
+
+
+    Returns
+    -------
+    DynamicConnectednessResult
+
+    Raises
+    ------
+    TypeError
+        If data is not a DataFrame.
+    ValueError
+        If the window is longer than the sample.
+    """
+    if not isinstance(data, pd.DataFrame):
+        raise TypeError("data must be a DataFrame")
+
+    nobs, k = data.shape
+    if window > nobs:
+        raise ValueError(f"window ({window}) exceeds the sample length ({nobs})")
+
+    if lags is None:
+        lags = fit_var(data, **fit_kwargs).lag_order
+
+    index = data.index[window - 1:]  # right-aligned, as in the papers
+    n_windows = len(index)
+
+    theta = np.empty((n_windows, k, k))
+    to = np.empty((n_windows, k))
+    frm = np.empty((n_windows, k))
+    total = np.empty(n_windows)
+
+    for t in range(n_windows):
+        res = static_connectedness(
+            data.iloc[t:t + window],
+            horizon,
+            method=method,
+            lags=lags,
+            **fit_kwargs,
+        )
+        theta[t] = res.fevd
+        to[t] = np.asarray(res.directional_to)
+        frm[t] = np.asarray(res.directional_from)
+        total[t] = res.total
+
+    names = list(data.columns)
+
+    pairwise = theta.transpose(0,2,1) - theta
+
+    return DynamicConnectednessResult(
+        total=pd.Series(total, index=index, name="total"),
+        directional_to=pd.DataFrame(to, index=index, columns=names),
+        directional_from=pd.DataFrame(frm, index=index, columns=names),
+        net=pd.DataFrame(to - frm, index=index, columns=names),  # = res.net
+        fevd=theta,
+        pairwise_net= pairwise,
+        names=names,
+        window=window,
+        horizon=horizon,
+        lag_order=lags,
+        method=method,
+    )

pyconnectedness/connectedness/frequency.py

@@ -0,0 +1,185 @@
+r"""
+Frequency connectedness (Baruník-Křehlík 2018).
+
+References
+----------
+Baruník and Křehlík (2018) Measuring the frequency dynamics of financial
+connectedness and systemic risk. Journal of Financial Econometrics, 16, 271-296.
+
+Diebold and Yilmaz (2012) Better to give than to receive: predictive directional
+measurement of volatility spillovers. International Journal of
+Forecasting, 28, 57-66.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from .static import _build_result
+from .var import VARFit, fit_var
+
+
+@dataclass
+class FrequencyConnectednessResult:
+    """
+    Connectedness by frequency band.
+
+    Parameters
+    ----------
+    bands : dict
+        Band label -> ConnectednessResult, the frequency connectedness
+    within : dict
+        Band label -> ConnectednessResult, the band rescaled as if it were the
+        whole system.
+    share : Series
+        Share of each band in the forecast error variance, in percent. Sums
+        to 100.
+    total : Series
+        Total connectedness per band, in percent
+    horizon : int
+    """
+
+    bands: dict
+    within: dict
+    share: pd.Series
+    total: pd.Series
+    horizon: int
+
+    def __repr__(self) -> str:
+        return (f"FrequencyConnectednessResult(TCI={self.total.sum():.2f}%, "
+                f"bands={self.total.round(2).to_dict()})")
+
+
+def frequency_connectedness(
+    data: pd.DataFrame | None = None,
+    horizon: int = 100,
+    *,
+    periods: tuple = (5, 20),
+    method: str = "generalized",
+    var_fit: VARFit | None = None,
+    **fit_kwargs,
+) -> FrequencyConnectednessResult:
+    r"""
+    Compute Baruník-Křehlík frequency connectedness.
+
+    Provide either `data`` (a VAR is estimated internally) or a pre-fitted
+    `var_fit`
+
+    Parameters
+    ----------
+    data : DataFrame, optional
+        Multivariate time series, one column per variable.
+    horizon : int
+        Forecast horizon H, also the number of points of the frequency grid.
+    periods : tuple of int
+        Band cutoffs as cycle lengths in observations, increasing and larger
+        than 2
+    method : {"generalized", "orthogonalized"}
+        Decomposition scheme, as in static_connectedness.
+    var_fit : VARFit, optional
+        Pre-fitted VAR model; skips the internal estimation.
+    **fit_kwargs
+        Passed through to :func:`pyconnectedness.connectedness.var.fit_var`
+        (e.g. ``lags``, ``ic``, ``max_lags``).
+
+    Notes
+    -----
+    The share of the forecast error variance of variable i due to shocks in
+    j on the frequency band d is
+
+    .. math::
+
+        \tilde\theta_{ij}(d) = \frac{\sigma_{jj}^{-1} \int_d
+            |(\Psi(e^{-i\omega}) \Sigma)_{ij}|^2 d\omega}
+            {\sum_l \sigma_{ll}^{-1} \int_{-\pi}^{\pi}
+            |(\Psi(e^{-i\omega}) \Sigma)_{il}|^2 d\omega}
+
+    with :math:`\Psi(e^{-i\omega}) = \sum_h \Phi_h e^{-i\omega h}`.
+
+    A cutoff of p observations is the frequency :math:`2\pi / p`. As the R
+    package frequencyConnectedness takes the cutoffs in radians, so
+    `periods=(5, 20)` corresponds to
+    `c(pi + 0.00001, 2*pi/5, 2*pi/20, 0)`.
+
+    Returns
+    -------
+    FrequencyConnectednessResult
+
+    Raises
+    ------
+    ValueError
+        If neither `data` nor `var_fit` is given, `method` is unknown,
+        `periods` is not increasing or not larger than 2, or a band holds no
+        frequency at the given horizon.
+    """
+    if var_fit is None:
+        if data is None:
+            raise ValueError("provide either 'data' or 'var_fit'")
+        var_fit = fit_var(data, **fit_kwargs)
+
+    if min(periods) <= 2:
+        raise ValueError("periods must be larger than 2")
+    if (np.diff(periods) <= 0).any():
+        raise ValueError("periods must be increasing")
+
+    names = var_fit.names
+    sigma = var_fit.sigma
+    k = var_fit.k
+
+    # 1) MA matrices Phi_0, ..., Phi_{H-1}, H x k x k
+    ma = var_fit.ma_coefficients(horizon)
+
+    # 2) psi[s] = Psi(exp(-i omega_s)) = sum_h Phi_h exp(-i omega_s h)
+    psi = np.fft.fft(ma, axis=0)
+
+    # 3) omega_s = 2 pi s / H; rows above H/2 are the negative frequencies and
+    # fold onto their positive twins
+    omega = 2 * np.pi * np.abs(np.fft.fftfreq(horizon))
+
+    # 4) contribution of shocks in j to variable i at each frequency
+    if method == "generalized":
+        numerator = np.abs(psi @ sigma) ** 2 / np.diag(sigma)
+    elif method == "orthogonalized":
+        numerator = np.abs(psi @ np.linalg.cholesky(sigma)) ** 2
+    else:
+        raise ValueError(
+            f"unknown method '{method}'; use 'generalized' or 'orthogonalized'"
+        )
+
+    # 5) normalize row i over all frequencies and all shocks
+    theta = numerator / numerator.sum(axis=(0, 2))[np.newaxis, :, np.newaxis]
+
+    # 6) band edges as frequencies, high to low
+    tol = 1e-10
+    edges = [np.inf] + [2 * np.pi / p for p in periods] + [0.0]
+
+    labels = [f"<={periods[0]}"]
+    for i in range(1, len(periods)):
+        labels.append(f"{periods[i - 1]}-{periods[i]}")
+    labels.append(f">{periods[-1]}")
+
+    # 7)sum theta over the frequencies of each band
+    bands = {}
+    within = {}
+    share = {}
+    total = {}
+    for b, label in enumerate(labels):
+        in_band = (omega >= edges[b + 1] - tol) & (omega < edges[b] - tol)
+        if not in_band.any():
+            raise ValueError(f"band '{label}' is empty at horizon {horizon}")
+        theta_band = theta[in_band].sum(axis=0)
+        bands[label] = _build_result(theta_band, names)
+        within[label] = _build_result(theta_band * k / theta_band.sum(), names)
+        share[label] = theta_band.sum() / k * 100.0
+        total[label] = bands[label].total
+
+    return FrequencyConnectednessResult(
+        bands=bands,
+        within=within,
+        share=pd.Series(share, name="share"),
+        total=pd.Series(total, name="total"),
+        horizon=horizon,
+    )

pyconnectedness/connectedness/static.py

@@ -0,0 +1,163 @@
+r"""
+Static connectedness measures (Diebold-Yilmaz 2009, 2012).
+
+From a normalized variance decomposition :math:`D = [\tilde\theta_{ij}]` the
+spillover measures are derived: the total connectedness index (TCI),
+directional "from" (shocks received), directional "to" (shocks transmitted), and
+net (to minus from).
+
+References
+----------
+Diebold and Yilmaz (2009) Measuring financial asset return and volatility
+spillovers, with application to global equity markets. The Economic Journal,
+119, 158-171.
+
+Diebold and Yilmaz (2012) Better to give than to receive: predictive
+directional measurement of volatility spillovers. International Journal of
+Forecasting, 28, 57-66.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from .decomposition import generalized_fevd, normalize_fevd, orthogonalized_fevd
+from .var import VARFit, fit_var
+
+
+@dataclass
+class ConnectednessResult:
+    """
+    Result of a static connectedness computation.
+
+    Parameters
+    ----------
+    table : DataFrame
+        Spillover table in Diebold-Yilmaz layout: the normalized decomposition
+        (in percent) with "FROM" column and "TO"/"NET" rows.
+    fevd : DataFrame (k x k)
+        Normalized variance decomposition, in percent.
+    total : float
+        Total connectedness index, in percent.
+    directional_to : Series
+        "To others" spillover per variable.
+    directional_from : Series
+        "From others" spillover per variable.
+    net : Series
+        Net spillover per variable (to minus from).
+    """
+
+    table: pd.DataFrame
+    fevd: pd.DataFrame
+    total: float
+    directional_to: pd.Series
+    directional_from: pd.Series
+    net: pd.Series
+    pairwise_net: pd.DataFrame
+
+    def __repr__(self) -> str:
+        return f"ConnectednessResult(TCI={self.total:.2f}%, n={self.fevd.shape[0]})"
+
+
+def _measures(theta_norm: np.ndarray) -> dict:
+    """Compute directional and total measures from a normalized decomposition."""
+    k = theta_norm.shape[0]
+    own = np.diag(theta_norm)
+    to_others = (theta_norm.sum(axis=0) - own) * 100.0      #  sums, off-diagonal
+    from_others = (theta_norm.sum(axis=1) - own) * 100.0    #  sums, off-diagonal
+    net = to_others - from_others
+    incl_own = theta_norm.sum(axis=0) * 100.0
+    total = (theta_norm.sum() - np.trace(theta_norm)) / k * 100.0
+    pairwise = (theta_norm.T - theta_norm) * 100.0    # C_ij = theta_ji - theta_ij
+    return {"to": to_others, "from": from_others, "net": net, "incl_own":incl_own,
+            "total": total, "pairwise": pairwise}
+
+
+
+def _build_result(theta_norm: np.ndarray, names: list) -> ConnectednessResult:
+    """Assemble a result object from a normalized decomposition."""
+    m = _measures(theta_norm)
+    fevd_df = pd.DataFrame(theta_norm * 100.0, index=names, columns=names)
+
+    # Spillover table in DY layout: FEVD + FROM column, then TO and NET rows
+    table = fevd_df.copy()
+    table["FROM"] = m["from"]
+    to_row = pd.Series(dict(zip(names, m["to"], strict=True)), name="TO")
+    to_row["FROM"] = m["to"].sum() # corner - sum of TO
+    incl_row = pd.Series(dict(zip(names,m["incl_own"], strict=True)), name="TO_incl_own")
+    incl_row ["FROM"] = m["total"]
+    net_row = pd.Series(dict(zip(names, m["net"], strict=True)), name="NET")
+    net_row["FROM"] = 0.0 # m["total"]   # corner entry = total connectedness index
+    table = pd.concat([table, to_row.to_frame().T, incl_row.to_frame().T, net_row.to_frame().T])
+
+    return ConnectednessResult(
+        table=table,
+        fevd=fevd_df,
+        total=float(m["total"]),
+        directional_to=pd.Series(m["to"], index=names, name="TO"),
+        directional_from=pd.Series(m["from"], index=names, name="FROM"),
+        net=pd.Series(m["net"], index=names, name="NET"),
+        pairwise_net=pd.DataFrame(m["pairwise"], index=names, columns=names)#.T,
+    )
+
+def static_connectedness(
+    data: pd.DataFrame | None = None,
+    horizon: int = 10,
+    *,
+    method: str = "generalized",
+    var_fit: VARFit | None = None,
+    **fit_kwargs,
+) -> ConnectednessResult:
+    """
+    Compute static Diebold-Yilmaz connectedness.
+
+    Provide either ``data`` (a VAR is estimated internally) or a pre-fitted
+    ``var_fit``.
+
+    Parameters
+    ----------
+    data : DataFrame, optional
+        Multivariate time series, one column per variable.
+    horizon : int
+        Forecast horizon H for the variance decomposition.
+    method : {"generalized", "orthogonalized"}
+        Decomposition scheme - "generalized" (Pesaran-Shin, order-invariant,
+        reproduces DY-2012/2014) or "orthogonalized" (Cholesky, order-
+        dependent, reproduces DY-2009). Under "orthogonalized" the column
+        order of the data determines the result.
+    var_fit : VARFit, optional
+        Pre-fitted VAR model; skips the internal estimation.
+    **fit_kwargs
+        Passed through to :func:`pyconnectedness.connectedness.var.fit_var`
+        (e.g. ``lags``, ``ic``, ``max_lags``).
+
+    Returns
+    -------
+    ConnectednessResult
+
+    Raises
+    ------
+    ValueError
+        If neither ``data`` nor ``var_fit`` is given, or ``method`` is unknown.
+    """
+    if var_fit is None:
+        if data is None:
+            raise ValueError("provide either 'data' or 'var_fit'")
+        var_fit = fit_var(data, **fit_kwargs)
+
+    ma = var_fit.ma_coefficients(horizon)
+    if method == "generalized":
+        theta = generalized_fevd(ma, var_fit.sigma)
+    elif method == "orthogonalized":
+        theta = orthogonalized_fevd(ma, var_fit.sigma)
+    else:
+        raise ValueError(
+            f"unknown method '{method}'; use 'generalized' or 'orthogonalized'"
+        )
+    theta_norm = normalize_fevd(theta)
+
+
+    return _build_result(theta_norm, var_fit.names)