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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squeeze-kernel
-Version: 0.3.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
@@ -130,6 +130,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

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

@@ -100,6 +100,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

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "squeeze-kernel"
-version = "0.3.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.3.0 → squeeze_kernel-0.4.0}/src/squeeze_kernel/__init__.py

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

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

@@ -93,6 +93,20 @@ 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.
 
     Examples
     --------
@@ -123,6 +137,7 @@ class SqueezeKernelEstimator:
         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
@@ -145,6 +160,9 @@ 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
 
         # Resolve shrinkage
         if isinstance(shrinkage, str):
@@ -384,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