squeeze-kernel 0.6.0__tar.gz → 0.7.1__tar.gz

{squeeze_kernel-0.6.0 → squeeze_kernel-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: squeeze-kernel
-Version: 0.6.0
+Version: 0.7.1
 Summary: Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage
 Keywords: covariance,correlation,ewma,kernel,risk,streaming
 Author: Robert Kende
@@ -19,6 +19,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: pytest>=7.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.7 ; extra == 'dev'
 Requires-Dist: scipy>=1.11 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
 Requires-Dist: scipy>=1.11 ; extra == 'full'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/r0k3/squeeze-kernel
@@ -35,13 +36,13 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-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.
+A **streaming covariance estimator for panels of financial returns** that learns fastest on the days that matter. One `O(n²)` update per period, 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) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918).
+References: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918) — and its companion *"Cluster-Respecting Shrinkage for Streaming Covariance Estimation"* (Kende, 2026).
 
 ## Why
 
-Rolling-window estimators (Ledoit–Wolf, nonlinear shrinkage, RMT denoising) refit over a fixed window each day and cannot adapt within it; multivariate GARCH (DCC) adapts but needs multi-stage estimation and a fragile news coefficient. The Squeeze Kernel is a single streaming recursion that:
+Every standard covariance estimator treats all trading days as equally informative. Markets don't work that way: **correlations reveal themselves when markets move; calm days are mostly noise.** The Squeeze Kernel weighs each day by the information it actually carries — quiet days barely count, dispersion shocks pass through in full — and runs volatility and correlation on separate clocks, so vol spikes never contaminate the correlation estimate. The result is a single streaming recursion that:
 
 - **is PSD at every step, structurally** — never needs eigenvalue clipping, nearest-PSD projection, or a solver;
 - **adapts fastest exactly when it matters** — a Fisher-information kernel up-weights high-dispersion (stress) days, when correlation regimes actually move;
@@ -49,7 +50,37 @@ Rolling-window estimators (Ledoit–Wolf, nonlinear shrinkage, RMT denoising) re
 - **ingests missing values natively** — listings, delistings, and halts enter as `NaN`; no imputation or complete-case subsetting;
 - **is fast** — a full 30-year daily pass takes ~0.75 s at n=100 and ~3.4 s at n=300 (single-threaded), 30–40× faster than rolling-window baselines at scale.
 
-On a 30-year S&P 500 panel (n=100, ~7,600 out-of-sample days) it statistically ties DCC on one-step density forecasts and beats EWMA, Ledoit–Wolf, OAS, nonlinear shrinkage, RMT denoising, and the Gerber statistic — and it is the only method in the 90% model confidence set together with DCC. At n=300 it leads every competitor that remains statistically viable.
+**The scoreboard.** On a 30-year S&P 500 panel (~7,600 out-of-sample days) the default single-scale estimator beats EWMA, Ledoit–Wolf, OAS, nonlinear shrinkage, RMT denoising, and the Gerber statistic on one-step density forecasts, and statistically ties DCC — the only two methods in the 90% model confidence set. The headline configuration (multi-scale correlation memory, `corr_half_lives=(43, 173, 693)`) goes further: it **leads every tested method at every universe size and the 90% model confidence set collapses to it alone**, with the margin confirmed out-of-time on an external industry panel. For large equity universes, the cluster shrinkage target (`shrinkage_target="cluster"`) adds a further large gain exactly where shrinkage binds: 25 NLL points at n=300.
+
+Against the alternatives:
+
+- **RiskMetrics / EWMA** — same one-recursion simplicity, but two clocks and information weighting: better forecasts at zero extra operational cost.
+- **Ledoit–Wolf, nonlinear shrinkage, RMT denoising** — static snapshots refit from scratch on a rolling window each day; the Squeeze Kernel is genuinely dynamic, more accurate on the benchmark, and 30–40× faster at scale.
+- **DCC-GARCH** — matched (single-scale) or beaten (multi-scale) without multi-stage likelihood fitting or the fragile news-impact coefficient; at n=300 DCC needs a multi-year warm-up before its forecasts stabilise and still trails by ~25 NLL.
+- **Gerber statistic** — the Squeeze Kernel is a PSD-by-construction generalization of the same robust-comovement idea: no nearest-PSD repair step, and it wins the head-to-head.
+
+## See the difference
+
+Take a passive strategy any allocator would recognize: a long-only minimum-variance portfolio of 300 liquid US stocks, scaled to a 15% volatility target, rebalanced once a month, with 5 bps trading costs. Run it twice on identical data. The only thing that changes between the two runs is the covariance matrix that picks the weights and sets the exposure.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio_dark.png">
+  <img alt="Vol-targeted long-only minimum-variance portfolio on 300 US equities: Squeeze Kernel vs Ledoit-Wolf equity curves, drawdown, realized volatility, and risk/return profile" src="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio.png">
+</picture>
+
+| Method | CAGR | Vol | Sharpe | MaxDD | Calmar | Vol-target RMSE |
+|---|---|---|---|---|---|---|
+| **Squeeze Kernel** | **13.1%** | **13.0%** | **1.00** | **-31.2%** | **0.42** | **6.47%** |
+| Ledoit-Wolf (252d) | 11.7% | 14.6% | 0.80 | -38.7% | 0.30 | 7.51% |
+
+You can regenerate this example from the repo alone. The returns panel ships as a parquet (daily returns for 300 US stocks, sourced from Yahoo Finance), and the script prints the table and redraws the figure:
+
+```bash
+pip install squeeze-kernel pandas pyarrow scikit-learn matplotlib
+python examples/vol_targeted_portfolio.py    # ~2 minutes
+```
+
+The full protocol and data notes live in [`examples/vol_targeted_portfolio.py`](examples/vol_targeted_portfolio.py) and [`examples/data/build_equity_panel.py`](examples/data/build_equity_panel.py).
 
 ## Installation
 
@@ -116,44 +147,27 @@ kappa = SqueezeKernelEstimator.calibrate_kappa(burn_in_returns, target_weight=0.
 
 ## Advanced options
 
-**Adaptive 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 resting at the prior ∝ half-life^`corr_theta`. By Bernstein's theorem the ladder approximates the power-law memory of financial correlations (the streaming analogue of HAR). For ladders of two or more rungs the blend weights are gated by a sequential surprise detector: a two-sided Page CUSUM on the studentized fast-vs-slow per-rung predictive-score drift (threshold set by Siegmund's average-run-length approximation at ~2 years, no tuned parameters) tilts the weights toward the fast or slow end of the ladder when one side accumulates statistically forced evidence, decaying back at the fastest rung's half-life. Weights equal the prior on all non-alarmed days, the blend stays convex, so PSD holds by construction; `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 −4.6 vs single-scale at n=100, −11.1 at n=300 before the cluster target), the 90% model confidence set collapses to it alone, and the detector's margin is confirmed out-of-time on an external industry panel (+0.53 NLL/day, p=1×10⁻⁴). Cost is O(K·n²) per update plus one Cholesky per rung per day for the detector scores. Composes with `shrinkage_target="cluster"`; mutually exclusive with `lambda_corr_fast`.
+All options are off by default; the defaults reproduce the published estimator exactly. Full derivations and benchmark tables are in the papers.
 
-```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")
-```
+**Multi-scale correlation memory** (`corr_half_lives=(43, 173, 693)`): replaces the single correlation timescale with a ladder of EWMAs whose blend a sequential surprise detector tilts toward fast or slow memory as the evidence demands. This is the papers' headline configuration: it leads every tested method at every universe size, and the blend stays convex so PSD still holds by construction.
 
