dscc 0.1.0__py3-none-any.whl

dscc/__init__.py

@@ -0,0 +1,45 @@
+"""dscc -- Dynamic Spectral Conditional Correlations in Python.
+
+Implements Abadir and Rockinger (2026, Econometrics Journal,
+doi:10.1093/ectj/utag017) and the explicit minimal representation of variance
+matrices of Abadir (2023, Econometrics Journal 26, 88-104, doi:10.1093/ectj/utac023).
+"""
+from ._filters import dsh_filter, g_abs
+from ._model import DSCC, DSCCForecast, DSCCResults, default_start, param_names
+from ._representation import (
+    compose_sigma,
+    correlation_from_cov,
+    decompose_sigma,
+    orthogonal_from_data,
+    permutation_matrix,
+    skew_from_vec,
+    vec_from_skew,
+    xi_from_data,
+)
+
+from ._colors import (bluered_colors, get_cmap, matlab_jet_colors, parula_colors, resolve_colorscale,
+                      sinha_colors, turbo_colors)
+from . import backtest, datasets, dcc, elliptope, portfolio
+from ._plots import (plot_correlation_heatmap, plot_coverage_grid, plot_elliptope, plot_slice_coverage,
+                     plot_wealth, save_figure)
+from .backtest import DCCForecaster, DSCCForecaster, EqualWeight, SampleCovForecaster, rolling_backtest
+from .dcc import DCC
+from .portfolio import gmv_weights
+
+__version__ = "0.1.0"
+__author__ = "Dr Merwan Roudane"
+__email__ = "merwanroudane920@gmail.com"
+
+__all__ = [
+    "DSCC", "DSCCResults", "DSCCForecast", "default_start", "param_names",
+    "dsh_filter", "g_abs",
+    "compose_sigma", "decompose_sigma", "correlation_from_cov", "orthogonal_from_data",
+    "permutation_matrix", "skew_from_vec", "vec_from_skew", "xi_from_data",
+    "parula_colors", "matlab_jet_colors", "turbo_colors", "bluered_colors", "sinha_colors",
+    "resolve_colorscale", "get_cmap",
+    "plot_elliptope", "plot_slice_coverage", "plot_coverage_grid", "plot_wealth",
+    "plot_correlation_heatmap", "save_figure",
+    "DCC", "gmv_weights", "rolling_backtest", "DSCCForecaster", "DCCForecaster",
+    "SampleCovForecaster", "EqualWeight",
+    "backtest", "datasets", "dcc", "elliptope", "portfolio",
+]

dscc/_colors.py

