multiarch 0.2.0__py3-none-any.whl

multiarch/diagnostics.py

@@ -0,0 +1,115 @@
+"""Specification tests: constant correlation (Engle & Sheppard 2001),
+multivariate portmanteau (Hosking 1980) and VaR backtests (Kupiec 1995,
+Christoffersen 1998)."""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from .univariate import UnivariateSpec, filter_series, fit_univariate
+
+
+def _sqrtm_inv(R):
+    w, V = np.linalg.eigh(R)
+    return V @ np.diag(w ** -0.5) @ V.T
+
+
+def constant_correlation_test(returns=None, lags=5, vol="garch", mean="constant",
+                              std_resid=None, whiten=True):
+    """Engle & Sheppard (2001) test of H0: constant conditional correlation.
+
+    Fits univariate GARCH margins, whitens the standardised residuals with
+    the CCC correlation matrix, and regresses the stacked off-diagonal
+    outer products on a constant and `lags` own lags. Under H0 all
+    coefficients are zero; the statistic is chi2(lags + 1).
+    Pass `std_resid` to skip the GARCH step (and `whiten=False` if they
+    are already whitened). Returns dict(statistic, pvalue, df).
+    """
+    if std_resid is None:
+        y = returns.to_numpy(float) if isinstance(returns, pd.DataFrame) else np.asarray(returns, float)
+        spec = UnivariateSpec(mean=mean, vol=vol)
+        z = np.column_stack([
+            filter_series(spec, fit_univariate(y[:, i], spec, compute_cov=False).params, y[:, i])[2]
+            for i in range(y.shape[1])
+        ])
+    else:
+        z = np.asarray(std_resid, float)
+    w = z @ _sqrtm_inv(np.corrcoef(z, rowvar=False)) if whiten else z
+    n = w.shape[1]
+    Y, X = [], []
+    for i in range(n - 1):
+        for j in range(i + 1, n):
+            p = w[:, i] * w[:, j]
+            Y.append(p[lags:])
+            X.append(np.column_stack([np.ones(len(p) - lags)]
+                                     + [p[lags - k:len(p) - k] for k in range(1, lags + 1)]))
+    Y = np.concatenate(Y)
+    X = np.vstack(X)
+    beta, *_ = np.linalg.lstsq(X, Y, rcond=None)
+    resid = Y - X @ beta
+    s2 = resid @ resid / len(Y)
+    stat = float(beta @ X.T @ X @ beta / s2)
+    df = lags + 1
+    return {"statistic": stat, "pvalue": float(stats.chi2.sf(stat, df)), "df": df}
+
+
+def hosking_test(x, lags=10, fitted_params=0):
+    """Multivariate portmanteau test (Hosking 1980) for serial correlation
+    in a (T, N) series, e.g. standardised residuals or their squares.
+    Returns dict(statistic, pvalue, df)."""
+    x = np.asarray(x, float)
+    x = x - x.mean(0)
+    T, n = x.shape
+    C0 = x.T @ x / T
+    C0i = np.linalg.inv(C0)
+    stat = 0.0
+    for k in range(1, lags + 1):
+        Ck = x[k:].T @ x[:-k] / T
+        stat += np.trace(Ck.T @ C0i @ Ck @ C0i) / (T - k)
+    stat *= T * T
+    df = n * n * lags - fitted_params
+    return {"statistic": float(stat), "pvalue": float(stats.chi2.sf(stat, df)), "df": df}
+
+
+def var_backtest(returns, var, level=0.01):
+    """Backtest a VaR forecast path.
+
+    returns : realised portfolio returns; var : VaR as positive losses,
+    aligned with `returns`. Reports the violation ratio (observed / expected
+    violations), Kupiec's unconditional coverage test, Christoffersen's
+    independence test and their sum (conditional coverage).
+    """
+    r = np.asarray(returns, float)
+    v = np.asarray(var, float)
+    hit = (r < -v).astype(int)
+    T = hit.size
+    x = int(hit.sum())
+    p = level
+    pi = x / T
+
+    def _xlogy(a, b):
+        return a * np.log(b) if a > 0 else 0.0
+
+    lr_uc = -2 * (_xlogy(T - x, 1 - p) + _xlogy(x, p) - _xlogy(T - x, 1 - pi) - _xlogy(x, pi))
+    h0, h1 = hit[:-1], hit[1:]
+    n00 = int(((h0 == 0) & (h1 == 0)).sum())
+    n01 = int(((h0 == 0) & (h1 == 1)).sum())
+    n10 = int(((h0 == 1) & (h1 == 0)).sum())
+    n11 = int(((h0 == 1) & (h1 == 1)).sum())
+    p01 = n01 / max(n00 + n01, 1)
+    p11 = n11 / max(n10 + n11, 1)
+    p1 = (n01 + n11) / max(n00 + n01 + n10 + n11, 1)
+    lr_ind = -2 * (_xlogy(n00 + n10, 1 - p1) + _xlogy(n01 + n11, p1)
+                   - _xlogy(n00, 1 - p01) - _xlogy(n01, p01)
+                   - _xlogy(n10, 1 - p11) - _xlogy(n11, p11))
+    return {
+        "violations": x,
+        "expected": p * T,
+        "violation_ratio": x / (p * T),
+        "kupiec_stat": float(lr_uc),
+        "kupiec_pvalue": float(stats.chi2.sf(lr_uc, 1)),
+        "independence_stat": float(lr_ind),
+        "independence_pvalue": float(stats.chi2.sf(lr_ind, 1)),
+        "cc_stat": float(lr_uc + lr_ind),
+        "cc_pvalue": float(stats.chi2.sf(lr_uc + lr_ind, 2)),
+    }

