squeeze-kernel 0.2.0__tar.gz → 0.4.0__tar.gz

{squeeze_kernel-0.2.0 → squeeze_kernel-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squeeze-kernel
-Version: 0.2.0
+Version: 0.4.0
 Summary: Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage
 Keywords: covariance,correlation,ewma,kernel,risk,streaming
 Author: Robert Kende
@@ -124,6 +124,18 @@ est = SqueezeKernelEstimator(n_assets=100, kappa=1.0, weight_statistic="mahalano
 
 **Score-driven memory** (`lambda_corr_fast=0.99`): lets stress days also *shorten* the correlation memory (decay slides from `lambda_corr` toward `lambda_corr_fast` as the kernel weight rises). Do **not** combine with the Mahalanobis option — they act on the same channel and the combination degrades accuracy.
 
+**OU volatility anchor** (`vol_anchor_phi=0.995`): mean-reverts each asset's variance prediction toward a slow per-asset anchor (a ~1000-day EWMA of squared returns) before the daily update — a two-timescale, component-style volatility structure. One global parameter with a clean interpretation (deviation half-life ≈ ln 2/(1−φ) days; φ=0.995 ≈ 139 d). On the S&P 500 n=100 benchmark this improved held-out one-step NLL by 3.3 points (4.3 at φ=0.99) and five-step NLL by 3.9 (5.0), with no degradation at n=300. `None` (default) or φ=1 reproduces the published estimator exactly.
+
+```python
+est = SqueezeKernelEstimator(n_assets=100, vol_anchor_phi=0.995)
+```
+
+**Cluster shrinkage target** (`shrinkage_target="cluster"`): generalizes the equicorrelation shrinkage target to respect the correlation matrix's own block/cluster structure — with **no clustering algorithm**. The target morphs with the shrinkage intensity, T = (1−α)·T_equi + α·[(1−γ)I + γ·(C∘C)], where C∘C is the Hadamard square of the current correlation (positive semi-definite by the Schur product theorem; entries are pairwise shared-variance fractions) and γ is level-matched automatically. Zero added parameters, still O(n²), and as α→0 it reduces exactly to the default estimator. Held-out one-step NLL on the S&P 500 benchmark: ±0.1 at n=100, **−4.2 at n=200, −25.0 at n=300** — recommended whenever the universe size approaches the effective sample size.
+
+```python
+est = SqueezeKernelEstimator(n_assets=300, shrinkage_target="cluster")
+```
+
 **Alternative kernels**: pass `kernel_fn=kernel_exponential` (with `kernel_kwargs={"gamma": ...}`) or `kernel_chi2_cdf`, or any callable `(d2, *, n_observed, **kw) -> float` mapping to `[0, 1)`. The PSD guarantee holds for any such kernel.
 
 ## How it works

{squeeze_kernel-0.2.0 → squeeze_kernel-0.4.0}/README.md

@@ -94,6 +94,18 @@ est = SqueezeKernelEstimator(n_assets=100, kappa=1.0, weight_statistic="mahalano
 
 **Score-driven memory** (`lambda_corr_fast=0.99`): lets stress days also *shorten* the correlation memory (decay slides from `lambda_corr` toward `lambda_corr_fast` as the kernel weight rises). Do **not** combine with the Mahalanobis option — they act on the same channel and the combination degrades accuracy.
 
+**OU volatility anchor** (`vol_anchor_phi=0.995`): mean-reverts each asset's variance prediction toward a slow per-asset anchor (a ~1000-day EWMA of squared returns) before the daily update — a two-timescale, component-style volatility structure. One global parameter with a clean interpretation (deviation half-life ≈ ln 2/(1−φ) days; φ=0.995 ≈ 139 d). On the S&P 500 n=100 benchmark this improved held-out one-step NLL by 3.3 points (4.3 at φ=0.99) and five-step NLL by 3.9 (5.0), with no degradation at n=300. `None` (default) or φ=1 reproduces the published estimator exactly.
+
+```python
+est = SqueezeKernelEstimator(n_assets=100, vol_anchor_phi=0.995)
+```
+
+**Cluster shrinkage target** (`shrinkage_target="cluster"`): generalizes the equicorrelation shrinkage target to respect the correlation matrix's own block/cluster structure — with **no clustering algorithm**. The target morphs with the shrinkage intensity, T = (1−α)·T_equi + α·[(1−γ)I + γ·(C∘C)], where C∘C is the Hadamard square of the current correlation (positive semi-definite by the Schur product theorem; entries are pairwise shared-variance fractions) and γ is level-matched automatically. Zero added parameters, still O(n²), and as α→0 it reduces exactly to the default estimator. Held-out one-step NLL on the S&P 500 benchmark: ±0.1 at n=100, **−4.2 at n=200, −25.0 at n=300** — recommended whenever the universe size approaches the effective sample size.
+
+```python
+est = SqueezeKernelEstimator(n_assets=300, shrinkage_target="cluster")
+```
+
 **Alternative kernels**: pass `kernel_fn=kernel_exponential` (with `kernel_kwargs={"gamma": ...}`) or `kernel_chi2_cdf`, or any callable `(d2, *, n_observed, **kw) -> float` mapping to `[0, 1)`. The PSD guarantee holds for any such kernel.
 
 ## How it works

{squeeze_kernel-0.2.0 → squeeze_kernel-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "squeeze-kernel"
-version = "0.2.0"
+version = "0.4.0"
 description = "Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage"
 readme = "README.md"
 license = "MIT"

{squeeze_kernel-0.2.0 → squeeze_kernel-0.4.0}/src/squeeze_kernel/__init__.py

@@ -34,4 +34,4 @@ __all__ = [
     "kernel_chi2_cdf",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{squeeze_kernel-0.2.0 → squeeze_kernel-0.4.0}/src/squeeze_kernel/estimator.py

@@ -74,6 +74,39 @@ class SqueezeKernelEstimator:
         Do not combine with ``weight_statistic='mahalanobis'`` — the two
         mechanisms act on the same reactivity channel and their combination
         degraded out-of-sample accuracy in testing.
+    vol_anchor_phi : float or None
+        If set, enables the OU volatility anchor: each asset's variance
+        prediction mean-reverts toward a slow per-asset anchor before the
+        measurement update, v_pred = v̄ + φ·(v − v̄), with the anchor v̄ a
+        slow EWMA of squared returns (see ``vol_anchor_decay``).  φ is the
+        per-step retention of deviations from the anchor (deviation
+        half-life ≈ ln 2 / (1 − φ) days); φ = 1 or ``None`` (default)
+        reproduces the published estimator exactly.  Recommended φ = 0.995
+        (conservative; the range [0.99, 0.995] is robust).  On the S&P-500
+        n=100 benchmark this improved held-out one-step NLL by 3.3 points
+        (φ=0.995; 4.3 at φ=0.99) and five-step NLL by 3.9 (5.0), with no
+        degradation at n=300.  Mechanism: a two-timescale (component-style)
+        volatility structure — it changes persistence, not shock response.
+        Validated with the default marginal kernel; interaction with the
+        correlation-side extensions above is untested.
+    vol_anchor_decay : float
+        Decay of the slow per-asset variance anchor (default 0.999,
+        effective memory ≈ 1000 trading days).  Only used when
+        ``vol_anchor_phi`` is set.
+    shrinkage_target : str
+        Geometry of the adaptive shrinkage target.  ``'equicorrelation'``
+        (default) is the published single-factor target.  ``'cluster'``
+        uses the concentration-morphing cluster target
+        T = (1−α)·T_equi + α·[(1−γ)I + γ·(C∘C)], where C∘C is the Hadamard
+        square of the current correlation (PSD by the Schur product
+        theorem) and γ = min(1, ρ̄/mean-offdiag(C∘C)) level-matches the
+        target to the equicorrelation mass.  Respects the correlation
+        matrix's own block/cluster structure without any clustering
+        algorithm; adds no parameters and stays O(n²).  As α → 0 it
+        reduces exactly to the published estimator, so behaviour at low
+        concentration is unchanged.  Held-out one-step NLL on the S&P-500
+        benchmark: +0.14 (negligible) at n=100, −4.2 at n=200, −25.0 at
+        n=300.  Recommended when n approaches the effective sample size.
 
     Examples
     --------
@@ -102,6 +135,9 @@ class SqueezeKernelEstimator:
         impute_threshold: float = 0.6,
         weight_statistic: str = "marginal",
         lambda_corr_fast: float | None = None,
+        vol_anchor_phi: float | None = None,
+        vol_anchor_decay: float = 0.999,
+        shrinkage_target: str = "equicorrelation",
     ):
         self.n_assets = n_assets
         self.lambda_vol = lambda_vol
@@ -118,6 +154,15 @@ class SqueezeKernelEstimator:
         if lambda_corr_fast is not None and not (0.0 < lambda_corr_fast < 1.0):
             raise ValueError("lambda_corr_fast must be in (0, 1).")
         self.lambda_corr_fast = lambda_corr_fast
+        if vol_anchor_phi is not None and not (0.0 < vol_anchor_phi <= 1.0):
+            raise ValueError("vol_anchor_phi must be in (0, 1].")
+        if not (0.0 < vol_anchor_decay < 1.0):
+            raise ValueError("vol_anchor_decay must be in (0, 1).")
+        self.vol_anchor_phi = vol_anchor_phi
+        self.vol_anchor_decay = vol_anchor_decay
+        if shrinkage_target not in ("equicorrelation", "cluster"):
+            raise ValueError("shrinkage_target must be 'equicorrelation' or 'cluster'.")
+        self.shrinkage_target = shrinkage_target
 
         # Resolve shrinkage
         if isinstance(shrinkage, str):
@@ -132,6 +177,7 @@ class SqueezeKernelEstimator:
         # State
         self._var_t: np.ndarray | None = None
         self._var_init: np.ndarray | None = None
+        self._var_anchor: np.ndarray | None = None
         self._M_t = np.eye(n_assets, dtype=np.float64) * epsilon
         self._S_t = float(epsilon)
         self._cov: np.ndarray | None = None
@@ -172,17 +218,38 @@ class SqueezeKernelEstimator:
         if self._var_t is None:
             self._var_t = np.zeros(n, dtype=np.float64)
             self._var_init = np.zeros(n, dtype=bool)
+            if self.vol_anchor_phi is not None:
+                self._var_anchor = np.zeros(n, dtype=np.float64)
 
         first = finite & ~self._var_init
         repeat = finite & self._var_init
         if np.any(first):
             self._var_t[first] = r_t[first] ** 2 + eps
             self._var_init[first] = True
+            if self._var_anchor is not None:
+                self._var_anchor[first] = self._var_t[first]
         if np.any(repeat):
-            self._var_t[repeat] = (
-                self.lambda_vol * self._var_t[repeat]
-                + (1.0 - self.lambda_vol) * r_t[repeat] ** 2
-            )
+            if self.vol_anchor_phi is None:
+                self._var_t[repeat] = (
+                    self.lambda_vol * self._var_t[repeat]
+                    + (1.0 - self.lambda_vol) * r_t[repeat] ** 2
+                )
+            else:
+                # OU anchor: mean-revert the variance prediction toward a slow
+                # per-asset anchor before the measurement update, then update
+                # the anchor itself (order matters and matches the validated
+                # experiment: prediction uses the *old* anchor).
+                phi = self.vol_anchor_phi
+                lam_bar = self.vol_anchor_decay
+                anchor = self._var_anchor[repeat]
+                v_pred = anchor + phi * (self._var_t[repeat] - anchor)
+                self._var_t[repeat] = (
+                    self.lambda_vol * v_pred
+                    + (1.0 - self.lambda_vol) * r_t[repeat] ** 2
+                )
+                self._var_anchor[repeat] = (
+                    lam_bar * anchor + (1.0 - lam_bar) * r_t[repeat] ** 2
+                )
 
         vol_t = np.zeros(n, dtype=np.float64)
         vol_t[self._var_init] = np.sqrt(self._var_t[self._var_init])
@@ -335,9 +402,25 @@ class SqueezeKernelEstimator:
         if alpha > 0.0 and n > 1:
             # Off-diagonal mean: O(n^2) sum, no mask allocation.
             rho_bar = (corr.sum() - corr.trace()) / self._n_off
-            corr *= (1.0 - alpha)
-            corr += alpha * rho_bar
-            np.fill_diagonal(corr, 1.0)
+            if self.shrinkage_target == "equicorrelation" or rho_bar <= 0.0:
+                corr *= (1.0 - alpha)
+                corr += alpha * rho_bar
+                np.fill_diagonal(corr, 1.0)
+            else:
+                # Cluster (concentration-morphing) target:
+                #   T = (1-alpha) T_equi + alpha [(1-gamma) I + gamma (C o C)]
+                # C o C is the Hadamard square of the raw correlation (PSD by
+                # the Schur product theorem, unit diagonal for free); gamma is
+                # level-matched so the target carries the same average
+                # correlation mass as the equicorrelation target.  As
+                # alpha -> 0 this reduces exactly to the published estimator.
+                had = corr * corr                       # Hadamard square, O(n^2)
+                mean_off = (had.sum() - np.trace(had)) / self._n_off
+                gamma = min(1.0, rho_bar / max(mean_off, eps))
+                corr *= (1.0 - alpha)
+                corr += (alpha * (1.0 - alpha)) * rho_bar
+                corr += (alpha * alpha * gamma) * had
+                np.fill_diagonal(corr, 1.0)
 
         # Build covariance from corr and vol_t.  We need an output array
         # that the caller can keep, so allocate one cov here (cannot reuse