@@ -0,0 +1,95 @@
+"""Colour maps: MATLAB R2014b Parula (default), Jet, Turbo, Blue-Red, Sinha.
+
+The 64 Parula stops are the same as in the author's R packages (mqqr, qqkrls, mqqcause).
+
+Author: Dr Merwan Roudane <merwanroudane920@gmail.com>
+"""
+from __future__ import annotations
+
+import numpy as np
+from matplotlib.colors import LinearSegmentedColormap, to_hex
+
+__all__ = ["parula_colors", "matlab_jet_colors", "turbo_colors", "bluered_colors",
+           "sinha_colors", "resolve_colorscale", "get_cmap", "PARULA_STOPS"]
+
+PARULA_STOPS = np.array([
+    [0.2422, 0.1504, 0.6603], [0.2504, 0.1650, 0.7076], [0.2578, 0.1818, 0.7511], [0.2647, 0.1978, 0.7952],
+    [0.2706, 0.2147, 0.8364], [0.2751, 0.2342, 0.8710], [0.2783, 0.2559, 0.8991], [0.2803, 0.2782, 0.9221],
+    [0.2813, 0.3006, 0.9414], [0.2810, 0.3228, 0.9579], [0.2795, 0.3447, 0.9717], [0.2760, 0.3667, 0.9829],
+    [0.2699, 0.3892, 0.9906], [0.2602, 0.4123, 0.9952], [0.2440, 0.4358, 0.9988], [0.2206, 0.4603, 0.9973],
+    [0.1963, 0.4847, 0.9892], [0.1834, 0.5074, 0.9798], [0.1786, 0.5289, 0.9682], [0.1764, 0.5499, 0.9520],
+    [0.1687, 0.5703, 0.9359], [0.1540, 0.5902, 0.9218], [0.1460, 0.6091, 0.9079], [0.1380, 0.6276, 0.8973],
+    [0.1248, 0.6459, 0.8883], [0.1113, 0.6635, 0.8763], [0.0952, 0.6798, 0.8598], [0.0689, 0.6948, 0.8394],
+    [0.0297, 0.7082, 0.8163], [0.0036, 0.7203, 0.7917], [0.0067, 0.7312, 0.7660], [0.0433, 0.7411, 0.7394],
+    [0.0964, 0.7500, 0.7120], [0.1408, 0.7584, 0.6842], [0.1717, 0.7670, 0.6554], [0.1938, 0.7758, 0.6251],
+    [0.2161, 0.7843, 0.5923], [0.2470, 0.7918, 0.5567], [0.2906, 0.7973, 0.5188], [0.3406, 0.8008, 0.4789],
+    [0.3909, 0.8029, 0.4354], [0.4456, 0.8024, 0.3909], [0.5044, 0.7993, 0.3480], [0.5616, 0.7942, 0.3045],
+    [0.6174, 0.7876, 0.2612], [0.6720, 0.7793, 0.2227], [0.7242, 0.7698, 0.1910], [0.7738, 0.7598, 0.1646],
+    [0.8203, 0.7498, 0.1535], [0.8634, 0.7406, 0.1596], [0.9035, 0.7330, 0.1774], [0.9393, 0.7288, 0.2100],
+    [0.9728, 0.7298, 0.2394], [0.9956, 0.7434, 0.2371], [0.9970, 0.7659, 0.2199], [0.9952, 0.7893, 0.2028],
+    [0.9892, 0.8129, 0.1885], [0.9786, 0.8360, 0.1766], [0.9676, 0.8587, 0.1643], [0.9610, 0.8806, 0.1537],
+    [0.9597, 0.9023, 0.1423], [0.9628, 0.9234, 0.1330], [0.9691, 0.9438, 0.1241], [0.9769, 0.9839, 0.0805],
+])
+
+_ANCHORS = {
+    "jet": ["#000090", "#0000FF", "#00FFFF", "#FFFF00", "#FF0000", "#800000"],
+    "turbo": ["#30123B", "#4145AB", "#4675ED", "#39A2FC", "#1BCFD4", "#24EAA7", "#61FC6C", "#A4FC3C",
+              "#D1E834", "#F3C63A", "#FE9B2D", "#F36315", "#D93806", "#A91201", "#7A0403"],
+    "bluered": ["#053061", "#2166AC", "#92C5DE", "#F7F7F7", "#F4A582", "#B2182B", "#67001F"],
+    "sinha": ["#000000", "#4A0E00", "#B22222", "#FF8C00", "#FFFF66"],
+}
+
+
+def _ramp(anchors, n: int) -> list[str]:
+    cm = LinearSegmentedColormap.from_list("_tmp", anchors, N=max(int(n), 2))
+    return [to_hex(cm(i / (n - 1))) if n > 1 else to_hex(cm(0.0)) for i in range(n)]
+
+
+def parula_colors(n: int = 256) -> list[str]:
+    """MATLAB R2014b Parula as ``n`` hex colours (interpolated from the 64 stops)."""
+    if n == len(PARULA_STOPS):
+        return [to_hex(c) for c in PARULA_STOPS]
+    return _ramp([tuple(c) for c in PARULA_STOPS], n)
+
+
+def matlab_jet_colors(n: int = 256) -> list[str]:
+    return _ramp(_ANCHORS["jet"], n)
+
+
+def turbo_colors(n: int = 256) -> list[str]:
+    return _ramp(_ANCHORS["turbo"], n)
+
+
+def bluered_colors(n: int = 256) -> list[str]:
+    return _ramp(_ANCHORS["bluered"], n)
+
+
+def sinha_colors(n: int = 256) -> list[str]:
+    return _ramp(_ANCHORS["sinha"], n)
+
+
+_FUN = {"parula": parula_colors, "jet": matlab_jet_colors, "turbo": turbo_colors,
+        "bluered": bluered_colors, "blue_red": bluered_colors, "sinha": sinha_colors,
+        "red_yellow_black": sinha_colors}
+
+
+def get_cmap(name: str = "Parula"):
+    """Matplotlib colormap for a scale name (Parula by default); falls back to matplotlib's names."""
+    key = str(name).lower()
+    if key in _FUN:
+        return LinearSegmentedColormap.from_list(name, _FUN[key](256), N=256)
+    import matplotlib
+    return matplotlib.colormaps[name]
+
+
+def resolve_colorscale(name="Parula", n_breaks: int = 32):
+    """Plotly colorscale ``[[value, hex], ...]`` for a scale name (Parula by default)."""
+    if isinstance(name, (list, tuple)):
+        return list(name)
+    key = str(name).lower()
+    if key in _FUN:
+        cols = _FUN[key](256)
+        n_breaks = max(2, int(n_breaks))
+        idx = np.round(np.linspace(0, len(cols) - 1, n_breaks)).astype(int)
+        return [[float(v), cols[i]] for v, i in zip(np.linspace(0, 1, n_breaks), idx)]
+    return name