multiarch/ewma.py

@@ -0,0 +1,26 @@
+import numpy as np
+from numba import njit
+
+
+@njit(cache=True)
+def _ewma(x, lam, S0):
+    T, n = x.shape
+    out = np.empty((T + 1, n, n))
+    out[0] = S0
+    for t in range(T):
+        out[t + 1] = lam * out[t] + (1 - lam) * np.outer(x[t], x[t])
+    return out
+
+
+def ewma_covariance(returns, lam=0.94, demean=False, init=None):
+    """RiskMetrics EWMA covariance: S_{t+1} = lam S_t + (1-lam) x_t x_t'.
+
+    Returns a (T+1, N, N) array; element t is the forecast for period t
+    made with data up to t-1, so the last element is the one-step-ahead
+    forecast. `init` defaults to the sample covariance.
+    """
+    x = np.asarray(returns, float)
+    if demean:
+        x = x - x.mean(0)
+    S0 = np.cov(x, rowvar=False, bias=True) if init is None else np.asarray(init, float)
+    return _ewma(x, float(lam), S0)

multiarch/gogarch.py

@@ -0,0 +1,220 @@
+"""GO-GARCH (van der Weide 2002) with the ICA rotation of Broda & Paolella
+(2009) / rmgarch: returns are linear combinations of independent factors,
+each following its own univariate GARCH."""
+
+import math
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from .dcc import _analytic_var_es, _normalise, _std_t_ppf
+from .univariate import UnivariateSpec, filter_series, fit_univariate
+
+
+def _sym_decorrelate(W):
+    s, u = np.linalg.eigh(W @ W.T)
+    return u @ np.diag(1 / np.sqrt(s)) @ u.T @ W
+
+
+def fastica(X, seed=0, max_iter=2000, tol=1e-10):
+    """Symmetric FastICA with the log-cosh contrast on whitened data X
+    (N, T). Returns the orthogonal unmixing matrix W (factors = W @ X)."""
+    n, T = X.shape
+    rng = np.random.default_rng(seed)
+    W = _sym_decorrelate(rng.standard_normal((n, n)))
+    for _ in range(max_iter):
+        G = np.tanh(W @ X)
+        W1 = _sym_decorrelate(G @ X.T / T - np.diag((1 - G * G).mean(axis=1)) @ W)
+        lim = np.max(np.abs(np.abs(np.einsum("ij,ij->i", W1, W)) - 1))
+        W = W1
+        if lim < tol:
+            break
+    return W
+
+
+class GOGARCH:
+    """Generalized orthogonal GARCH.
+
+    eps_t = A f_t, with f_it independent GARCH processes of unit
+    unconditional variance and A = P Lambda^{1/2} U' from the PCA of the
+    sample covariance and an ICA rotation U.
+
+    Parameters
+    ----------
+    returns : (T, N) array or DataFrame.
+    vol : factor variance model, "garch" or "gjr".
+    dist : factor distribution, "normal" or "t".
+    mean : "constant" (sample mean, as rmgarch) or "zero".
+    seed : seed for the ICA start (ICA is identified only up to factor
+        order and sign).
+    convention : factor variance start-up, "arch" or "rmgarch" (see DCC).
+    """
+
+    def __init__(self, returns, vol="garch", dist="normal", mean="constant", seed=0,
+                 convention="arch"):
+        if isinstance(returns, pd.DataFrame):
+            self.index = returns.index
+            self.columns = [str(c) for c in returns.columns]
+            y = returns.to_numpy(float)
+        else:
+            y = np.asarray(returns, float)
+            self.index = pd.RangeIndex(y.shape[0])
+            self.columns = [f"x{i}" for i in range(y.shape[1])]
+        if y.ndim != 2 or y.shape[1] < 2:
+            raise ValueError("returns must be (T, N) with N >= 2")
+        self.y = y
+        self.mean = mean
+        self.seed = seed
+        init = {"arch": "arch", "rmgarch": "rugarch", "tsmarch": "tsgarch"}[convention]
+        self.fspec = UnivariateSpec(mean="zero", vol=vol, dist=dist, init=init)
+
+    def fit(self, compute_cov=True, unmixing=None):
+        """Estimate the rotation by ICA and the factor GARCH models.
+        `unmixing` (N, N) fixes the map from demeaned returns to factors
+        (f_t = unmixing @ eps_t) instead of estimating it."""
+        y = self.y
+        mu = y.mean(axis=0) if self.mean == "constant" else np.zeros(y.shape[1])
+        eps = y - mu
+        if unmixing is None:
+            Sigma = eps.T @ eps / len(eps)
+            lam, P = np.linalg.eigh(Sigma)
+            K = np.diag(lam ** -0.5) @ P.T          # whitening
+            W = fastica(K @ eps.T, seed=self.seed)
+            A = P @ np.diag(lam ** 0.5) @ W.T       # mixing: eps = A f
+        else:
+            A = np.linalg.inv(np.asarray(unmixing, float))
+        f = eps @ np.linalg.inv(A).T
+        fits = [fit_univariate(f[:, i], self.fspec, compute_cov=compute_cov)
+                for i in range(f.shape[1])]
+        return GOGARCHResult(self, mu, A, f, fits)
+
+
+@dataclass
+class GOGARCHResult:
+    model: GOGARCH
+    mu: np.ndarray
+    A: np.ndarray
+    factors: np.ndarray = field(repr=False)
+    fits: list = field(repr=False)
+
+    def __post_init__(self):
+        fs = [filter_series(self.model.fspec, ft.params, self.factors[:, i])
+              for i, ft in enumerate(self.fits)]
+        self.factor_sigma2 = np.column_stack([s[1] for s in fs])
+
+    @property
+    def params(self):
+        idx, vals = [], []
+        for i, ft in enumerate(self.fits):
+            idx += [(f"f{i}", nm) for nm in self.model.fspec.names]
+            vals += list(ft.params)
+        return pd.Series(vals, index=pd.MultiIndex.from_tuples(idx), name="params")
+
+    @property
+    def std_err(self):
+        return pd.Series(np.concatenate([ft.std_err for ft in self.fits]),
+                         index=self.params.index, name="std_err")
+
+    @property
+    def loglik(self):
+        """sum of factor log-likelihoods minus T log|det A|."""
+        T = self.factors.shape[0]
+        return float(sum(ft.loglik for ft in self.fits)
+                     - T * np.log(abs(np.linalg.det(self.A))))
+
+    @property
+    def nobs(self):
+        return self.factors.shape[0]
+
+    @property
+    def aic(self):
+        k = self.params.size + self.A.size
+        return -2 * self.loglik + 2 * k
+
+    def summary(self):
+        p, se = self.params, self.std_err
+        df = pd.DataFrame({"coef": p, "std_err": se, "t": p / se})
+        head = (f"GO-GARCH ({self.model.fspec.vol}, {self.model.fspec.dist})  "
+                f"T={self.nobs}  N={len(self.model.columns)}  loglik={self.loglik:.3f}\n")
+        return head + df.to_string(float_format=lambda x: f"{x: .5g}")
+
+    def __repr__(self):
+        return self.summary()
+
+    @property
+    def conditional_covariance(self):
+        """(T, N, N) array of H_t = A diag(h_t) A'."""
+        return np.einsum("ik,tk,jk->tij", self.A, self.factor_sigma2, self.A)
+
+    @property
+    def conditional_correlation(self):
+        H = self.conditional_covariance
+        d = 1 / np.sqrt(np.diagonal(H, axis1=1, axis2=2))
+        return H * d[:, :, None] * d[:, None, :]
+
+    @property
+    def conditional_volatility(self):
+        H = self.conditional_covariance
+        return pd.DataFrame(np.sqrt(np.diagonal(H, axis1=1, axis2=2)),
+                            index=self.model.index, columns=self.model.columns)
+
+    def _factor_forecast(self, horizon):
+        out = np.empty((horizon, len(self.fits)))
+        for i, ft in enumerate(self.fits):
+            _, omega, alpha, gamma, beta, _ = self.model.fspec.unpack(ft.params)
+            e = self.factors[-1, i]
+            s = omega + alpha * e * e + beta * self.factor_sigma2[-1, i] + (gamma * e * e if e < 0 else 0)
+            pers = alpha + 0.5 * gamma + beta
+            for h in range(horizon):
+                out[h, i] = s
+                s = omega + pers * s
+        return out
+
+    def forecast(self, horizon=1):
+        h = self._factor_forecast(horizon)
+        cov = np.einsum("ik,tk,jk->tij", self.A, h, self.A)
+        return {"mean": np.tile(self.mu, (horizon, 1)), "covariance": cov,
+                "correlation": np.array([_normalise(c) for c in cov]),
+                "variance": np.diagonal(cov, axis1=1, axis2=2).copy()}
+
+    def simulate(self, nobs, n_paths=1, start="end", burn=500, seed=None):
+        """Simulate return paths; start "end" continues from the sample."""
+        rng = np.random.default_rng(seed)
+        ups = np.array([self.model.fspec.unpack(ft.params) for ft in self.fits])
+        _, omega, alpha, gamma, beta, nus = ups.T
+        n = len(self.fits)
+        if start == "end":
+            s2 = np.tile(self._factor_forecast(1)[0], (n_paths, 1))
+            burn = 0
+        else:
+            s2 = np.tile(omega / (1 - alpha - 0.5 * gamma - beta), (n_paths, 1))
+        out = np.empty((n_paths, nobs, len(self.mu)))
+        for t in range(burn + nobs):
+            z = rng.standard_normal((n_paths, n))
+            for i, nu in enumerate(nus):
+                if nu > 0:
+                    z[:, i] = _std_t_ppf(rng.uniform(size=n_paths), nu)
+            fct = np.sqrt(s2) * z
+            if t >= burn:
+                out[:, t - burn] = self.mu + fct @ self.A.T
+            s2 = omega + (alpha + gamma * (fct < 0)) * fct ** 2 + beta * s2
+        return {"returns": out}
+
+    def value_at_risk(self, weights, level=0.01, horizon=1, method=None,
+                      n_sims=100_000, value=1.0, seed=None):
+        """Portfolio VaR/ES (positive losses). Analytic for one period with
+        normal factors, otherwise by simulation."""
+        w = np.asarray(weights, float)
+        if method is None:
+            method = ("analytic" if horizon == 1 and self.model.fspec.dist == "normal"
+                      else "simulation")
+        if method == "analytic":
+            f = self.forecast(1)
+            var, es = _analytic_var_es(self.mu @ w, math.sqrt(w @ f["covariance"][0] @ w), level)
+        else:
+            pr = (self.simulate(horizon, n_paths=n_sims, seed=seed)["returns"] @ w).sum(axis=1)
+            q = np.quantile(pr, level)
+            var, es = -q, -pr[pr <= q].mean()
+        return {"VaR": float(value * var), "ES": float(value * es)}

