squeeze-kernel 0.3.0__tar.gz → 0.5.0__tar.gz

{squeeze_kernel-0.3.0 → squeeze_kernel-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squeeze-kernel
-Version: 0.3.0
+Version: 0.5.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
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 A **streaming covariance estimator for panels of daily financial returns**. One `O(n²)` update per day, positive semi-definite **by construction** at every step, missing values handled **natively**, and defaults that require no tuning. Only dependency: NumPy.
 
-Reference: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026).
+Reference: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918).
 
 ## Why
 
@@ -116,6 +116,14 @@ kappa = SqueezeKernelEstimator.calibrate_kappa(burn_in_returns, target_weight=0.
 
 ## Advanced options
 
+**Scale-free correlation memory** (`corr_half_lives=(43, 173, 693)`, `corr_theta=0.25`): replaces the single correlation timescale with a positive combination of EWMAs on a geometric half-life ladder — each scale normalized and adaptively shrunk against its own effective sample size, then the covariances blended with weights ∝ half-life^`corr_theta`. By Bernstein's theorem this approximates the power-law memory of financial correlations (the streaming analogue of HAR); positive weights keep it PSD by construction, and `None` (default) reproduces the published single-scale estimator exactly. This is the paper's **headline configuration**: on the S&P 500 benchmark it leads every tested method at every universe size (held-out one-step NLL −3.9 at n=100, up to −18 at n=300 before the cluster target), and the 90% model confidence set collapses to it alone. Cost is O(K·n²) per update. Composes with `shrinkage_target="cluster"`; mutually exclusive with `lambda_corr_fast`.
+
+```python
+est = SqueezeKernelEstimator(n_assets=100, corr_half_lives=(43, 173, 693), corr_theta=0.25)
+# maximal variant at high dimension:
+est = SqueezeKernelEstimator(n_assets=300, corr_half_lives=(43, 173, 693), shrinkage_target="cluster")
+```
+
 **Score-exact weighting** (`weight_statistic="mahalanobis"`, use with `kappa=1.0`): drives the kernel with the Mahalanobis surprise `z'C⁻¹z/N` against the estimator's own correlation instead of the marginal dispersion. Improves accuracy in the moderate-concentration regime — use only when `n / T_eff ≲ 0.5` (e.g. n ≤ 100 at the default `lambda_corr`); at higher concentration the estimated inverse degrades it and the default is strictly better.
 
 ```python
@@ -130,6 +138,12 @@ est = SqueezeKernelEstimator(n_assets=100, kappa=1.0, weight_statistic="mahalano
 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
@@ -159,7 +173,8 @@ Releases: publishing a GitHub release from a `v*` tag triggers the [publish work
 @article{kende2026squeeze,
   title  = {The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage},
   author = {Kende, Robert},
-  year   = {2026}
+  year   = {2026},
+  note   = {Available at SSRN: \url{https://ssrn.com/abstract=6455918}}
 }
 ```
 

{squeeze_kernel-0.3.0 → squeeze_kernel-0.5.0}/README.md

@@ -7,7 +7,7 @@
 
 A **streaming covariance estimator for panels of daily financial returns**. One `O(n²)` update per day, positive semi-definite **by construction** at every step, missing values handled **natively**, and defaults that require no tuning. Only dependency: NumPy.
 
-Reference: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026).
+Reference: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918).
 
 ## Why
 