-**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.
+**Cluster shrinkage target** (`shrinkage_target="cluster"`): shrinks toward a target that respects the correlation matrix's own block structure instead of a single equicorrelation, with no clustering algorithm and zero added parameters. The best choice for large equity universes: worth 4 held-out NLL points at n=200 and 25 at n=300 on the benchmark.
 
 ```python
-est = SqueezeKernelEstimator(n_assets=100, kappa=1.0, weight_statistic="mahalanobis")
+# recommended setup for a large equity universe:
+est = SqueezeKernelEstimator(n_assets=300, corr_half_lives=(43, 173, 693),
+                             shrinkage_target="cluster")
 ```
 
-**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.
+**OU volatility anchor** (`vol_anchor_phi=0.995`): mean-reverts each asset's variance forecast toward a slow per-asset anchor, giving a two-timescale volatility structure with a single parameter (deviation half-life ≈ ln 2/(1−φ) days). Worth 3–5 NLL points on the benchmark.
 
-```python
-est = SqueezeKernelEstimator(n_assets=100, vol_anchor_phi=0.995)
-```
+**Score-exact weighting** (`weight_statistic="mahalanobis"`, use with `kappa=1.0`): drives the kernel with the Mahalanobis surprise against the estimator's own correlation. Use it only in the moderate-concentration regime (`n / T_eff ≲ 0.5`).
 
-**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.
+**Score-driven memory** (`lambda_corr_fast=0.99`): lets stress days also shorten the correlation memory. Do not combine with the Mahalanobis option.
 
-```python
-est = SqueezeKernelEstimator(n_assets=300, shrinkage_target="cluster")
-```
+**New-listing usability gate** (`min_obs=60`): exposes a `usable_mask` property marking assets with at least `min_obs` observations, so deployments can exclude cold starts from scoring and optimization; the estimates themselves are unchanged.
 
-**New-listing usability gate** (`min_obs=60`): on an expanding universe, an asset's forecast rows are dominated by its single-observation variance initialization for its first weeks of life and are unusable for scoring or portfolio construction (measured ≈ +2,800 NLL/day on days whose scored set included such assets, on a 42-instrument multi-asset panel). `min_obs` gates nothing inside the estimator — states warm normally, all outputs are unchanged — it exposes a `usable_mask` property marking assets with at least `min_obs` finite observations, so deployments subset with it:
-
-```python
-est = SqueezeKernelEstimator(n_assets=42, min_obs=60)
-# ... update loop ...
-m = est.usable_mask
-cov_usable = est.get_cov()[np.ix_(m, m)]
-```
-
-**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.
+**Alternative kernels**: pass `kernel_fn=kernel_exponential` or `kernel_chi2_cdf`, or any callable mapping to `[0, 1)`; the PSD guarantee holds for any such kernel.
 
 ## How it works
 
@@ -171,11 +185,10 @@ The complete update is a natural-gradient step on the Gaussian log-likelihood, w
 uv sync --extra full --extra dev
 uv run python -m pytest        # test suite
 uv run python -m ruff check .  # lint
+uv run mypy                      # strict type check (src/squeeze_kernel)
 uv build                       # build sdist + wheel
 ```
 
-Releases: publishing a GitHub release from a `v*` tag triggers the [publish workflow](.github/workflows/publish.yml), which builds and uploads to PyPI via trusted publishing.
-
 ## Citation
 
 ```bibtex

squeeze_kernel-0.7.1/README.md