multiarch/rolling.py

@@ -0,0 +1,69 @@
+"""Rolling-window estimation and one-step-ahead forecasts, for backtesting."""
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from .dcc import DCC, _analytic_var_es
+
+
+@dataclass
+class RollingForecast:
+    """One-step-ahead forecasts for periods window..T-1.
+
+    mean (n, N), covariance (n, N, N), and nu (n,) for multivariate-t models
+    (NaN otherwise). Row k is the forecast for `index[k]`, made with data up
+    to the previous period only.
+    """
+
+    index: pd.Index
+    columns: list
+    mean: np.ndarray
+    covariance: np.ndarray
+    nu: np.ndarray
+
+    def portfolio_variance(self, weights):
+        w = np.asarray(weights, float)
+        return pd.Series(np.einsum("i,tij,j->t", w, self.covariance, w), index=self.index)
+
+    def value_at_risk(self, weights, level=0.01, value=1.0):
+        """Analytic one-step VaR/ES path (positive numbers are losses)."""
+        w = np.asarray(weights, float)
+        mean = self.mean @ w
+        sd = np.sqrt(self.portfolio_variance(w).to_numpy())
+        var = np.empty(len(mean))
+        es = np.empty(len(mean))
+        for k in range(len(mean)):
+            nu = None if np.isnan(self.nu[k]) else self.nu[k]
+            var[k], es[k] = _analytic_var_es(mean[k], sd[k], level, nu)
+        return pd.DataFrame({"VaR": value * var, "ES": value * es}, index=self.index)
+
+
+def rolling_forecast(returns, window, refit_every=20, expanding=False, **model_kwargs):
+    """Re-estimate a DCC model every `refit_every` periods on a rolling (or
+    expanding) window and filter forward between refits with the parameters
+    held fixed. Uses no information from the forecast period.
+
+    `model_kwargs` are passed to `DCC` (model, vol, dist, ...). Copula models
+    are supported for the covariance path, but their VaR needs simulation.
+    """
+    df = returns if isinstance(returns, pd.DataFrame) else pd.DataFrame(np.asarray(returns, float))
+    y = df.to_numpy(float)
+    T, n = y.shape
+    if window >= T:
+        raise ValueError("window must be shorter than the sample")
+    means, covs, nus = [], [], []
+    for k in range(window, T, refit_every):
+        lo = 0 if expanding else k - window
+        res = DCC(y[lo:k], **model_kwargs).fit(se=None)
+        hi = min(k + refit_every, T)
+        # filter the estimation window plus the next block; row t of the
+        # filtered covariance only uses data up to t-1
+        ap = res.apply(y[lo:hi], sigma2_0=res.sigma2[0])
+        sl = slice(k - lo, hi - lo)
+        covs.append(ap.conditional_covariance[sl])
+        means.append(ap.conditional_mean[sl])
+        nus.append(np.full(hi - k, res.nu if res.nu else np.nan))
+    return RollingForecast(df.index[window:], [str(c) for c in df.columns],
+                           np.concatenate(means), np.concatenate(covs), np.concatenate(nus))