dscc/_fast.py

@@ -0,0 +1,152 @@
+"""Optional numba kernels for the three hot loops (DSH filter, GARCH(1,1), DCC likelihood).
+
+If numba is not installed, or ``DSCC_NO_NUMBA=1`` is set, the pure-NumPy code paths
+are used; both paths give identical results (tested).
+
+Author: Dr Merwan Roudane <merwanroudane920@gmail.com>
+"""
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+HAVE_NUMBA = False
+if os.environ.get("DSCC_NO_NUMBA", "0") != "1":
+    try:
+        from numba import njit
+        HAVE_NUMBA = True
+    except Exception:  # pragma: no cover
+        HAVE_NUMBA = False
+
+__all__ = ["HAVE_NUMBA", "dsh_loop", "garch11_h", "dcc_nll"]
+
+
+def _dsh_loop_py(X, Xd, expU, D0, D11, D21, a, c, egarch, delta_fixed):
+    T, k = X.shape
+    state = np.zeros((T, k)); delta = np.zeros(T, np.int64); contrib = np.zeros(T)
+    for t in range(1, T):
+        xp = Xd[t - 1] if delta[t - 1] else X[t - 1]
+        z = expU[t - 1].T @ xp
+        if egarch:
+            zs = z / np.sqrt(np.exp(state[t - 1]))
+            d = zs - c
+            state[t] = D0 + D11 * state[t - 1] + D21 * (np.abs(d) - a * d)
+            lam = np.exp(state[t]); logdet = state[t].sum()
+        else:
+            state[t] = D0 + D11 * state[t - 1] + D21 * z * z
+            lam = state[t]
+            if np.any(lam <= 0):
+                return state, delta, contrib, False
+            logdet = np.log(lam).sum()
+        E = expU[t]
+        w0 = E.T @ X[t]; w1 = E.T @ Xd[t]
+        f0 = np.sum(w0 * w0 / lam); f1 = np.sum(w1 * w1 / lam)
+        if delta_fixed[0] >= 0:
+            delta[t] = delta_fixed[t]
+            contrib[t] = logdet + (f1 if delta[t] else f0)
+        elif f1 < f0:
+            delta[t] = 1; contrib[t] = logdet + f1
+        else:
+            contrib[t] = logdet + f0
+    return state, delta, contrib, True
+
+
+def _garch11_h_py(u, w, a, b, h0):
+    T = u.size
+    h = np.empty(T); h[0] = h0
+    for t in range(1, T):
+        h[t] = w + a * u[t - 1] ** 2 + b * h[t - 1]
+    return h
+
+
+def _dcc_nll_py(e, Qbar, a, b):
+    T, k = e.shape
+    Q = Qbar.copy()
+    nll = 0.0
+    for t in range(T):
+        if t > 0:
+            Q = (1 - a - b) * Qbar + a * np.outer(e[t - 1], e[t - 1]) + b * Q
+        d = 1.0 / np.sqrt(np.diag(Q))
+        R = Q * np.outer(d, d)
+        L = np.linalg.cholesky(R)
+        y = np.linalg.solve(L, e[t])
+        nll += 2.0 * np.log(np.diag(L)).sum() + y @ y - e[t] @ e[t]
+    return 0.5 * nll
+
+
+if HAVE_NUMBA:
+    @njit(cache=True, error_model="numpy")
+    def _dsh_loop_nb(X, Xd, expU, D0, D11, D21, a, c, egarch, delta_fixed):
+        T, k = X.shape
+        state = np.zeros((T, k)); delta = np.zeros(T, np.int64); contrib = np.zeros(T)
+        z = np.empty(k)
+        for t in range(1, T):
+            use_d = delta[t - 1] == 1
+            for i in range(k):
+                s = 0.0
+                for j in range(k):
+                    s += expU[t - 1, j, i] * (Xd[t - 1, j] if use_d else X[t - 1, j])
+                z[i] = s
+            logdet = 0.0
+            for i in range(k):
+                if egarch:
+                    zs = z[i] / np.sqrt(np.exp(state[t - 1, i]))
+                    dd = zs - c[i]
+                    state[t, i] = D0[i] + D11[i] * state[t - 1, i] + D21[i] * (abs(dd) - a[i] * dd)
+                    logdet += state[t, i]
+                else:
+                    state[t, i] = D0[i] + D11[i] * state[t - 1, i] + D21[i] * z[i] * z[i]
+                    if state[t, i] <= 0.0:
+                        return state, delta, contrib, False
+                    logdet += np.log(state[t, i])
+            f0 = 0.0; f1 = 0.0
+            for i in range(k):
+                lam = np.exp(state[t, i]) if egarch else state[t, i]
+                s0 = 0.0; s1 = 0.0
+                for j in range(k):
+                    s0 += expU[t, j, i] * X[t, j]
+                    s1 += expU[t, j, i] * Xd[t, j]
+                f0 += s0 * s0 / lam; f1 += s1 * s1 / lam
+            if delta_fixed[0] >= 0:
+                delta[t] = delta_fixed[t]
+                contrib[t] = logdet + (f1 if delta[t] == 1 else f0)
+            elif f1 < f0:
+                delta[t] = 1; contrib[t] = logdet + f1
+            else:
+                contrib[t] = logdet + f0
+        return state, delta, contrib, True
+
+    @njit(cache=True, error_model="numpy")
+    def _garch11_h_nb(u, w, a, b, h0):
+        T = u.size
+        h = np.empty(T); h[0] = h0
+        for t in range(1, T):
+            h[t] = w + a * u[t - 1] ** 2 + b * h[t - 1]
+        return h
+
+    @njit(cache=True, error_model="numpy")
+    def _dcc_nll_nb(e, Qbar, a, b):
+        T, k = e.shape
+        Q = Qbar.copy()
+        nll = 0.0
+        for t in range(T):
+            if t > 0:
+                for i in range(k):
+                    for j in range(k):
+                        Q[i, j] = (1 - a - b) * Qbar[i, j] + a * e[t - 1, i] * e[t - 1, j] + b * Q[i, j]
+            R = np.empty((k, k))
+            for i in range(k):
+                for j in range(k):
+                    R[i, j] = Q[i, j] / np.sqrt(Q[i, i] * Q[j, j])
+            L = np.linalg.cholesky(R)
+            y = np.linalg.solve(L, e[t])
+            ld = 0.0
+            for i in range(k):
+                ld += 2.0 * np.log(L[i, i])
+            nll += ld + np.dot(y, y) - np.dot(e[t], e[t])
+        return 0.5 * nll
+
+    dsh_loop, garch11_h, dcc_nll = _dsh_loop_nb, _garch11_h_nb, _dcc_nll_nb
+else:  # pragma: no cover
+    dsh_loop, garch11_h, dcc_nll = _dsh_loop_py, _garch11_h_py, _dcc_nll_py