@@ -0,0 +1,176 @@
+# Squeeze Kernel Covariance Estimator
+
+[![CI](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
+[![Python](https://img.shields.io/pypi/pyversions/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A **streaming covariance estimator for panels of financial returns** that learns fastest on the days that matter. One `O(n²)` update per period, positive semi-definite **by construction** at every step, missing values handled **natively**, and defaults that require no tuning. Only dependency: NumPy.
+
+References: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918) — and its companion *"Cluster-Respecting Shrinkage for Streaming Covariance Estimation"* (Kende, 2026).
+
+## Why
+
+Every standard covariance estimator treats all trading days as equally informative. Markets don't work that way: **correlations reveal themselves when markets move; calm days are mostly noise.** The Squeeze Kernel weighs each day by the information it actually carries — quiet days barely count, dispersion shocks pass through in full — and runs volatility and correlation on separate clocks, so vol spikes never contaminate the correlation estimate. The result is a single streaming recursion that:
+
+- **is PSD at every step, structurally** — never needs eigenvalue clipping, nearest-PSD projection, or a solver;
+- **adapts fastest exactly when it matters** — a Fisher-information kernel up-weights high-dispersion (stress) days, when correlation regimes actually move;
+- **regularises itself** — an adaptive equicorrelation shrinkage activates automatically as the asset count approaches the effective sample size, with a provable condition-number bound;
+- **ingests missing values natively** — listings, delistings, and halts enter as `NaN`; no imputation or complete-case subsetting;
+- **is fast** — a full 30-year daily pass takes ~0.75 s at n=100 and ~3.4 s at n=300 (single-threaded), 30–40× faster than rolling-window baselines at scale.
+
+**The scoreboard.** On a 30-year S&P 500 panel (~7,600 out-of-sample days) the default single-scale estimator beats EWMA, Ledoit–Wolf, OAS, nonlinear shrinkage, RMT denoising, and the Gerber statistic on one-step density forecasts, and statistically ties DCC — the only two methods in the 90% model confidence set. The headline configuration (multi-scale correlation memory, `corr_half_lives=(43, 173, 693)`) goes further: it **leads every tested method at every universe size and the 90% model confidence set collapses to it alone**, with the margin confirmed out-of-time on an external industry panel. For large equity universes, the cluster shrinkage target (`shrinkage_target="cluster"`) adds a further large gain exactly where shrinkage binds: 25 NLL points at n=300.
+
+Against the alternatives:
+
+- **RiskMetrics / EWMA** — same one-recursion simplicity, but two clocks and information weighting: better forecasts at zero extra operational cost.
+- **Ledoit–Wolf, nonlinear shrinkage, RMT denoising** — static snapshots refit from scratch on a rolling window each day; the Squeeze Kernel is genuinely dynamic, more accurate on the benchmark, and 30–40× faster at scale.
+- **DCC-GARCH** — matched (single-scale) or beaten (multi-scale) without multi-stage likelihood fitting or the fragile news-impact coefficient; at n=300 DCC needs a multi-year warm-up before its forecasts stabilise and still trails by ~25 NLL.
+- **Gerber statistic** — the Squeeze Kernel is a PSD-by-construction generalization of the same robust-comovement idea: no nearest-PSD repair step, and it wins the head-to-head.
+
+## See the difference
+
+Take a passive strategy any allocator would recognize: a long-only minimum-variance portfolio of 300 liquid US stocks, scaled to a 15% volatility target, rebalanced once a month, with 5 bps trading costs. Run it twice on identical data. The only thing that changes between the two runs is the covariance matrix that picks the weights and sets the exposure.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio_dark.png">
+  <img alt="Vol-targeted long-only minimum-variance portfolio on 300 US equities: Squeeze Kernel vs Ledoit-Wolf equity curves, drawdown, realized volatility, and risk/return profile" src="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio.png">
+</picture>
+
+| Method | CAGR | Vol | Sharpe | MaxDD | Calmar | Vol-target RMSE |
+|---|---|---|---|---|---|---|
+| **Squeeze Kernel** | **13.1%** | **13.0%** | **1.00** | **-31.2%** | **0.42** | **6.47%** |
+| Ledoit-Wolf (252d) | 11.7% | 14.6% | 0.80 | -38.7% | 0.30 | 7.51% |
+
+You can regenerate this example from the repo alone. The returns panel ships as a parquet (daily returns for 300 US stocks, sourced from Yahoo Finance), and the script prints the table and redraws the figure:
+
+```bash
+pip install squeeze-kernel pandas pyarrow scikit-learn matplotlib
+python examples/vol_targeted_portfolio.py    # ~2 minutes
+```
+
+The full protocol and data notes live in [`examples/vol_targeted_portfolio.py`](examples/vol_targeted_portfolio.py) and [`examples/data/build_equity_panel.py`](examples/data/build_equity_panel.py).
+
+## Installation
+
+```bash
+pip install squeeze-kernel          # NumPy only
+pip install "squeeze-kernel[full]"  # + SciPy (kappa calibration, chi² kernel)
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from squeeze_kernel import SqueezeKernelEstimator
+
+# daily_returns: array of shape (T, n) — may contain NaN for missing assets
+est = SqueezeKernelEstimator(n_assets=daily_returns.shape[1])
+
+for r_t in daily_returns:          # stream one day at a time
+    est.update(r_t)
+
+cov  = est.get_cov()               # (n, n) covariance, PSD by construction
+corr = est.get_corr()              # (n, n) correlation
+```
+
+That is the whole API for most uses. The defaults (`lambda_vol=0.98`, `lambda_corr=0.996`, `kappa=0.25`) are the paper-recommended settings for daily returns, selected by time-series cross-validation and robust across a 50× parameter sweep — deploy them as-is.
+
+Batch mode, if you prefer the full path in one call:
+
+```python
+from squeeze_kernel import estimate_squeeze_cov
+
+cov_path, corr_path, weights = estimate_squeeze_cov(daily_returns, with_weights=True)
+# cov_path: (T, n, n) — the estimate after each day
+```
+
+A complete runnable walkthrough (streaming, missing data, batch) is in [`examples/quickstart.py`](examples/quickstart.py).
+
+## Missing values
+
+Pass `NaN` for any asset not observed on a given day — nothing else to do:
+
+```python
+r_t = np.array([0.004, np.nan, -0.011])   # asset 2 not trading today
+est.update(r_t)                            # PSD preserved, no imputation
+```
+
+## Parameters
+
+| Parameter | Default | Meaning |
+|---|---|---|
+| `lambda_vol` | `0.98` | volatility EWMA decay (half-life ≈ 34 days) |
+| `lambda_corr` | `0.996` | correlation EWMA decay (half-life ≈ 173 days, T_eff ≈ 250) |
+| `kappa` | `0.25` | Fisher kernel saturation; higher = stronger calm-day filtering |
+| `shrinkage` | `"auto"` | adaptive equicorrelation shrinkage (`"none"` or a float to override) |
+| `shrinkage_delta` | `0.10` | concentration threshold at which shrinkage activates |
+
+Useful read-only state after each `update()`: `est.weight` (last kernel weight), `est.effective_sample_size` (kernel-weighted T_eff), `est.shrinkage_intensity` (current α).
+
+To recalibrate `kappa` for a different asset class (requires the `full` extra):
+
+```python
+kappa = SqueezeKernelEstimator.calibrate_kappa(burn_in_returns, target_weight=0.6)
+```
+
+## Advanced options
+
+All options are off by default; the defaults reproduce the published estimator exactly. Full derivations and benchmark tables are in the papers.
+
+**Multi-scale correlation memory** (`corr_half_lives=(43, 173, 693)`): replaces the single correlation timescale with a ladder of EWMAs whose blend a sequential surprise detector tilts toward fast or slow memory as the evidence demands. This is the papers' headline configuration: it leads every tested method at every universe size, and the blend stays convex so PSD still holds by construction.
+
+**Cluster shrinkage target** (`shrinkage_target="cluster"`): shrinks toward a target that respects the correlation matrix's own block structure instead of a single equicorrelation, with no clustering algorithm and zero added parameters. The best choice for large equity universes: worth 4 held-out NLL points at n=200 and 25 at n=300 on the benchmark.
+
+```python
+# recommended setup for a large equity universe:
+est = SqueezeKernelEstimator(n_assets=300, corr_half_lives=(43, 173, 693),
+                             shrinkage_target="cluster")
+```
+
+**OU volatility anchor** (`vol_anchor_phi=0.995`): mean-reverts each asset's variance forecast toward a slow per-asset anchor, giving a two-timescale volatility structure with a single parameter (deviation half-life ≈ ln 2/(1−φ) days). Worth 3–5 NLL points on the benchmark.
+
+**Score-exact weighting** (`weight_statistic="mahalanobis"`, use with `kappa=1.0`): drives the kernel with the Mahalanobis surprise against the estimator's own correlation. Use it only in the moderate-concentration regime (`n / T_eff ≲ 0.5`).
+
+**Score-driven memory** (`lambda_corr_fast=0.99`): lets stress days also shorten the correlation memory. Do not combine with the Mahalanobis option.
+
+**New-listing usability gate** (`min_obs=60`): exposes a `usable_mask` property marking assets with at least `min_obs` observations, so deployments can exclude cold starts from scoring and optimization; the estimates themselves are unchanged.
+
+**Alternative kernels**: pass `kernel_fn=kernel_exponential` or `kernel_chi2_cdf`, or any callable mapping to `[0, 1)`; the PSD guarantee holds for any such kernel.
+
+## How it works
+
+Three mechanisms in one recursion:
+
+1. **Dual-timescale EWMA** — fast per-asset volatility (`lambda_vol`) is separated from slow correlation dynamics (`lambda_corr`), so variance shocks don't contaminate the correlation estimate.
+2. **Fisher kernel weighting** — each day's standardized outer product enters with weight `w = d²/(d² + kappa)`, where `d²` is the mean squared standardized return: calm days contribute little, dispersion shocks contribute fully.
+3. **Adaptive equicorrelation shrinkage** — `alpha = min(1, max(0, n/(2·S) − delta))` blends toward an equicorrelation target using the estimator's own kernel-weighted sample size `S`; it is a no-op at low dimension and provides provably bounded conditioning at high dimension.
+
+The complete update is a natural-gradient step on the Gaussian log-likelihood, with the kernel weight acting as an adaptive Riemannian learning rate (paper, Appendix B).
+
+## Development
+
+```bash
+uv sync --extra full --extra dev
+uv run python -m pytest        # test suite
+uv run python -m ruff check .  # lint
+uv run mypy                      # strict type check (src/squeeze_kernel)
+uv build                       # build sdist + wheel
+```
+
+## Citation
+
+```bibtex
+@article{kende2026squeeze,
+  title  = {The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage},
+  author = {Kende, Robert},
+  year   = {2026},
+  note   = {Available at SSRN: \url{https://ssrn.com/abstract=6455918}}
+}
+```
+
+See also [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT

squeeze_kernel-0.7.1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["uv_build>=0.10.6,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "squeeze-kernel"
+version = "0.7.1"
+description = "Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = [
+    "covariance",
+    "correlation",
+    "ewma",
+    "kernel",
+    "risk",
+    "streaming",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = ["numpy>=1.24"]
+
+[[project.authors]]
+name = "Robert Kende"
+
+[project.urls]
+Homepage = "https://github.com/r0k3/squeeze-kernel"
+Repository = "https://github.com/r0k3/squeeze-kernel"
+Issues = "https://github.com/r0k3/squeeze-kernel/issues"
+
+[project.optional-dependencies]
+full = ["scipy>=1.11"]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.7",
+    "scipy>=1.11",
+    "mypy>=1.10",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src/squeeze_kernel"]
+strict = true
+
+[[tool.mypy.overrides]]
+module = "scipy.*"
+ignore_missing_imports = true

squeeze_kernel-0.6.0/pyproject.toml → squeeze_kernel-0.7.1/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "squeeze-kernel"
-version = "0.6.0"
+version = "0.7.1"
 description = "Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage"
 readme = "README.md"
 license = "MIT"
@@ -32,7 +32,15 @@ Issues = "https://github.com/r0k3/squeeze-kernel/issues"
 
 [project.optional-dependencies]
 full = ["scipy>=1.11"]
-dev = ["pytest>=7.0", "ruff>=0.7", "scipy>=1.11"]
+dev = ["pytest>=7.0", "ruff>=0.7", "scipy>=1.11", "mypy>=1.10"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src/squeeze_kernel"]
+strict = true
+
+[[tool.mypy.overrides]]
+module = "scipy.*"
+ignore_missing_imports = true

{squeeze_kernel-0.6.0 → squeeze_kernel-0.7.1}/src/squeeze_kernel/__init__.py

@@ -34,4 +34,4 @@ __all__ = [
     "kernel_chi2_cdf",
 ]
 
-__version__ = "0.6.0"
+__version__ = "0.7.1"

{squeeze_kernel-0.6.0 → squeeze_kernel-0.7.1}/src/squeeze_kernel/batch.py

@@ -2,69 +2,59 @@
 
 from __future__ import annotations
 
+from typing import Any
+
 import numpy as np
+from numpy.typing import ArrayLike
 
 from squeeze_kernel.estimator import SqueezeKernelEstimator
-from squeeze_kernel.kernels import KernelFn
 
 
 def estimate_squeeze_cov(
-    returns,
+    returns: ArrayLike,
     *,
-    lambda_vol: float = 0.98,
-    lambda_corr: float = 0.996,
-    kappa: float | None = None,
-    kernel_fn: KernelFn | None = None,
-    kernel_kwargs: dict[str, object] | None = None,
-    epsilon: float = 1e-8,
-    shrinkage: str | float = "auto",
-    shrinkage_delta: float = 0.10,
-    impute_missing: bool = False,
-    impute_threshold: float = 0.6,
     with_corr: bool = True,
     with_weights: bool = False,
+    **estimator_kwargs: Any,
 ) -> tuple[np.ndarray, np.ndarray | None, np.ndarray | None]:
     """Estimate streaming covariance over an entire returns panel.
 
+    Runs one :class:`SqueezeKernelEstimator` over the panel day by day and
+    collects the estimate path.  ``n_assets`` is taken from the panel shape;
+    every other keyword argument is forwarded unchanged to the estimator, so
+    batch mode reaches the full estimator surface — ``kappa``, ``shrinkage``,
+    ``shrinkage_target``, ``corr_half_lives``, ``weight_statistic``,
+    ``vol_anchor_phi``, ``min_obs``, custom kernels, and so on (see the
+    estimator's docstring for the complete list and defaults).
+
     Parameters
     ----------
     returns : array-like, shape (T, n)
         2D return matrix.  May contain NaN for missing observations.
-    kappa : float, optional
-        Saturation parameter for the default Fisher kernel.
-    kernel_fn : callable, optional
-        Custom kernel ``(d2, *, n_observed, **kw) -> float``.
-    kernel_kwargs : dict, optional
-        Extra keyword arguments forwarded to ``kernel_fn``.
     with_corr : bool
         If True, also return the correlation tensor.
     with_weights : bool
         If True, also return per-timestamp kernel weights.
+    **estimator_kwargs
+        Passed through to ``SqueezeKernelEstimator``.
 
     Returns
     -------
     cov : ndarray, shape (T, n, n)
+        The covariance estimate after each day.
     corr : ndarray or None, shape (T, n, n)
     weights : ndarray or None, shape (T,)
     """
     values = np.asarray(returns, dtype=np.float64)
     if values.ndim != 2:
         raise ValueError(f"Expected 2D returns, got shape {values.shape}.")
+    if "n_assets" in estimator_kwargs:
+        raise ValueError(
+            "n_assets is derived from the panel shape and cannot be passed."
+        )
     t_total, n_assets = values.shape
 
-    est = SqueezeKernelEstimator(
-        n_assets,
-        lambda_vol=lambda_vol,
-        lambda_corr=lambda_corr,
-        kappa=kappa,
-        kernel_fn=kernel_fn,
-        kernel_kwargs=kernel_kwargs,
-        epsilon=epsilon,
-        shrinkage=shrinkage,
-        shrinkage_delta=shrinkage_delta,
-        impute_missing=impute_missing,
-        impute_threshold=impute_threshold,
-    )
+    est = SqueezeKernelEstimator(n_assets, **estimator_kwargs)
 
     cov = np.empty((t_total, n_assets, n_assets), dtype=np.float64)
     corr = np.empty_like(cov) if with_corr else None

{squeeze_kernel-0.6.0 → squeeze_kernel-0.7.1}/src/squeeze_kernel/estimator.py

@@ -18,11 +18,118 @@ except ImportError:  # pragma: no cover
 from squeeze_kernel.kernels import (
     KernelFn, kernel_fisher, calibrate_kappa, extract_d2_series,
 )
+from numpy.typing import ArrayLike
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
 
+class _SurpriseDetector:
+    """Two-sided Page CUSUM on the studentised fast-vs-slow per-rung
+    predictive-score drift.
+
+    Gates the blend weights of the scale-free correlation ladder: on each
+    update the day is scored under every rung's previous (t-1) covariance
+    — causal, since ``record`` is called with the rung states *after* the
+    update — and the drift of the centred rung scores advances the CUSUM.
+    An alarm sets a half-magnitude tilt of the theta-prior toward the
+    inverse-horizon vector (fast alarm) or the square-root-horizon vector
+    (slow alarm); on all other days the tilt decays at the fastest rung's
+    half-life.  State: five scalars (``gp``, ``gm``, ``tilt``, ``scale``
+    and the cached ``prev_sig`` rung covariances).
+    """
+
+    _DRIFT = 0.5
+    _THRESHOLD = 4.9721088583   # Siegmund ARL approximation at ~2 years
+    _SNAP = 0.5
+    _CLIP = 3.0
+    _JITTER = 1e-12
+
+    def __init__(self, half_lives: np.ndarray) -> None:
+        hl = half_lives
+        self.pi_fast = (1.0 / hl) / (1.0 / hl).sum()
+        self.pi_slow = hl ** 0.5 / (hl ** 0.5).sum()
+        self._lam_tilt = 2.0 ** (-1.0 / float(hl.min()))
+        self._gamma_scale = 2.0 ** (-1.0 / float(np.median(hl)))
+        self._k_fast = int(np.argmin(hl))
+        self._k_slow = int(np.argmax(hl))
+        self.gp = 0.0
+        self.gm = 0.0
+        self.tilt = 0.0
+        self.scale = 1.0
+        self.prev_sig: list[np.ndarray] | None = None
+
+    def score(self, r_t: np.ndarray, finite: np.ndarray) -> np.ndarray | None:
+        """Per-rung Gaussian log-likelihood of ``r_t`` under ``prev_sig``,
+        restricted to the observed assets.  Returns None when there is no
+        previous state, nothing is observed, or the day is degenerate
+        (e.g. a fresh listing); a degenerate day also decays the tilt."""
+        if self.prev_sig is None or not finite.any():
+            return None
+        oidx = np.flatnonzero(finite)
+        r_o = r_t[oidx]
+        ell = np.empty(len(self.prev_sig))
+        for k, sig in enumerate(self.prev_sig):
+            sub = sig[np.ix_(oidx, oidx)]
+            sub = (sub + sub.T) * 0.5
+            if _cho_factor is not None:
+                # One Cholesky per rung: logdet from the factor's
+                # diagonal, quadratic form via triangular solves.
+                try:
+                    cf = _cho_factor(sub, lower=True, check_finite=False)
+                except np.linalg.LinAlgError:
+                    self.tilt *= self._lam_tilt
+                    return None
+                logdet = 2.0 * np.log(np.diagonal(cf[0])).sum()
+                quad = float(r_o @ _cho_solve(cf, r_o, check_finite=False))
+            else:
+                sign, logdet = np.linalg.slogdet(sub)
+                if sign <= 0:
+                    self.tilt *= self._lam_tilt
+                    return None
+                try:
+                    quad = float(r_o @ np.linalg.solve(sub, r_o))
+                except np.linalg.LinAlgError:
+                    self.tilt *= self._lam_tilt
+                    return None
+            ell[k] = -0.5 * (oidx.size * np.log(2 * np.pi) + logdet + quad)
+        return ell
+
+    def advance(self, ell: np.ndarray | None) -> None:
+        """Advance the CUSUM with the rung scores for this day.  ``None``
+        (no clean score) is a no-op: the degenerate-day tilt decay already
+        happened inside ``score``."""
+        if ell is None:
+            return
+        dd = ell - ell.mean()
+        rms = float(np.sqrt((dd @ dd) / ell.size))
+        self.scale = (self._gamma_scale * self.scale
+                      + (1.0 - self._gamma_scale) * rms)
+        zc = np.clip(dd / (self.scale + self._JITTER), -self._CLIP, self._CLIP)
+        zfs = float(zc[self._k_fast] - zc[self._k_slow])
+        self.gp = max(0.0, self.gp + zfs - self._DRIFT)
+        self.gm = max(0.0, self.gm - zfs - self._DRIFT)
+        if self.gp > self._THRESHOLD:
+            self.tilt, self.gp = self._SNAP, 0.0
+        elif self.gm > self._THRESHOLD:
+            self.tilt, self.gm = -self._SNAP, 0.0
+        else:
+            self.tilt *= self._lam_tilt
+
+    def record(self, rung_covs: list[np.ndarray]) -> None:
+        """Cache this step's rung covariances as next step's forecasts."""
+        self.prev_sig = rung_covs
+
+    def blend(self, prior: np.ndarray) -> np.ndarray:
+        """Blend weights for the rung covariances: the theta-prior on
+        non-alarmed days, tilted half-magnitude toward the horizon vectors
+        while an alarm is live.  Convex in both regimes."""
+        t = self.tilt
+        if t >= 0:
+            return np.asarray((1.0 - t) * prior + t * self.pi_fast)
+        return np.asarray((1.0 + t) * prior + (-t) * self.pi_slow)
+
+
 class SqueezeKernelEstimator:
     """Streaming robust covariance estimator with pluggable kernel weighting.
 
@@ -251,6 +358,7 @@ class SqueezeKernelEstimator:
         self.corr_theta = corr_theta
         self._corr_lam: np.ndarray | None = None
         self._corr_w: np.ndarray | None = None
+        self._detector: _SurpriseDetector | None = None
         self._Q_list: list[np.ndarray] | None = None
         self._S_list: list[float] | None = None
         self._adaptive = False
@@ -271,21 +379,11 @@ class SqueezeKernelEstimator:
             self._corr_w = w / w.sum()
             self._Q_list = [np.eye(n_assets, dtype=np.float64) for _ in hl]
             self._S_list = [float(epsilon) for _ in hl]
-            # Surprise-gated blend weights (integral for K >= 2): two-sided
-            # Page CUSUM on the studentised fast-vs-slow per-rung
-            # predictive-score drift; drift 0.5, threshold from Siegmund's
-            # ARL approximation at ARL0 = 504 trading days (~2 years).
+            # Surprise-gated blend weights (integral for K >= 2): see
+            # ``_SurpriseDetector``.
             self._adaptive = hl.size >= 2
             if self._adaptive:
-                self._aw_pi_fast = (1.0 / hl) / (1.0 / hl).sum()
-                self._aw_pi_slow = hl ** 0.5 / (hl ** 0.5).sum()
-                self._aw_lam_tilt = 2.0 ** (-1.0 / float(hl.min()))
-                self._aw_gamma_scale = 2.0 ** (-1.0 / float(np.median(hl)))
-                self._aw_drift, self._aw_b, self._aw_snap = 0.5, 4.9721088583, 0.5
-                self._aw_gp = self._aw_gm = 0.0
-                self._aw_tilt = 0.0
-                self._aw_scale = 1.0
-                self._aw_prev_sig: list[np.ndarray] | None = None
+                self._detector = _SurpriseDetector(hl)
 
         # Resolve shrinkage
         if isinstance(shrinkage, str):
@@ -328,7 +426,7 @@ class SqueezeKernelEstimator:
 
     # ── Public API ────────────────────────────────────────────────────────
 
-    def update(self, r_t) -> float:
+    def update(self, r_t: ArrayLike) -> float:
         """Process one return vector and update the covariance estimate.
 
         Parameters
@@ -353,77 +451,37 @@ class SqueezeKernelEstimator:
         # ── Adaptive-weight detector: score r_t under yesterday's per-rung
         # forecasts, then advance the CUSUM (weights used below therefore
         # reflect information through r_t only — causal). ──
-        if (self._adaptive and self._aw_prev_sig is not None
-                and finite.any()):
-            oidx = np.flatnonzero(finite)
-            r_o = r_t[oidx]
-            ell = np.empty(len(self._aw_prev_sig))
-            ok = True
-            for k, sig in enumerate(self._aw_prev_sig):
-                sub = sig[np.ix_(oidx, oidx)]
-                sub = (sub + sub.T) * 0.5
-                if _cho_factor is not None:
-                    # One Cholesky per rung: logdet from the factor's
-                    # diagonal, quadratic form via triangular solves.
-                    try:
-                        cf = _cho_factor(sub, lower=True, check_finite=False)
-                    except np.linalg.LinAlgError:
-                        ok = False           # degenerate day (e.g. a fresh
-                        break                # listing): no clean score
-                    logdet = 2.0 * np.log(np.diagonal(cf[0])).sum()
-                    quad = float(r_o @ _cho_solve(cf, r_o, check_finite=False))
-                else:
-                    sign, logdet = np.linalg.slogdet(sub)
-                    if sign <= 0:
-                        ok = False           # degenerate day (e.g. a fresh
-                        break                # listing): no clean score
-                    try:
-                        quad = float(r_o @ np.linalg.solve(sub, r_o))
-                    except np.linalg.LinAlgError:
-                        ok = False
-                        break
-                ell[k] = -0.5 * (oidx.size * np.log(2 * np.pi) + logdet + quad)
-            if not ok:
-                self._aw_tilt *= self._aw_lam_tilt
-                ell = None
-        else:
-            ell = None
-        if ell is not None:
-            dd = ell - ell.mean()
-            rms = float(np.sqrt((dd @ dd) / ell.size))
-            self._aw_scale = (self._aw_gamma_scale * self._aw_scale
-                              + (1.0 - self._aw_gamma_scale) * rms)
-            zc = np.clip(dd / (self._aw_scale + 1e-12), -3.0, 3.0)
-            k_fast = int(np.argmin(self.corr_half_lives))
-            k_slow = int(np.argmax(self.corr_half_lives))
-            zfs = float(zc[k_fast] - zc[k_slow])
-            self._aw_gp = max(0.0, self._aw_gp + zfs - self._aw_drift)
-            self._aw_gm = max(0.0, self._aw_gm - zfs - self._aw_drift)
-            if self._aw_gp > self._aw_b:
-                self._aw_tilt, self._aw_gp = self._aw_snap, 0.0
-            elif self._aw_gm > self._aw_b:
-                self._aw_tilt, self._aw_gm = -self._aw_snap, 0.0
-            else:
-                self._aw_tilt *= self._aw_lam_tilt
+        ell = None
+        detector = self._detector
+        if detector is not None:
+            ell = detector.score(r_t, finite)
+            detector.advance(ell)
 
         # ── Volatility update ──
-        if self._var_t is None:
-            self._var_t = np.zeros(n, dtype=np.float64)
-            self._var_init = np.zeros(n, dtype=bool)
+        # Locals alias the variance states: the guard initialises the pair
+        # together, so both are non-None afterwards, and local aliases keep
+        # the narrowing visible to mypy.
+        var_t = self._var_t
+        var_init = self._var_init
+        if var_t is None or var_init is None:
+            var_t = np.zeros(n, dtype=np.float64)
+            var_init = np.zeros(n, dtype=bool)
+            self._var_t = var_t
+            self._var_init = var_init
             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
+        first = finite & ~var_init
+        repeat = finite & var_init
         if np.any(first):
-            self._var_t[first] = r_t[first] ** 2 + eps
-            self._var_init[first] = True
+            var_t[first] = r_t[first] ** 2 + eps
+            var_init[first] = True
             if self._var_anchor is not None:
-                self._var_anchor[first] = self._var_t[first]
+                self._var_anchor[first] = var_t[first]
         if np.any(repeat):
             if self.vol_anchor_phi is None:
-                self._var_t[repeat] = (
-                    self.lambda_vol * self._var_t[repeat]
+                var_t[repeat] = (
+                    self.lambda_vol * var_t[repeat]
                     + (1.0 - self.lambda_vol) * r_t[repeat] ** 2
                 )
             else:
@@ -431,20 +489,23 @@ class SqueezeKernelEstimator:
                 # per-asset anchor before the measurement update, then update
                 # the anchor itself (order matters and matches the validated
                 # experiment: prediction uses the *old* anchor).
+                var_anchor = self._var_anchor
+                assert var_anchor is not None
+                # allocated together with the anchor on the first update
                 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] = (
+                anchor = var_anchor[repeat]
+                v_pred = anchor + phi * (var_t[repeat] - anchor)
+                var_t[repeat] = (
                     self.lambda_vol * v_pred
                     + (1.0 - self.lambda_vol) * r_t[repeat] ** 2
                 )
-                self._var_anchor[repeat] = (
+                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])
+        vol_t[var_init] = np.sqrt(var_t[var_init])
 
         # ── Standardized returns ──
         z_t = np.zeros(n, dtype=np.float64)
@@ -459,8 +520,10 @@ class SqueezeKernelEstimator:
                 # lazy, so bring _corr up to the t-1 state first.
                 if self._dirty:
                     self._materialize()
+                corr_prev = self._corr
+                assert corr_prev is not None   # _materialize always sets it
                 try:
-                    c_sub = self._corr[np.ix_(finite, finite)]
+                    c_sub = corr_prev[np.ix_(finite, finite)]
                     d2 = float(z_t[finite] @ np.linalg.solve(c_sub, z_t[finite])) / n_obs
                 except np.linalg.LinAlgError:
                     pass
@@ -478,9 +541,12 @@ class SqueezeKernelEstimator:
             # np.outer otherwise allocates each step. zz' is computed once
             # and shared by every rung.
             np.multiply.outer(z_t, z_t, out=self._scratch_outer)
-        if self._corr_lam is None:
+        corr_lam = self._corr_lam
+        if corr_lam is None:
             # ── Single-scale correlation EWMA (published path) ──
-            lam_c = self.lambda_corr
+            Q_t = self._Q_t
+            assert Q_t is not None     # the single-scale state exists exactly
+            lam_c = self.lambda_corr   # when the ladder is not configured
             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.
@@ -490,23 +556,28 @@ class SqueezeKernelEstimator:
                 # Q <- (1 - eta) Q + eta zz'. With w_t = 0 both S and M decay
                 # by lam_c, so Q is unchanged — no matrix work at all.
                 eta = w_t / self._S_t
-                self._Q_t *= 1.0 - eta
+                Q_t *= 1.0 - eta
                 self._scratch_outer *= eta
-                self._Q_t += self._scratch_outer
+                Q_t += self._scratch_outer
         else:
             # ── Scale-free ladder (Mode A) ──
             # Update K normalised correlation states on the geometric
             # half-life ladder; extraction (normalise + shrink + blend)
             # happens lazily in _materialize().
+            Q_list = self._Q_list
+            S_list = self._S_list
+            corr_w = self._corr_w
+            assert Q_list is not None and S_list is not None
+            assert corr_w is not None  # allocated together with corr_lam
             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
+            for k in range(corr_lam.size):
+                S_list[k] = corr_lam[k] * S_list[k] + w_t
                 if add:
-                    eta = w_t / self._S_list[k]
-                    self._Q_list[k] *= 1.0 - eta
+                    eta = w_t / S_list[k]
+                    Q_list[k] *= 1.0 - eta
                     np.multiply(self._scratch_outer, eta, out=self._scratch_had)
-                    self._Q_list[k] += self._scratch_had
-                s_eff += self._corr_w[k] * self._S_list[k]
+                    Q_list[k] += self._scratch_had
+                s_eff += corr_w[k] * S_list[k]
             self._S_t = s_eff                        # blended effective size (for the property)
         self._vol_t = vol_t
         self._dirty = True
@@ -521,7 +592,9 @@ class SqueezeKernelEstimator:
             raise RuntimeError("Call update() at least once before get_cov().")
         if self._dirty:
             self._materialize()
-        return self._cov.copy()
+        cov = self._cov
+        assert cov is not None
+        return cov.copy()
 
     def get_corr(self) -> np.ndarray:
         """Return the current correlation matrix estimate (n x n)."""
@@ -529,7 +602,9 @@ class SqueezeKernelEstimator:
             raise RuntimeError("Call update() at least once before get_corr().")
         if self._dirty:
             self._materialize()
-        return self._corr.copy()
+        corr = self._corr
+        assert corr is not None
+        return corr.copy()
 
     @property
     def weight(self) -> float:
@@ -562,7 +637,7 @@ class SqueezeKernelEstimator:
 
     @staticmethod
     def calibrate_kappa(
-        returns, target_weight: float = 0.5, lambda_vol: float = 0.98,
+        returns: ArrayLike, target_weight: float = 0.5, lambda_vol: float = 0.98,
     ) -> float:
         """Calibrate κ from burn-in data so E[w_t] ≈ target_weight.
 
@@ -669,20 +744,24 @@ class SqueezeKernelEstimator:
         """Adaptive-weight extraction: build per-rung shrunk covariances
         (kept for the next update's detector scores), blend with the
         CUSUM-tilted weights, derive _cov/_corr. Runs eagerly."""
-        eps = self.epsilon
+        detector = self._detector
+        corr_lam = self._corr_lam
+        Q_list = self._Q_list
+        S_list = self._S_list
+        corr_w = self._corr_w
         vol_t = self._vol_t
+        assert detector is not None      # only called when the detector exists
+        assert corr_lam is not None and Q_list is not None
+        assert S_list is not None and corr_w is not None
+        assert vol_t is not None         # set on every update before this runs
+        eps = self.epsilon
         vv = np.multiply.outer(vol_t, vol_t)
         sig_k = []
-        for k in range(self._corr_lam.size):
-            corr_k = self._shrunk_corr_from_Q(self._Q_list[k], self._S_list[k])
+        for k in range(corr_lam.size):
+            corr_k = self._shrunk_corr_from_Q(Q_list[k], S_list[k])
             sig_k.append(corr_k * vv)
-        self._aw_prev_sig = sig_k
-        t = self._aw_tilt
-        pi = self._corr_w
-        if t >= 0:
-            w = (1.0 - t) * pi + t * self._aw_pi_fast
-        else:
-            w = (1.0 + t) * pi + (-t) * self._aw_pi_slow
+        detector.record(sig_k)
+        w = detector.blend(corr_w)
         cov = w[0] * sig_k[0]
         for k in range(1, len(sig_k)):
             cov = cov + w[k] * sig_k[k]
@@ -697,9 +776,12 @@ class SqueezeKernelEstimator:
         """Extract _cov/_corr from the current state (lazy, on demand)."""
         eps = self.epsilon
         vol_t = self._vol_t
+        assert vol_t is not None   # get_cov/get_corr guard this before calling
         if self._corr_lam is None:
             # ── Single scale: shrunk correlation IS the correlation output ──
-            corr = self._shrunk_corr_from_Q(self._Q_t, self._S_t)
+            Q_t = self._Q_t
+            assert Q_t is not None   # the ladder is not configured on this path
+            corr = self._shrunk_corr_from_Q(Q_t, self._S_t)
             np.multiply.outer(vol_t, vol_t, out=self._scratch_outer)
             cov = corr * self._scratch_outer
             cov += cov.T
@@ -712,10 +794,16 @@ class SqueezeKernelEstimator:
             # ── Ladder: blend per-rung shrunk correlations, then apply the
             # (shared) volatilities once — algebraically identical to
             # blending per-rung covariances, K-1 fewer O(n^2) passes.
+            corr_lam = self._corr_lam
+            Q_list = self._Q_list
+            S_list = self._S_list
+            corr_w = self._corr_w
+            assert Q_list is not None and S_list is not None
+            assert corr_w is not None  # allocated together with corr_lam
             mix = np.zeros((self.n_assets, self.n_assets), dtype=np.float64)
-            for k in range(self._corr_lam.size):
-                corr_k = self._shrunk_corr_from_Q(self._Q_list[k], self._S_list[k])
-                corr_k *= self._corr_w[k]
+            for k in range(corr_lam.size):
+                corr_k = self._shrunk_corr_from_Q(Q_list[k], S_list[k])
+                corr_k *= corr_w[k]
                 mix += corr_k
             cov = mix
             np.multiply.outer(vol_t, vol_t, out=self._scratch_outer)
@@ -751,7 +839,13 @@ def _resolve_kernel(
     if "kappa" in kw and kappa is not None:
         raise ValueError("Pass kappa either as a top-level argument or in kernel_kwargs, not both.")
 
-    resolved_kappa = float(kw.get("kappa", 0.25 if kappa is None else kappa))
+    if "kappa" in kw:
+        kappa_src = kw["kappa"]
+        if isinstance(kappa_src, bool) or not isinstance(kappa_src, (int, float)):
+            raise ValueError("kappa in kernel_kwargs must be a number.")
+        resolved_kappa = float(kappa_src)
+    else:
+        resolved_kappa = 0.25 if kappa is None else float(kappa)
     if resolved_kappa <= 0.0:
         raise ValueError("kappa must be > 0.")
     kw["kappa"] = resolved_kappa

{squeeze_kernel-0.6.0 → squeeze_kernel-0.7.1}/src/squeeze_kernel/kernels.py

@@ -5,10 +5,13 @@ from __future__ import annotations
 import math
 from typing import Callable
 
+import numpy as np
+from numpy.typing import ArrayLike
+
 KernelFn = Callable[..., float]
 
 
-def kernel_fisher(d2: float, /, *, kappa: float, **kw) -> float:
+def kernel_fisher(d2: float, /, *, kappa: float, **kw: object) -> float:
     """Fisher information saturation kernel: w = d² / (d² + κ).
 
     Motivated by the signal-to-noise structure of the Gaussian score.
@@ -19,14 +22,14 @@ def kernel_fisher(d2: float, /, *, kappa: float, **kw) -> float:
     return d2 / (d2 + kappa)
 
 
-def kernel_exponential(d2: float, /, *, gamma: float, **kw) -> float:
+def kernel_exponential(d2: float, /, *, gamma: float, **kw: object) -> float:
     """Rayleigh survival (exponential) kernel: w = 1 − exp(−d²/(2γ²))."""
     if gamma <= 0.0:
         raise ValueError("gamma must be > 0.")
     return 1.0 - math.exp(-d2 / (2.0 * gamma * gamma))
 
 
-def kernel_chi2_cdf(d2: float, /, *, n_observed: int, **kw) -> float:
+def kernel_chi2_cdf(d2: float, /, *, n_observed: int, **kw: object) -> float:
     """Chi-squared CDF kernel: w = F_χ²_N(N·d²).  Requires scipy."""
     try:
         from scipy.stats import chi2
@@ -38,7 +41,7 @@ def kernel_chi2_cdf(d2: float, /, *, n_observed: int, **kw) -> float:
     return float(chi2.cdf(n_observed * d2, df=n_observed))
 
 
-def calibrate_kappa(d2_samples, target_mean_weight: float = 0.5) -> float:
+def calibrate_kappa(d2_samples: ArrayLike, target_mean_weight: float = 0.5) -> float:
     """Find κ such that E[d²/(d²+κ)] ≈ target_mean_weight on burn-in data.
 
     This implements the closed-form initializer from Proposition 1 of the paper,
@@ -56,7 +59,6 @@ def calibrate_kappa(d2_samples, target_mean_weight: float = 0.5) -> float:
     float
         Calibrated κ value.
     """
-    import numpy as np
     try:
         from scipy.optimize import brentq
     except ImportError as exc:
@@ -75,7 +77,7 @@ def calibrate_kappa(d2_samples, target_mean_weight: float = 0.5) -> float:
     kappa_init = mu * (1.0 / target_mean_weight - 1.0)
 
     # Refine via root finding
-    def residual(kappa):
+    def residual(kappa: float) -> float:
         return float(np.mean(d2 / (d2 + kappa))) - target_mean_weight
 
     lo = max(kappa_init * 0.01, 1e-6)
@@ -90,8 +92,8 @@ def calibrate_kappa(d2_samples, target_mean_weight: float = 0.5) -> float:
 
 
 def extract_d2_series(
-    returns, lambda_vol: float = 0.98, epsilon: float = 1e-8,
-):
+    returns: ArrayLike, lambda_vol: float = 0.98, epsilon: float = 1e-8,
+) -> np.ndarray:
     """Extract the d̄²_t series from a returns panel for κ calibration.
 
     Parameters
@@ -106,7 +108,6 @@ def extract_d2_series(
     ndarray, shape (T,)
         Average squared standardized return at each timestep.
     """
-    import numpy as np
 
     x = np.asarray(returns, dtype=np.float64)
     t_total, n = x.shape

squeeze_kernel-0.6.0/README.md

@@ -1,164 +0,0 @@
-# Squeeze Kernel Covariance Estimator
-
-[![CI](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
-[![Python](https://img.shields.io/pypi/pyversions/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-
-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) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918).
-
-## Why
-
-Rolling-window estimators (Ledoit–Wolf, nonlinear shrinkage, RMT denoising) refit over a fixed window each day and cannot adapt within it; multivariate GARCH (DCC) adapts but needs multi-stage estimation and a fragile news coefficient. The Squeeze Kernel is a single streaming recursion that:
-
-- **is PSD at every step, structurally** — never needs eigenvalue clipping, nearest-PSD projection, or a solver;
-- **adapts fastest exactly when it matters** — a Fisher-information kernel up-weights high-dispersion (stress) days, when correlation regimes actually move;
-- **regularises itself** — an adaptive equicorrelation shrinkage activates automatically as the asset count approaches the effective sample size, with a provable condition-number bound;
-- **ingests missing values natively** — listings, delistings, and halts enter as `NaN`; no imputation or complete-case subsetting;
-- **is fast** — a full 30-year daily pass takes ~0.75 s at n=100 and ~3.4 s at n=300 (single-threaded), 30–40× faster than rolling-window baselines at scale.
-
-On a 30-year S&P 500 panel (n=100, ~7,600 out-of-sample days) it statistically ties DCC on one-step density forecasts and beats EWMA, Ledoit–Wolf, OAS, nonlinear shrinkage, RMT denoising, and the Gerber statistic — and it is the only method in the 90% model confidence set together with DCC. At n=300 it leads every competitor that remains statistically viable.
-
-## Installation
-
-```bash
-pip install squeeze-kernel          # NumPy only
-pip install "squeeze-kernel[full]"  # + SciPy (kappa calibration, chi² kernel)
-```
-
-## Quickstart
-
-```python
-import numpy as np
-from squeeze_kernel import SqueezeKernelEstimator
-
-# daily_returns: array of shape (T, n) — may contain NaN for missing assets
-est = SqueezeKernelEstimator(n_assets=daily_returns.shape[1])
-
-for r_t in daily_returns:          # stream one day at a time
-    est.update(r_t)
-
-cov  = est.get_cov()               # (n, n) covariance, PSD by construction
-corr = est.get_corr()              # (n, n) correlation
-```
-
-That is the whole API for most uses. The defaults (`lambda_vol=0.98`, `lambda_corr=0.996`, `kappa=0.25`) are the paper-recommended settings for daily returns, selected by time-series cross-validation and robust across a 50× parameter sweep — deploy them as-is.
-
-Batch mode, if you prefer the full path in one call:
-
-```python
-from squeeze_kernel import estimate_squeeze_cov
-
-cov_path, corr_path, weights = estimate_squeeze_cov(daily_returns, with_weights=True)
-# cov_path: (T, n, n) — the estimate after each day
-```
-
-A complete runnable walkthrough (streaming, missing data, batch) is in [`examples/quickstart.py`](examples/quickstart.py).
-
-## Missing values
-
-Pass `NaN` for any asset not observed on a given day — nothing else to do:
-
-```python
-r_t = np.array([0.004, np.nan, -0.011])   # asset 2 not trading today
-est.update(r_t)                            # PSD preserved, no imputation
-```
-
-## Parameters
-
-| Parameter | Default | Meaning |
-|---|---|---|
-| `lambda_vol` | `0.98` | volatility EWMA decay (half-life ≈ 34 days) |
-| `lambda_corr` | `0.996` | correlation EWMA decay (half-life ≈ 173 days, T_eff ≈ 250) |
-| `kappa` | `0.25` | Fisher kernel saturation; higher = stronger calm-day filtering |
-| `shrinkage` | `"auto"` | adaptive equicorrelation shrinkage (`"none"` or a float to override) |
-| `shrinkage_delta` | `0.10` | concentration threshold at which shrinkage activates |
-
-Useful read-only state after each `update()`: `est.weight` (last kernel weight), `est.effective_sample_size` (kernel-weighted T_eff), `est.shrinkage_intensity` (current α).
-
-To recalibrate `kappa` for a different asset class (requires the `full` extra):
-
-```python
-kappa = SqueezeKernelEstimator.calibrate_kappa(burn_in_returns, target_weight=0.6)
-```
-
-## Advanced options
-
-**Adaptive 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 resting at the prior ∝ half-life^`corr_theta`. By Bernstein's theorem the ladder approximates the power-law memory of financial correlations (the streaming analogue of HAR). For ladders of two or more rungs the blend weights are gated by a sequential surprise detector: a two-sided Page CUSUM on the studentized fast-vs-slow per-rung predictive-score drift (threshold set by Siegmund's average-run-length approximation at ~2 years, no tuned parameters) tilts the weights toward the fast or slow end of the ladder when one side accumulates statistically forced evidence, decaying back at the fastest rung's half-life. Weights equal the prior on all non-alarmed days, the blend stays convex, so PSD holds by construction; `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 −4.6 vs single-scale at n=100, −11.1 at n=300 before the cluster target), the 90% model confidence set collapses to it alone, and the detector's margin is confirmed out-of-time on an external industry panel (+0.53 NLL/day, p=1×10⁻⁴). Cost is O(K·n²) per update plus one Cholesky per rung per day for the detector scores. 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
-est = SqueezeKernelEstimator(n_assets=100, kappa=1.0, weight_statistic="mahalanobis")
-```
-
-**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")
-```
-
-**New-listing usability gate** (`min_obs=60`): on an expanding universe, an asset's forecast rows are dominated by its single-observation variance initialization for its first weeks of life and are unusable for scoring or portfolio construction (measured ≈ +2,800 NLL/day on days whose scored set included such assets, on a 42-instrument multi-asset panel). `min_obs` gates nothing inside the estimator — states warm normally, all outputs are unchanged — it exposes a `usable_mask` property marking assets with at least `min_obs` finite observations, so deployments subset with it:
-
-```python
-est = SqueezeKernelEstimator(n_assets=42, min_obs=60)
-# ... update loop ...
-m = est.usable_mask
-cov_usable = est.get_cov()[np.ix_(m, m)]
-```
-
-**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
-
-Three mechanisms in one recursion:
-
-1. **Dual-timescale EWMA** — fast per-asset volatility (`lambda_vol`) is separated from slow correlation dynamics (`lambda_corr`), so variance shocks don't contaminate the correlation estimate.
-2. **Fisher kernel weighting** — each day's standardized outer product enters with weight `w = d²/(d² + kappa)`, where `d²` is the mean squared standardized return: calm days contribute little, dispersion shocks contribute fully.
-3. **Adaptive equicorrelation shrinkage** — `alpha = min(1, max(0, n/(2·S) − delta))` blends toward an equicorrelation target using the estimator's own kernel-weighted sample size `S`; it is a no-op at low dimension and provides provably bounded conditioning at high dimension.
-
-The complete update is a natural-gradient step on the Gaussian log-likelihood, with the kernel weight acting as an adaptive Riemannian learning rate (paper, Appendix B).
-
-## Development
-
-```bash
-uv sync --extra full --extra dev
-uv run python -m pytest        # test suite
-uv run python -m ruff check .  # lint
-uv build                       # build sdist + wheel
-```
-
-Releases: publishing a GitHub release from a `v*` tag triggers the [publish workflow](.github/workflows/publish.yml), which builds and uploads to PyPI via trusted publishing.
-
-## Citation
-
-```bibtex
-@article{kende2026squeeze,
-  title  = {The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage},
-  author = {Kende, Robert},
-  year   = {2026},
-  note   = {Available at SSRN: \url{https://ssrn.com/abstract=6455918}}
-}
-```
-
-See also [`CITATION.cff`](CITATION.cff).
-
-## License
-
-MIT