multiarch/simulate.py

@@ -0,0 +1,43 @@
+import numpy as np
+
+from . import _kernels as K
+
+
+def simulate_dcc(nobs, mu, omega, alpha, beta, Qbar, a, b, gamma=None, g=0.0,
+                 Nbar=None, nu=None, burn=500, seed=None, Q0=None, sigma2_0=None,
+                 shocks=None):
+    """Simulate returns from GJR-GARCH(1,1) margins + (A)DCC correlation.
+
+    nu : degrees of freedom for unit-variance multivariate-t shocks
+         (None for Gaussian).
+    Q0, sigma2_0 : starting state (default: unconditional, Qbar and
+         omega / (1 - persistence)).
+    shocks : optional (nobs + burn, N) iid unit-variance, uncorrelated
+         innovations, e.g. copula draws; overrides `nu`.
+    Returns (returns, sigma2, std_resid), each (nobs, N).
+    """
+    rng = np.random.default_rng(seed)
+    omega = np.asarray(omega, float)
+    n = omega.size
+    mu = np.broadcast_to(np.asarray(mu, float), (n,)).copy()
+    alpha = np.asarray(alpha, float)
+    beta = np.asarray(beta, float)
+    gamma = np.zeros(n) if gamma is None else np.asarray(gamma, float)
+    Qbar = np.asarray(Qbar, float)
+    Nbar = np.zeros_like(Qbar) if Nbar is None else np.asarray(Nbar, float)
+    T = nobs + burn
+    Q0 = Qbar if Q0 is None else np.asarray(Q0, float)
+    if sigma2_0 is None:
+        sigma2_0 = omega / (1 - alpha - 0.5 * gamma - beta)
+    sigma2_0 = np.asarray(sigma2_0, float)
+    if shocks is not None:
+        return K.simulate_path(mu, omega, alpha, gamma, beta, Qbar, Nbar,
+                               float(a), float(b), float(g), np.asarray(shocks, float),
+                               burn, Q0, sigma2_0)
+    x = rng.standard_normal((T, n))
+    if nu is not None:
+        # multivariate t: common chi-square mixing, scaled to unit variance
+        w = rng.chisquare(nu, size=T) / nu
+        x = x / np.sqrt(w)[:, None] * np.sqrt((nu - 2) / nu)
+    return K.simulate_path(mu, omega, alpha, gamma, beta, Qbar, Nbar,
+                           float(a), float(b), float(g), x, burn, Q0, sigma2_0)