dscc/_filters.py

@@ -0,0 +1,221 @@
+"""Likelihood filters for the DSH / DSCC class.
+
+One pass through the data computes, for every t, the dynamic skew-symmetric
+component Upsilon_t (eq. 2.9), the eigenvalues Lambda_t (GARCH eq. 2.5 or
+EGARCH eq. 2.6-2.7), the in-sample MLE of delta_t, and the Gaussian
+log-likelihood (2.13) of Abadir and Rockinger (2026) / (3.11) of Abadir (2023).
+
+Parameter-vector layout (identical to the authors' replication code, so their
+stored estimates load unchanged), with k variables and l = k(k-1)/2:
+
+    GARCH  : [D0 (k), D11 (k), D21 (k), mu (l), alpha (l), beta (l)]           3k + 3l
+    EGARCH : [D0 (k), D11 (k), D21 (k), mu (l), alpha (l), beta (l), a (k), c (k)]  5k + 3l
+
+Timing conventions (verified line by line against the authors' code):
+
+* t = 1 is a dead start-up: Lambda_1 = O (GARCH) or log Lambda_1 = O (EGARCH),
+  Upsilon_1 = O, delta_1 = 0, and t = 1 does not enter the likelihood
+  (Abadir 2023, after eq. 4.8).
+* Lambda_t uses z_{t-1} = e^{-Upsilon_{t-1}} P^{delta_{t-1}} x_{t-1}   (eq. 2.4-2.5).
+* delta_t is chosen sequentially: given Lambda_t and Upsilon_t, the t-th summand
+  of (2.13) is maximised over delta_t in {0, 1}; ties keep delta_t = 0.
+  (Abadir 2023, Section 4.1: "each of the summands ... maximized with respect
+  to delta_t"; 2T likelihood evaluations instead of 2^T.)
+
+Author: Dr Merwan Roudane <merwanroudane920@gmail.com>
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ._fast import HAVE_NUMBA, dsh_loop
+from ._representation import n_offdiag
+
+__all__ = ["FilterOutput", "unpack_theta", "n_params", "dsh_filter", "g_abs"]
+
+
+@dataclass
+class FilterOutput:
+    """Output of one filtering pass (all arrays are time-major)."""
+
+    negloglik: float            # 0.5 * sum_t [ sum_i log lam_it + x_t' Sigma_t^{-1} x_t ]
+    contributions: np.ndarray   # (T,) the per-t terms (before the 0.5 factor)
+    delta: np.ndarray           # (T,) int, in-sample MLE of delta_t
+    lam: np.ndarray             # (T, k) eigenvalues Lambda_t (levels)
+    ups: np.ndarray             # (T, l) free elements of Upsilon_t
+    expU: np.ndarray            # (T, k, k) e^{Upsilon_t}
+
+
+def n_params(k: int, dynamics: str) -> int:
+    l = n_offdiag(k)
+    return 3 * k + 3 * l + (2 * k if dynamics == "egarch" else 0)
+
+
+def unpack_theta(theta: np.ndarray, k: int, dynamics: str) -> dict:
+    theta = np.asarray(theta, dtype=float).ravel()
+    l = n_offdiag(k)
+    if theta.size != n_params(k, dynamics):
+        raise ValueError(
+            f"theta has {theta.size} elements; {dynamics} with k={k} needs {n_params(k, dynamics)}"
+        )
+    out = {
+        "D0": theta[0:k],
+        "D11": theta[k:2 * k],
+        "D21": theta[2 * k:3 * k],
+        "mu": theta[3 * k:3 * k + l],
+        "alpha": theta[3 * k + l:3 * k + 2 * l],
+        "beta": theta[3 * k + 2 * l:3 * k + 3 * l],
+    }
+    if dynamics == "egarch":
+        out["a"] = theta[3 * k + 3 * l:4 * k + 3 * l]
+        out["c"] = theta[4 * k + 3 * l:5 * k + 3 * l]
+    return out
+
+
+def g_abs(v: np.ndarray, a: np.ndarray, c: np.ndarray) -> np.ndarray:
+    """Asymmetric absolute-value function g_i(v) = |v_i - c_i| - a_i (v_i - c_i), eq. (2.7)."""
+    d = v - c
+    return np.abs(d) - a * d
+
+
+def dsh_filter(
+    theta: np.ndarray,
+    X: np.ndarray,
+    xi: np.ndarray,
+    dynamics: str = "garch",
+    store_expU: bool = True,
+    delta_fixed: np.ndarray | None = None,
+    use_fast: bool = True,
+) -> FilterOutput:
+    """Run the DSH filter and return the negative log-likelihood and paths.
+
+    Parameters
+    ----------
+    theta : parameter vector (layout in the module docstring).
+    X : (T, k) de-meaned data x_t.
+    xi : (T, l) data innovations xi_t = vec(log Q_t), eq. (2.11).
+    dynamics : {"garch", "egarch"} for eq. (2.5) or eq. (2.6).
+    store_expU : keep e^{Upsilon_t} for every t (needed for forecasting).
+    delta_fixed : optional (T,) 0/1 path. When given, delta_t is held at these
+        values instead of being maximised; the likelihood is then smooth in theta,
+        which is what the profile-likelihood standard errors use.
+
+    Returns
+    -------
+    FilterOutput
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dscc._representation import xi_from_data
+    >>> rng = np.random.default_rng(0); X = rng.standard_normal((30, 2))
+    >>> theta = np.r_[[0.02]*2, [0.85]*2, [0.10]*2, -1.0, 0.1, -0.02]
+    >>> out = dsh_filter(theta, X, xi_from_data(X))
+    >>> bool(np.isfinite(out.negloglik))
+    True
+    """
+    X = np.asarray(X, dtype=float)
+    T, k = X.shape
+    l = n_offdiag(k)
+    p = unpack_theta(theta, k, dynamics)
+    D0, D11, D21 = p["D0"], p["D11"], p["D21"]
+    mu, alpha, beta = p["mu"], p["alpha"], p["beta"]
+    const_v = mu * (1.0 - alpha)
+    egarch = dynamics == "egarch"
+    if egarch:
+        a, c = p["a"], p["c"]
+
+    Xd = X.copy()
+    Xd[:, [0, 1]] = X[:, [1, 0]]          # P x_t  (P swaps the first two variates)
+
+    # (2.9): upsilon_t = (1-alpha) mu + alpha upsilon_{t-1} + beta xi_{t-1}, upsilon_1 = 0.
+    # Upsilon_t depends neither on Lambda nor on delta, so the whole path and all
+    # matrix exponentials are computed once, before the Lambda/delta recursion.
+    v = ups_path(const_v, alpha, beta, xi, T)
+    expU = expm_skew_batch(v, k)
+
+    if use_fast and HAVE_NUMBA:
+        dfix = (np.full(1, -1, np.int64) if delta_fixed is None
+                else np.ascontiguousarray(delta_fixed, dtype=np.int64))
+        zk = np.zeros(k)
+        state, delta, contrib, ok = dsh_loop(
+            np.ascontiguousarray(X), np.ascontiguousarray(Xd), expU,
+            np.ascontiguousarray(D0, float), np.ascontiguousarray(D11, float),
+            np.ascontiguousarray(D21, float),
+            np.ascontiguousarray(a, float) if egarch else zk,
+            np.ascontiguousarray(c, float) if egarch else zk, egarch, dfix)
+        if not ok:
+            return FilterOutput(np.inf, np.full(T, np.inf), delta, state, v, expU)
+        lam = np.exp(state) if egarch else state
+        return FilterOutput(0.5 * contrib.sum(), contrib, delta, lam, v,
+                            expU if store_expU else None)
+
+    state = np.zeros((T, k))               # lam_t (garch) or log lam_t (egarch)
+    delta = np.zeros(T, dtype=int)
+    contrib = np.zeros(T)
+
+    for t in range(1, T):
+        # z_{t-1} = e^{-Upsilon_{t-1}} P^{delta_{t-1}} x_{t-1}
+        x_prev = Xd[t - 1] if delta[t - 1] else X[t - 1]
+        z = expU[t - 1].T @ x_prev
+        if egarch:
+            # (2.6): log Lambda_t = D0 + D11 log Lambda_{t-1} + D21 g(Lambda_{t-1}^{-1/2} z_{t-1})
+            zs = z / np.sqrt(np.exp(state[t - 1]))
+            state[t] = D0 + D11 * state[t - 1] + D21 * g_abs(zs, a, c)
+            lam_t = np.exp(state[t])
+            logdet = state[t].sum()
+        else:
+            # (2.5): Lambda_t = D0 + D11 Lambda_{t-1} + D21 dg(z_{t-1} z_{t-1}')
+            state[t] = D0 + D11 * state[t - 1] + D21 * z * z
+            lam_t = state[t]
+            if np.any(lam_t <= 0):
+                contrib[t:] = np.inf
+                return FilterOutput(np.inf, contrib, delta, state, v, expU)
+            logdet = np.log(lam_t).sum()
+
+        E = expU[t]
+        # quadratic forms x' Sigma_t^{-1} x for delta = 0 and delta = 1
+        w0 = E.T @ X[t]
+        w1 = E.T @ Xd[t]
+        f0 = np.sum(w0 * w0 / lam_t)
+        f1 = np.sum(w1 * w1 / lam_t)
+        if delta_fixed is not None:
+            delta[t] = int(delta_fixed[t])
+            contrib[t] = logdet + (f1 if delta[t] else f0)
+        elif f1 < f0:
+            delta[t] = 1
+            contrib[t] = logdet + f1
+        else:
+            contrib[t] = logdet + f0
+
+    lam = np.exp(state) if egarch else state
+    return FilterOutput(0.5 * contrib.sum(), contrib, delta, lam, v,
+                        expU if store_expU else None)
+
+
+def ups_path(const_v, alpha, beta, xi, T: int) -> np.ndarray:
+    """Path of the free elements of Upsilon_t from eq. (2.9), with upsilon_1 = 0."""
+    l = np.size(alpha)
+    v = np.zeros((T, l))
+    for t in range(1, T):
+        v[t] = const_v + alpha * v[t - 1] + beta * xi[t - 1]
+    return v
+
+
+def expm_skew_batch(v: np.ndarray, k: int) -> np.ndarray:
+    """e^{Upsilon_t} for a batch of skew-symmetric matrices.
+
+    For skew-symmetric U, H = iU is Hermitian: H = V diag(w) V^H, hence
+    e^U = V diag(e^{-iw}) V^H (exact; Lemma 2.1 of Abadir 2023). One batched
+    Hermitian eigendecomposition replaces T calls to a general expm.
+    """
+    T = v.shape[0]
+    U = np.zeros((T, k, k))
+    i, j = np.triu_indices(k, 1)
+    U[:, i, j] = v
+    U[:, j, i] = -v
+    w, V = np.linalg.eigh(1j * U)
+    E = (V * np.exp(-1j * w)[:, None, :]) @ np.conj(np.swapaxes(V, 1, 2))
+    return E.real