@@ -86,6 +86,14 @@ kappa = SqueezeKernelEstimator.calibrate_kappa(burn_in_returns, target_weight=0.
 
 ## Advanced options
 
+**Scale-free correlation memory** (`corr_half_lives=(43, 173, 693)`, `corr_theta=0.25`): replaces the single correlation timescale with a positive combination of EWMAs on a geometric half-life ladder — each scale normalized and adaptively shrunk against its own effective sample size, then the covariances blended with weights ∝ half-life^`corr_theta`. By Bernstein's theorem this approximates the power-law memory of financial correlations (the streaming analogue of HAR); positive weights keep it PSD by construction, and `None` (default) reproduces the published single-scale estimator exactly. This is the paper's **headline configuration**: on the S&P 500 benchmark it leads every tested method at every universe size (held-out one-step NLL −3.9 at n=100, up to −18 at n=300 before the cluster target), and the 90% model confidence set collapses to it alone. Cost is O(K·n²) per update. Composes with `shrinkage_target="cluster"`; mutually exclusive with `lambda_corr_fast`.
+
+```python
+est = SqueezeKernelEstimator(n_assets=100, corr_half_lives=(43, 173, 693), corr_theta=0.25)
+# maximal variant at high dimension:
+est = SqueezeKernelEstimator(n_assets=300, corr_half_lives=(43, 173, 693), shrinkage_target="cluster")
+```
+
 **Score-exact weighting** (`weight_statistic="mahalanobis"`, use with `kappa=1.0`): drives the kernel with the Mahalanobis surprise `z'C⁻¹z/N` against the estimator's own correlation instead of the marginal dispersion. Improves accuracy in the moderate-concentration regime — use only when `n / T_eff ≲ 0.5` (e.g. n ≤ 100 at the default `lambda_corr`); at higher concentration the estimated inverse degrades it and the default is strictly better.
 
 ```python
@@ -100,6 +108,12 @@ est = SqueezeKernelEstimator(n_assets=100, kappa=1.0, weight_statistic="mahalano
 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
@@ -129,7 +143,8 @@ Releases: publishing a GitHub release from a `v*` tag triggers the [publish work
 @article{kende2026squeeze,
   title  = {The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage},
   author = {Kende, Robert},
-  year   = {2026}
+  year   = {2026},
+  note   = {Available at SSRN: \url{https://ssrn.com/abstract=6455918}}
 }
 ```
 

{squeeze_kernel-0.3.0 → squeeze_kernel-0.5.0}/pyproject.toml

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

{squeeze_kernel-0.3.0 → squeeze_kernel-0.5.0}/src/squeeze_kernel/__init__.py

@@ -34,4 +34,4 @@ __all__ = [
     "kernel_chi2_cdf",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"

{squeeze_kernel-0.3.0 → squeeze_kernel-0.5.0}/src/squeeze_kernel/estimator.py

@@ -2,12 +2,17 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import numpy as np
 
 from squeeze_kernel.kernels import (
     KernelFn, kernel_fisher, calibrate_kappa, extract_d2_series,
 )
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 
 class SqueezeKernelEstimator:
     """Streaming robust covariance estimator with pluggable kernel weighting.
@@ -93,6 +98,42 @@ class SqueezeKernelEstimator:
         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.
+    corr_half_lives : sequence of float, optional
+        Scale-free correlation memory.  When set, the single correlation
+        timescale is replaced by a positive combination of EWMAs on the
+        given geometric half-life ladder (in trading days, e.g.
+        ``(43, 173, 693)``): each scale is normalised and adaptively
+        shrunk against its own effective sample size, and the resulting
+        covariances are blended with weights ∝ half-life\\ :sup:`corr_theta`.
+        By Bernstein's theorem this approximates the power-law memory of
+        financial correlations (the streaming analogue of HAR).  PSD by
+        construction (positive combination of PSD matrices).  ``None``
+        (default) is the published single-scale estimator, bit-for-bit;
+        a one-element ladder reduces to a single-scale estimator at that
+        half-life.  Mutually exclusive with ``lambda_corr_fast``; composes
+        with ``shrinkage_target='cluster'``.  Cost is O(K·n²) per update.
+        Held-out one-step NLL on the S&P-500 benchmark improves at every
+        dimension (−3.9 at n=100, up to −18 at n=300 before the cluster
+        target); the $90\\%$ model confidence set collapses to this
+        configuration alone.  Recommended default: the base-centred ladder
+        ``(43, 173, 693)`` with ``corr_theta=0.25``.
+    corr_theta : float
+        Long-memory exponent controlling the ladder weights (default
+        0.25).  Only used when ``corr_half_lives`` is set.
 
     Examples
     --------
@@ -123,6 +164,9 @@ class SqueezeKernelEstimator:
         lambda_corr_fast: float | None = None,
         vol_anchor_phi: float | None = None,
         vol_anchor_decay: float = 0.999,
+        shrinkage_target: str = "equicorrelation",
+        corr_half_lives: "Sequence[float] | None" = None,
+        corr_theta: float = 0.25,
     ):
         self.n_assets = n_assets
         self.lambda_vol = lambda_vol
@@ -145,6 +189,37 @@ class SqueezeKernelEstimator:
             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
+
+        # Scale-free correlation memory (opt-in): replace the single correlation
+        # timescale by a positive combination of EWMAs on a geometric half-life
+        # ladder, blended per-scale (Mode A). None => single-scale, published
+        # behaviour bit-for-bit. See ``corr_half_lives`` in the class docstring.
+        self.corr_half_lives = None
+        self.corr_theta = corr_theta
+        self._corr_lam: np.ndarray | None = None
+        self._corr_w: np.ndarray | None = None
+        self._M_list: list[np.ndarray] | None = None
+        self._S_list: list[float] | None = None
+        if corr_half_lives is not None:
+            hl = np.asarray(corr_half_lives, dtype=np.float64)
+            if hl.ndim != 1 or hl.size < 1 or np.any(hl <= 0.0):
+                raise ValueError("corr_half_lives must be a non-empty sequence of positive half-lives.")
+            if corr_theta < 0.0:
+                raise ValueError("corr_theta must be >= 0.")
+            if lambda_corr_fast is not None:
+                raise ValueError(
+                    "corr_half_lives and lambda_corr_fast are mutually exclusive "
+                    "correlation-memory mechanisms; set at most one."
+                )
+            self.corr_half_lives = hl
+            self._corr_lam = 2.0 ** (-1.0 / hl)
+            w = hl ** corr_theta
+            self._corr_w = w / w.sum()
+            self._M_list = [np.eye(n_assets, dtype=np.float64) * epsilon for _ in hl]
+            self._S_list = [float(epsilon) for _ in hl]
 
         # Resolve shrinkage
         if isinstance(shrinkage, str):
@@ -259,22 +334,45 @@ class SqueezeKernelEstimator:
         if self.impute_missing and 0 < n_obs < n:
             self._impute(z_t, finite)
 
-        # ── Correlation EWMA (in-place to avoid per-step allocations) ──
-        lam_c = self.lambda_corr
-        if self.lambda_corr_fast is not None:
-            # Score-driven memory: stress days (w_t → 1) shorten the memory
-            # toward lambda_corr_fast; calm days keep the slow decay.
-            lam_c = self.lambda_corr + (self.lambda_corr_fast - self.lambda_corr) * w_t
-        self._S_t = lam_c * self._S_t + w_t
-        self._M_t *= lam_c
-        if w_t > 0.0 and n_obs > 0:
-            # np.multiply.outer with out= avoids the temporary that
-            # np.outer otherwise allocates each step.
-            np.multiply.outer(z_t, z_t, out=self._scratch_outer)
-            self._M_t += w_t * self._scratch_outer
-
-        # ── Extract covariance ──
-        self._cov, self._corr = self._extract(vol_t)
+        if self._corr_lam is None:
+            # ── Single-scale correlation EWMA (published path, unchanged) ──
+            lam_c = self.lambda_corr
+            if self.lambda_corr_fast is not None:
+                # Score-driven memory: stress days (w_t → 1) shorten the memory
+                # toward lambda_corr_fast; calm days keep the slow decay.
+                lam_c = self.lambda_corr + (self.lambda_corr_fast - self.lambda_corr) * w_t
+            self._S_t = lam_c * self._S_t + w_t
+            self._M_t *= lam_c
+            if w_t > 0.0 and n_obs > 0:
+                # np.multiply.outer with out= avoids the temporary that
+                # np.outer otherwise allocates each step.
+                np.multiply.outer(z_t, z_t, out=self._scratch_outer)
+                self._M_t += w_t * self._scratch_outer
+            self._cov, self._corr = self._extract(vol_t)
+        else:
+            # ── Scale-free ladder (Mode A) ──
+            # Update K correlation accumulators on the geometric half-life
+            # ladder; normalise and adaptively shrink each against its OWN
+            # effective sample size, then blend the per-scale covariances.
+            add = w_t > 0.0 and n_obs > 0
+            if add:
+                np.multiply.outer(z_t, z_t, out=self._scratch_outer)
+            cov = np.zeros((n, n), dtype=np.float64)
+            s_eff = 0.0
+            for k in range(self._corr_lam.size):
+                self._S_list[k] = self._corr_lam[k] * self._S_list[k] + w_t
+                self._M_list[k] *= self._corr_lam[k]
+                if add:
+                    self._M_list[k] += w_t * self._scratch_outer
+                cov_k, _ = self._extract(vol_t, self._M_list[k], self._S_list[k])
+                cov += self._corr_w[k] * cov_k
+                s_eff += self._corr_w[k] * self._S_list[k]
+            cov = 0.5 * (cov + cov.T)
+            self._cov = cov
+            self._S_t = s_eff                        # blended effective size (for the property)
+            d = np.sqrt(np.maximum(np.diagonal(cov), eps))
+            self._corr = cov / np.outer(d, d)
+            np.fill_diagonal(self._corr, 1.0)
         self._last_weight = w_t
         return w_t
 
@@ -355,22 +453,23 @@ class SqueezeKernelEstimator:
             if den > 0.0:
                 z_t[i] = num / den
 
-    def _extract(self, vol_t: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    def _extract(self, vol_t: np.ndarray, M_t=None, S_in=None) -> tuple[np.ndarray, np.ndarray]:
         eps = self.epsilon
-        S_t = max(self._S_t, eps)
+        M_t = self._M_t if M_t is None else M_t
+        S_t = max(self._S_t if S_in is None else S_in, eps)
         n = self.n_assets
 
         # Normalised standardised covariance matrix sigma_z = M_t / S_t.
         # Compute correlations directly into the cached scratch buffer to
         # avoid two intermediate allocations (sigma_z and corr).
-        diag_z = np.diagonal(self._M_t).copy()
+        diag_z = np.diagonal(M_t).copy()
         diag_z /= S_t                                # in-place
         inv_diag = 1.0 / np.sqrt(np.maximum(diag_z, eps))
         # corr_ij = (M_ij / S_t) * inv_diag_i * inv_diag_j; this writes
         # the rescaled outer-product into _scratch_corr in one pass.
         np.multiply.outer(inv_diag, inv_diag, out=self._scratch_corr)
         corr = self._scratch_corr
-        corr *= self._M_t                            # in-place; corr = sigma_z * outer(inv_diag,inv_diag)
+        corr *= M_t                                  # in-place; corr = sigma_z * outer(inv_diag,inv_diag)
         corr *= (1.0 / S_t)                          # absorb the M_t / S_t scale
         np.fill_diagonal(corr, np.where(diag_z > eps, 1.0, 0.0))
 
@@ -384,9 +483,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