multiarch/univariate.py

@@ -0,0 +1,213 @@
+"""Univariate GARCH(1,1) / GJR-GARCH(1,1) margins, the first stage of DCC.
+
+Conventions (start-up backcast, unit-variance Student-t, parameter order)
+follow the `arch` package so results are directly comparable.
+"""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy.optimize import minimize
+
+from . import _kernels as K
+from ._numdiff import hessian, jacobian
+
+
+def backcast(resid):
+    """arch's exponential backcast for the pre-sample variance."""
+    tau = min(75, resid.shape[0])
+    w = 0.94 ** np.arange(tau)
+    w /= w.sum()
+    return float(np.sum(resid[:tau] ** 2 * w))
+
+
+@dataclass
+class UnivariateSpec:
+    mean: str = "constant"  # "constant" or "zero"
+    vol: str = "garch"  # "garch" or "gjr"
+    dist: str = "normal"  # "normal" or "t"
+    # start-up of the variance recursion: "arch" (exponential backcast,
+    # sigma2_0 = omega + persistence * backcast), "rugarch"
+    # (sigma2_0 = full-sample mean of squared residuals) or "tsgarch"
+    # (sigma2_0 = omega + persistence * mean of squared residuals)
+    init: str = "arch"
+
+    def __post_init__(self):
+        if self.mean not in ("constant", "zero"):
+            raise ValueError("mean must be 'constant' or 'zero'")
+        if self.vol not in ("garch", "gjr"):
+            raise ValueError("vol must be 'garch' or 'gjr'")
+        if self.dist not in ("normal", "t"):
+            raise ValueError("dist must be 'normal' or 't'")
+        if self.init not in ("arch", "rugarch", "tsgarch"):
+            raise ValueError("init must be 'arch', 'rugarch' or 'tsgarch'")
+
+    @property
+    def names(self):
+        n = ["mu"] if self.mean == "constant" else []
+        n += ["omega", "alpha"]
+        if self.vol == "gjr":
+            n.append("gamma")
+        n.append("beta")
+        if self.dist == "t":
+            n.append("nu")
+        return n
+
+    def unpack(self, p):
+        """-> mu, omega, alpha, gamma, beta, nu  (nu=0 means normal)."""
+        k = 0
+        mu = 0.0
+        if self.mean == "constant":
+            mu = p[0]
+            k = 1
+        omega, alpha = p[k], p[k + 1]
+        k += 2
+        gamma = 0.0
+        if self.vol == "gjr":
+            gamma = p[k]
+            k += 1
+        beta = p[k]
+        nu = p[k + 1] if self.dist == "t" else 0.0
+        return mu, omega, alpha, gamma, beta, nu
+
+
+def _sigma2_0(spec, omega, alpha, gamma, beta, resid):
+    if spec.init == "rugarch":
+        return float(np.mean(resid * resid))
+    if spec.init == "tsgarch":
+        return omega + (alpha + 0.5 * gamma + beta) * float(np.mean(resid * resid))
+    return omega + (alpha + 0.5 * gamma + beta) * backcast(resid)
+
+
+def loglik_obs(spec, p, y):
+    mu, omega, alpha, gamma, beta, nu = spec.unpack(p)
+    resid = y - mu
+    s0 = _sigma2_0(spec, omega, alpha, gamma, beta, resid)
+    sigma2 = K.garch_filter(omega, alpha, gamma, beta, resid, s0)
+    if nu > 0:
+        return K.std_t_loglik_obs(resid, sigma2, nu)
+    return K.normal_loglik_obs(resid, sigma2)
+
+
+def filter_series(spec, p, y, sigma2_0=None):
+    """-> (residuals, conditional variance, standardised residuals).
+    `sigma2_0` overrides the start-up variance."""
+    mu, omega, alpha, gamma, beta, _ = spec.unpack(p)
+    resid = y - mu
+    s0 = _sigma2_0(spec, omega, alpha, gamma, beta, resid) if sigma2_0 is None else sigma2_0
+    sigma2 = K.garch_filter(omega, alpha, gamma, beta, resid, s0)
+    return resid, sigma2, resid / np.sqrt(sigma2)
+
+
+@dataclass
+class UnivariateFit:
+    spec: UnivariateSpec
+    params: np.ndarray
+    loglik: float
+    cov: np.ndarray = field(repr=False)
+    converged: bool = True
+
+    @property
+    def std_err(self):
+        return np.sqrt(np.diag(self.cov))
+
+
+def _start_values(spec, y):
+    var = float(np.var(y))
+    best, best_ll = None, -np.inf
+    for alpha in (0.03, 0.08, 0.15):
+        for beta in (0.75, 0.85, 0.92):
+            gamma = 0.05 if spec.vol == "gjr" else 0.0
+            if alpha + beta + gamma / 2 >= 0.995:
+                continue
+            p = []
+            if spec.mean == "constant":
+                p.append(float(np.mean(y)))
+            p += [var * (1 - alpha - beta - gamma / 2), alpha]
+            if spec.vol == "gjr":
+                p.append(gamma)
+            p.append(beta)
+            if spec.dist == "t":
+                p.append(8.0)
+            p = np.array(p)
+            ll = loglik_obs(spec, p, y).sum()
+            if ll > best_ll:
+                best, best_ll = p, ll
+    return best
+
+
+def rescale(spec, p, s):
+    """Map parameters estimated on y/s back to the scale of y.
+    Returns (params, jacobian diagonal)."""
+    J = np.array([{"mu": s, "omega": s * s}.get(nm, 1.0) for nm in spec.names])
+    return p * J, J
+
+
+def fit_univariate(y, spec=None, compute_cov=True):
+    """QML / ML fit of a single GARCH margin. Covariance is the robust
+    (Bollerslev-Wooldridge) sandwich, matching arch's default.
+
+    The fit runs on y / sd(y) and is mapped back, so results do not depend
+    on whether returns are in percent or fractions."""
+    spec = spec or UnivariateSpec()
+    y = np.asarray(y, dtype=float)
+    s = float(np.std(y))
+    f = _fit_unit(y / s, spec, compute_cov)
+    p, J = rescale(spec, f.params, s)
+    cov = f.cov * np.outer(J, J)
+    return UnivariateFit(spec, p, f.loglik - y.shape[0] * np.log(s), cov, f.converged)
+
+
+def _fit_unit(y, spec, compute_cov):
+    names = spec.names
+    var = float(np.var(y))
+    scale = max(abs(float(np.mean(y))), 1e-8)
+
+    bounds = []
+    for nm in names:
+        bounds.append(
+            {
+                "mu": (-10 * scale - 10 * np.sqrt(var), 10 * scale + 10 * np.sqrt(var)),
+                "omega": (1e-8 * var, 2.0 * var),
+                "alpha": (0.0, 1.0),
+                "gamma": (-1.0, 2.0),
+                "beta": (0.0, 1.0),
+                "nu": (2.05, 500.0),
+            }[nm]
+        )
+    ia, ib = names.index("alpha"), names.index("beta")
+    ig = names.index("gamma") if "gamma" in names else None
+
+    def persistence_gap(p):
+        g = p[ig] / 2 if ig is not None else 0.0
+        return 1.0 - 1e-6 - p[ia] - p[ib] - g
+
+    cons = [{"type": "ineq", "fun": persistence_gap}]
+    if ig is not None:  # alpha + gamma >= 0 keeps the variance positive
+        cons.append({"type": "ineq", "fun": lambda p: p[ia] + p[ig]})
+
+    def obj(p):
+        ll = loglik_obs(spec, p, y).sum()
+        return -ll if np.isfinite(ll) else 1e10
+
+    x0 = _start_values(spec, y)
+    res = minimize(
+        obj, x0, method="SLSQP", bounds=bounds, constraints=cons,
+        options={"maxiter": 1000, "ftol": 1e-10},
+    )
+    p = res.x
+    ll = -res.fun
+    cov = np.full((len(p), len(p)), np.nan)
+    if compute_cov:
+        cov = robust_cov(lambda q: loglik_obs(spec, q, y), p)
+    return UnivariateFit(spec, p, ll, cov, bool(res.success))
+
+
+def robust_cov(ll_obs_fn, p):
+    """Sandwich covariance A^{-1} B A^{-1} / T from per-observation log-likelihoods."""
+    scores = jacobian(ll_obs_fn, p)  # T x k
+    T = scores.shape[0]
+    H = hessian(lambda q: ll_obs_fn(q).sum(), p) / T
+    B = scores.T @ scores / T
+    Ainv = np.linalg.inv(H)
+    return Ainv @ B @ Ainv / T