nested-recd 0.2.0__tar.gz → 0.2.3__tar.gz

{nested_recd-0.2.0/src/nested_recd.egg-info → nested_recd-0.2.3}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: nested-recd
-Version: 0.2.0
-Summary: Nested ordinal RECD: Φ1–Φ3, continuous excess³ (primary Level-3), and λ-weighted Discrete Extramental Clock
+Version: 0.2.3
+Summary: Nested ordinal RECD: Φ1–Φ3, continuous excess³ (exportable Level-3 proxy), Res_pair (strong residual), and λ-weighted Discrete Extramental Clock
 Author-email: Johel Padilla-Villanueva <joel.padilla2@upr.edu>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/johelpadilla/nested-recd
 Project-URL: Repository, https://github.com/johelpadilla/nested-recd
 Project-URL: Issues, https://github.com/johelpadilla/nested-recd/issues
 Project-URL: Documentation, https://github.com/johelpadilla/nested-recd#readme
-Project-URL: DOI, https://doi.org/10.5281/zenodo.21270699
+Project-URL: DOI, https://doi.org/10.5281/zenodo.22970079
 Keywords: RECD,ordinal patterns,nested time,Systemic Tau,complexity,early-warning,network physiology,Bandt-Pompe
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -35,13 +35,26 @@ Dynamic: license-file
 
 # nested-recd
 
+> **Correction (0.2.3).** Versions ≤ 0.2.2 computed `H_joint` and the pairwise
+> entropies inside `Syn` with `np.unique` on a list of tuples and no `axis=0`.
+> NumPy flattens that input, so `Syn`, `excess3` and binary `phi3` were not the
+> published definition when `N ≥ 3`. `Surp` and `Res_pair` were not affected.
+> For `N = 2`, `Syn` is 0 either way. 0.2.3 counts joint rows.
+> `legacy_pooled_counting=True` reproduces the old numbers and warns.
+> See `CHANGELOG.md`. This version:
+> [10.5281/zenodo.22970079](https://doi.org/10.5281/zenodo.22970079).
+> The 0.2.2 deposit remains
+> [10.5281/zenodo.21937204](https://doi.org/10.5281/zenodo.21937204).
+
 [![PyPI version](https://img.shields.io/pypi/v/nested-recd.svg)](https://pypi.org/project/nested-recd/)
 [![Python](https://img.shields.io/pypi/pyversions/nested-recd.svg)](https://pypi.org/project/nested-recd/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 proxy, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 *proxy* (T-IV; not the strong residual), optional **Res_pair** \(=\mathrm{KL}(P\|P^{(2)})\), Gibbs-α weights, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+
+This is the **canonical nested-clock software** for the Systemic Tau / RECD stack (foundations paper, excess³ methods preprint, cardiac CCTP/SDDB pilot, Academy Learning Tau).
 
-This is the **canonical Level-3 software** for the Systemic Tau / RECD stack (cardiac CCTP/SDDB pilot, excess³ methods preprint, Academy Learning Tau).
+**Léxico (no negociable):** *strong Level-3* := `Res_pair`. *excess3* := exportable proxy. Report `w` with any Res_pair figure. Abundance (excess3) ≠ aggregation share \(f_3\).
 
 ## Install
 
@@ -88,6 +101,15 @@ print("weights:", out["params"]["alpha_syn"], out["params"]["alpha_surp"])
 print("final T_recd:", float(out["T_recd"][-1]))
 ```
 
+### Strong residual Res_pair (optional)
+
+```python
+out = compute_recd_from_conjunctions(X, compute_res=True)
+# or, on a symbol window:
+from nested_recd import compute_res_pair_window
+# Always report window length with Res_pair (Nota 4: w=13 can bias chaos).
+```
+
 ### Continuous excess³ only
 
 ```python
@@ -114,7 +136,7 @@ out = compute_recd_from_conjunctions(X, tau_s=tau_s)
 out = compute_recd_from_conjunctions(X, lam_override=0.5)
 ```
 
-**Note:** `delta_recd` / `T_recd` use **binary Φ₃** in the α-weighted clock (legacy Discrete Extramental Clock). For scientific Level-3 claims, report **continuous excess³** and nulls on `|Δ excess3|`.
+**Note:** `delta_recd` / `T_recd` use **binary Φ₃** in the α-weighted clock (legacy Discrete Extramental Clock). For **exportable / scalable** Level-3 reporting, use continuous **excess³** and nulls on `|Δ excess3|`. For **strong** Level-3 claims, report **`res_pair`** (enable `compute_res=True`) **and the window `w`**. Do not identify the two.
 
 ## What it computes
 
@@ -122,10 +144,11 @@ out = compute_recd_from_conjunctions(X, lam_override=0.5)
 |--------|---------|
 | **Φ₁** | Co-occurrence of identical ordinal symbols across variable pairs |
 | **Φ₂** | Persistence of pairwise ordinal relations over lag `d` |
-| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**primary** Level-3) |
+| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**exportable Level-3 proxy**; T-IV) |
 | **Φ₃** | Binary ticks of excess³ above `theta3` (**secondary**) |
+| **Res_pair** | Strong Level-3 residual `KL(P ‖ P^(2))` (optional; always report `w`) |
 | **λ** | Chaos / reorganization intensity (from `τ_s` or `lam_override`) |
-| **α(λ)** | Level weights: α₁ decays with λ; α₂, α₃ grow with λ |
+| **α(λ)** | Design-engine weights (template or Gibbs-α); **not** a joint observable |
 | **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` (legacy clock; binary Φ₃) |
 | **T_recd** | Cumulative sum of ΔRECD |
 
@@ -150,7 +173,8 @@ from nested_recd import (
     compute_phi1, compute_phi2, compute_phi3,
     compute_phi3_excess, compute_excess3_window,
     mean_excess_pre_post, surrogate_pvalue_delta_excess3,
-    compute_lambda, alpha_weights, regime_lambda_proxy,
+    compute_lambda, alpha_weights, alpha_weights_gibbs, regime_lambda_proxy,
+    compute_res_pair, compute_res_pair_window,
     compute_weighted_contributions, high_level3_rate,
     generate_multivariate_symbols,
     phase_shuffle_independent, generate_surrogate_ensemble,
@@ -173,6 +197,12 @@ If you use excess³ / Level-3 from this package, cite the **methods** preprint (
 
 > Padilla-Villanueva, J. (2026). *excess³: A Pre-Specified Continuous Proxy for Order-3 Synergistic Surplus* (methods). Zenodo. https://doi.org/10.5281/zenodo.21385937
 
+This software (0.2.3):
+
+> Padilla-Villanueva, J. (2026). *nested-recd 0.2.3: Nested ordinal RECD, excess³ proxy, and Res_pair*. Zenodo. https://doi.org/10.5281/zenodo.22970079
+
+The previous release (0.2.2), which pooled symbols inside Syn, remains citable as https://doi.org/10.5281/zenodo.21937204.
+
 Software / related stack:
 
 > Padilla-Villanueva, J. (2026). Systemic Tau software archive. Zenodo. https://doi.org/10.5281/zenodo.20576241
@@ -187,7 +217,8 @@ CCTP/SDDB pilot:
   title   = {nested-recd: Nested ordinal RECD levels and continuous excess³},
   year    = {2026},
   url     = {https://github.com/johelpadilla/nested-recd},
-  version = {0.2.0}
+  version = {0.2.3},
+  doi     = {10.5281/zenodo.22970079}
 }
 ```
 

{nested_recd-0.2.0 → nested_recd-0.2.3}/README.md

@@ -1,12 +1,25 @@
 # nested-recd
 
+> **Correction (0.2.3).** Versions ≤ 0.2.2 computed `H_joint` and the pairwise
+> entropies inside `Syn` with `np.unique` on a list of tuples and no `axis=0`.
+> NumPy flattens that input, so `Syn`, `excess3` and binary `phi3` were not the
+> published definition when `N ≥ 3`. `Surp` and `Res_pair` were not affected.
+> For `N = 2`, `Syn` is 0 either way. 0.2.3 counts joint rows.
+> `legacy_pooled_counting=True` reproduces the old numbers and warns.
+> See `CHANGELOG.md`. This version:
+> [10.5281/zenodo.22970079](https://doi.org/10.5281/zenodo.22970079).
+> The 0.2.2 deposit remains
+> [10.5281/zenodo.21937204](https://doi.org/10.5281/zenodo.21937204).
+
 [![PyPI version](https://img.shields.io/pypi/v/nested-recd.svg)](https://pypi.org/project/nested-recd/)
 [![Python](https://img.shields.io/pypi/pyversions/nested-recd.svg)](https://pypi.org/project/nested-recd/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 proxy, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 *proxy* (T-IV; not the strong residual), optional **Res_pair** \(=\mathrm{KL}(P\|P^{(2)})\), Gibbs-α weights, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+
+This is the **canonical nested-clock software** for the Systemic Tau / RECD stack (foundations paper, excess³ methods preprint, cardiac CCTP/SDDB pilot, Academy Learning Tau).
 
-This is the **canonical Level-3 software** for the Systemic Tau / RECD stack (cardiac CCTP/SDDB pilot, excess³ methods preprint, Academy Learning Tau).
+**Léxico (no negociable):** *strong Level-3* := `Res_pair`. *excess3* := exportable proxy. Report `w` with any Res_pair figure. Abundance (excess3) ≠ aggregation share \(f_3\).
 
 ## Install
 
@@ -53,6 +66,15 @@ print("weights:", out["params"]["alpha_syn"], out["params"]["alpha_surp"])
 print("final T_recd:", float(out["T_recd"][-1]))
 ```
 
+### Strong residual Res_pair (optional)
+
+```python
+out = compute_recd_from_conjunctions(X, compute_res=True)
+# or, on a symbol window:
+from nested_recd import compute_res_pair_window
+# Always report window length with Res_pair (Nota 4: w=13 can bias chaos).
+```
+
 ### Continuous excess³ only
 
 ```python
@@ -79,7 +101,7 @@ out = compute_recd_from_conjunctions(X, tau_s=tau_s)
 out = compute_recd_from_conjunctions(X, lam_override=0.5)
 ```
 
-**Note:** `delta_recd` / `T_recd` use **binary Φ₃** in the α-weighted clock (legacy Discrete Extramental Clock). For scientific Level-3 claims, report **continuous excess³** and nulls on `|Δ excess3|`.
+**Note:** `delta_recd` / `T_recd` use **binary Φ₃** in the α-weighted clock (legacy Discrete Extramental Clock). For **exportable / scalable** Level-3 reporting, use continuous **excess³** and nulls on `|Δ excess3|`. For **strong** Level-3 claims, report **`res_pair`** (enable `compute_res=True`) **and the window `w`**. Do not identify the two.
 
 ## What it computes
 
@@ -87,10 +109,11 @@ out = compute_recd_from_conjunctions(X, lam_override=0.5)
 |--------|---------|
 | **Φ₁** | Co-occurrence of identical ordinal symbols across variable pairs |
 | **Φ₂** | Persistence of pairwise ordinal relations over lag `d` |
-| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**primary** Level-3) |
+| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**exportable Level-3 proxy**; T-IV) |
 | **Φ₃** | Binary ticks of excess³ above `theta3` (**secondary**) |
+| **Res_pair** | Strong Level-3 residual `KL(P ‖ P^(2))` (optional; always report `w`) |
 | **λ** | Chaos / reorganization intensity (from `τ_s` or `lam_override`) |
-| **α(λ)** | Level weights: α₁ decays with λ; α₂, α₃ grow with λ |
+| **α(λ)** | Design-engine weights (template or Gibbs-α); **not** a joint observable |
 | **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` (legacy clock; binary Φ₃) |
 | **T_recd** | Cumulative sum of ΔRECD |
 
@@ -115,7 +138,8 @@ from nested_recd import (
     compute_phi1, compute_phi2, compute_phi3,
     compute_phi3_excess, compute_excess3_window,
     mean_excess_pre_post, surrogate_pvalue_delta_excess3,
-    compute_lambda, alpha_weights, regime_lambda_proxy,
+    compute_lambda, alpha_weights, alpha_weights_gibbs, regime_lambda_proxy,
+    compute_res_pair, compute_res_pair_window,
     compute_weighted_contributions, high_level3_rate,
     generate_multivariate_symbols,
     phase_shuffle_independent, generate_surrogate_ensemble,
@@ -138,6 +162,12 @@ If you use excess³ / Level-3 from this package, cite the **methods** preprint (
 
 > Padilla-Villanueva, J. (2026). *excess³: A Pre-Specified Continuous Proxy for Order-3 Synergistic Surplus* (methods). Zenodo. https://doi.org/10.5281/zenodo.21385937
 
+This software (0.2.3):
+
+> Padilla-Villanueva, J. (2026). *nested-recd 0.2.3: Nested ordinal RECD, excess³ proxy, and Res_pair*. Zenodo. https://doi.org/10.5281/zenodo.22970079
+
+The previous release (0.2.2), which pooled symbols inside Syn, remains citable as https://doi.org/10.5281/zenodo.21937204.
+
 Software / related stack:
 
 > Padilla-Villanueva, J. (2026). Systemic Tau software archive. Zenodo. https://doi.org/10.5281/zenodo.20576241
@@ -152,7 +182,8 @@ CCTP/SDDB pilot:
   title   = {nested-recd: Nested ordinal RECD levels and continuous excess³},
   year    = {2026},
   url     = {https://github.com/johelpadilla/nested-recd},
-  version = {0.2.0}
+  version = {0.2.3},
+  doi     = {10.5281/zenodo.22970079}
 }
 ```
 

{nested_recd-0.2.0 → nested_recd-0.2.3}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nested-recd"
-version = "0.2.0"
-description = "Nested ordinal RECD: Φ1–Φ3, continuous excess³ (primary Level-3), and λ-weighted Discrete Extramental Clock"
+version = "0.2.3"
+description = "Nested ordinal RECD: Φ1–Φ3, continuous excess³ (exportable Level-3 proxy), Res_pair (strong residual), and λ-weighted Discrete Extramental Clock"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
@@ -49,7 +49,7 @@ Homepage = "https://github.com/johelpadilla/nested-recd"
 Repository = "https://github.com/johelpadilla/nested-recd"
 Issues = "https://github.com/johelpadilla/nested-recd/issues"
 Documentation = "https://github.com/johelpadilla/nested-recd#readme"
-DOI = "https://doi.org/10.5281/zenodo.21270699"
+DOI = "https://doi.org/10.5281/zenodo.22970079"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{nested_recd-0.2.0 → nested_recd-0.2.3}/src/nested_recd/__init__.py

@@ -3,7 +3,8 @@ nested-recd
 ===========
 
 Nested ordinal RECD: Φ₁ / Φ₂ / Φ₃ conjunction levels, continuous excess³
-(primary Level-3 readout), and λ-weighted Discrete Extramental Clock.
+(exportable Level-3 proxy; not the strong residual), optional Res_pair,
+and λ-weighted Discrete Extramental Clock.
 
 Quick start
 -----------
@@ -11,7 +12,7 @@ Quick start
 >>> from nested_recd import compute_recd_from_conjunctions
 >>> X = np.random.randn(500, 3).cumsum(axis=0)
 >>> out = compute_recd_from_conjunctions(X)
->>> float(np.nanmean(out["excess3"]))  # continuous primary Level-3 score
+>>> float(np.nanmean(out["excess3"]))  # continuous Level-3 *proxy* (T-IV)
 """
 
 from nested_recd.ordinal_levels import (
@@ -32,10 +33,16 @@ from nested_recd.ordinal_levels import (
     compute_phi3,
     compute_phi3_excess,
     compute_excess3_window,
+    compute_res_pair_window,
+    compute_res_pair,
+    pairwise_maxent_ipf,
+    kl_divergence,
     mean_excess_pre_post,
     surrogate_pvalue_delta_excess3,
     compute_lambda,
     alpha_weights,
+    alpha_weights_gibbs,
+    alpha_compare_template_gibbs,
     regime_lambda_proxy,
     compute_recd_from_conjunctions,
     simple_level_classification,
@@ -51,7 +58,7 @@ from nested_recd.surrogates import (
     compute_null_distribution,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.3"
 
 __all__ = [
     "__version__",
@@ -72,10 +79,16 @@ __all__ = [
     "compute_phi3",
     "compute_phi3_excess",
     "compute_excess3_window",
+    "compute_res_pair_window",
+    "compute_res_pair",
+    "pairwise_maxent_ipf",
+    "kl_divergence",
     "mean_excess_pre_post",
     "surrogate_pvalue_delta_excess3",
     "compute_lambda",
     "alpha_weights",
+    "alpha_weights_gibbs",
+    "alpha_compare_template_gibbs",
     "regime_lambda_proxy",
     "compute_recd_from_conjunctions",
     "simple_level_classification",

{nested_recd-0.2.0 → nested_recd-0.2.3}/src/nested_recd/ordinal_levels.py

@@ -189,62 +189,76 @@ def compute_phi2(
 # NIVEL 3: Emergencia / Sinergia (proxy)
 # ============================================================
 
-def _joint_entropy_and_marginals(S_window: np.ndarray) -> Tuple[float, float, float]:
+def _entropy_from_counts(counts: np.ndarray) -> float:
+    p = counts / counts.sum()
+    return float(-np.sum(p * np.log2(p + 1e-12)))
+
+
+def _joint_entropy_and_marginals(
+    S_window: np.ndarray,
+    legacy_pooled_counting: bool = False,
+) -> Tuple[float, float, float]:
     """
-    Calcula H(joint), promedio H(marginal), y proxy de info mutua pairwise promedio
-    sobre una ventana de símbolos.
-    Muy quirúrgico: conteos exactos (N pequeño, m=3 → 6^N factible).
+    H(joint), sum of marginal entropies, and the Syn proxy on one window.
+
+    Correct joint counting (default since 0.2.3) uses
+    ``np.unique(..., axis=0)`` on rows. ``legacy_pooled_counting=True``
+    reproduces <= 0.2.2, where ``np.unique`` on a list of tuples flattened
+    the tuples, so H_joint and each pairwise H were entropies of pooled
+    symbol values. Use the legacy mode only to reproduce archived numbers.
+
+        TC  = sum_i H(S_i) - H(S)
+        MI  = H(S_i) + H(S_j) - H(S_i, S_j)
+        Syn = max(0, TC - (N-1) * mean MI)
     """
-    T, N = S_window.shape
-    # Joint tuples como tuplas hashables
-    joint_tuples = [tuple(row) for row in S_window]
-    unique_j, counts_j = np.unique(joint_tuples, return_counts=True)
-    p_joint = counts_j / counts_j.sum()
-    H_joint = -np.sum(p_joint * np.log2(p_joint + 1e-12))
+    S_window = np.asarray(S_window)
+    _, N = S_window.shape
+
+    if legacy_pooled_counting:
+        _, counts_j = np.unique(S_window.ravel(), return_counts=True)
+    else:
+        _, counts_j = np.unique(S_window, axis=0, return_counts=True)
+    H_joint = _entropy_from_counts(counts_j)
 
-    # Marginales por variable
     H_margs = []
     for k in range(N):
         _, c = np.unique(S_window[:, k], return_counts=True)
-        p = c / c.sum()
-        H_margs.append(-np.sum(p * np.log2(p + 1e-12)))
-    H_marg_mean = float(np.mean(H_margs))
+        H_margs.append(_entropy_from_counts(c))
     H_marg_sum = float(np.sum(H_margs))
 
-    # Pairwise MI promedio (aprox rápida)
     pair_mi = []
     for i in range(N):
         for j in range(i + 1, N):
-            joint2 = list(zip(S_window[:, i], S_window[:, j]))
-            _, cj = np.unique(joint2, return_counts=True)
-            pj = cj / cj.sum()
-            H2 = -np.sum(pj * np.log2(pj + 1e-12))
-
-            _, ci = np.unique(S_window[:, i], return_counts=True)
-            pi = ci / ci.sum()
-            Hi = -np.sum(pi * np.log2(pi + 1e-12))
-
-            _, cj2 = np.unique(S_window[:, j], return_counts=True)
-            pj2 = cj2 / cj2.sum()
-            Hj = -np.sum(pj2 * np.log2(pj2 + 1e-12))
-
-            mi = Hi + Hj - H2
-            pair_mi.append(max(0.0, mi))
+            pair = S_window[:, [i, j]]
+            if legacy_pooled_counting:
+                _, cj = np.unique(pair.ravel(), return_counts=True)
+            else:
+                _, cj = np.unique(pair, axis=0, return_counts=True)
+            H2 = _entropy_from_counts(cj)
+            pair_mi.append(max(0.0, H_margs[i] + H_margs[j] - H2))
     mi_pair_avg = float(np.mean(pair_mi)) if pair_mi else 0.0
 
-    # Total correlation approx = sum H - H_joint
     tc = H_marg_sum - H_joint
-    # "Synergy beyond pairwise" rough: tc - (N-1)*mi_pair_avg  (heurística; puede ser negativa)
     synergy_proxy = max(0.0, tc - (N - 1) * mi_pair_avg)
-
     return H_joint, H_marg_sum, synergy_proxy
 
 
+def _warn_legacy() -> None:
+    warnings.warn(
+        "legacy_pooled_counting=True reproduces the joint-counting bug of "
+        "nested-recd <= 0.2.2 (pooled symbol values instead of joint tuples "
+        "in H_joint and pairwise H). Use only to reproduce archived results.",
+        UserWarning,
+        stacklevel=3,
+    )
+
+
 def compute_excess3_window(
     win: np.ndarray,
     use_surprise: bool = True,
     alpha_syn: float = ALPHA_SYN,
     alpha_surp: float = ALPHA_SURP,
+    legacy_pooled_counting: bool = False,
 ) -> float:
     """
     excess³ score on a single window of joint ordinal symbols (shape (w, N)).
@@ -259,6 +273,9 @@ def compute_excess3_window(
     Surp: observed-vs-independence joint surprise (frequency-weighted log-ratio).
 
     This is a **proxy**, not a complete PID synergy atom.
+
+    ``legacy_pooled_counting`` (default False) reproduces the <= 0.2.2
+    pooled-symbol bug. Surp is the same in both modes.
     """
     win = np.asarray(win)
     if win.ndim != 2 or win.shape[0] == 0:
@@ -266,7 +283,9 @@ def compute_excess3_window(
     if win.shape[1] < 2:
         return 0.0
 
-    _, _, syn = _joint_entropy_and_marginals(win)
+    _, _, syn = _joint_entropy_and_marginals(
+        win, legacy_pooled_counting=legacy_pooled_counting
+    )
     if not use_surprise:
         return float(syn)
 
@@ -297,6 +316,7 @@ def compute_phi3_excess(
     alpha_syn: float = ALPHA_SYN,
     alpha_surp: float = ALPHA_SURP,
     fill: bool = False,
+    legacy_pooled_counting: bool = False,
 ) -> Tuple[np.ndarray, np.ndarray]:
     """
     Continuous excess³ (primary) and binary Φ₃ (secondary) on symbol matrix S.
@@ -313,7 +333,11 @@ def compute_phi3_excess(
     fill : bool
         If True, forward-fill NaNs after the first finite score (plot convenience).
         Default False preserves sparse stride semantics.
+    legacy_pooled_counting : bool
+        Default False (joint tuples). True reproduces the <= 0.2.2 bug.
     """
+    if legacy_pooled_counting:
+        _warn_legacy()
     S = np.asarray(S)
     T_eff, N = S.shape
     phi3 = np.full(T_eff, np.nan)
@@ -328,6 +352,7 @@ def compute_phi3_excess(
             use_surprise=use_surprise,
             alpha_syn=alpha_syn,
             alpha_surp=alpha_surp,
+            legacy_pooled_counting=legacy_pooled_counting,
         )
         excess[t] = score
         phi3[t] = 1.0 if score > theta else 0.0
@@ -352,6 +377,7 @@ def compute_phi3(
     use_surprise: bool = True,
     alpha_syn: float = ALPHA_SYN,
     alpha_surp: float = ALPHA_SURP,
+    legacy_pooled_counting: bool = False,
 ) -> Tuple[np.ndarray, np.ndarray]:
     """
     Φ₃(t) binary + continuous excess³ series.
@@ -370,9 +396,201 @@ def compute_phi3(
         alpha_syn=alpha_syn,
         alpha_surp=alpha_surp,
         fill=False,
+        legacy_pooled_counting=legacy_pooled_counting,
     )
 
 
+# ============================================================
+# Strong Level-3 residual: Res_pair = KL(P || P^(2))
+# ============================================================
+
+def _empirical_joint_table(win: np.ndarray) -> Tuple[np.ndarray, list]:
+    """
+    Build dense joint probability table over observed symbol alphabet.
+
+    Returns
+    -------
+    p : ndarray shape (k_0, k_1, ..., k_{N-1})
+        Empirical frequencies (sums to 1).
+    levels : list of 1d arrays
+        Sorted unique symbols per coordinate (axis order of ``p``).
+    """
+    win = np.asarray(win)
+    if win.ndim != 2 or win.shape[0] == 0:
+        raise ValueError("win must be (w, N) with w>0")
+    T, N = win.shape
+    levels = [np.unique(win[:, i]) for i in range(N)]
+    shape = tuple(len(lev) for lev in levels)
+    # Map symbols to indices
+    idx = np.zeros((T, N), dtype=int)
+    for i in range(N):
+        # searchsorted works because levels[i] is sorted unique
+        idx[:, i] = np.searchsorted(levels[i], win[:, i])
+    p = np.zeros(shape, dtype=float)
+    for t in range(T):
+        p[tuple(idx[t])] += 1.0
+    p /= p.sum()
+    return p, levels
+
+
+def _pair_marginal(p: np.ndarray, i: int, j: int) -> np.ndarray:
+    """Marginal of joint tensor p over all axes except i and j."""
+    axes = tuple(a for a in range(p.ndim) if a not in (i, j))
+    if axes:
+        m = p.sum(axis=axes)
+    else:
+        m = p.copy()
+    # Ensure axes order (i, j): if i>j, sum order may swap
+    if i > j:
+        m = m.T
+    return m
+
+
+def pairwise_maxent_ipf(
+    p_emp: np.ndarray,
+    max_iter: int = 200,
+    tol: float = 1e-10,
+) -> np.ndarray:
+    """
+    Fit discrete pairwise maxent / IPF model matching all bivariate marginals.
+
+    Starts from the product of univariate marginals and iteratively rescales
+    so that each pair marginal matches that of ``p_emp``. On finite alphabets
+    this is the standard iterative proportional fitting procedure toward the
+    I-projection onto the pairwise exponential family (when it exists in the
+    relative interior).
+
+    Parameters
+    ----------
+    p_emp : ndarray
+        Empirical joint (N-way table).
+    max_iter, tol :
+        Convergence controls.
+
+    Returns
+    -------
+    p2 : ndarray
+        Pairwise-consistent joint with same shape as ``p_emp``.
+    """
+    p_emp = np.asarray(p_emp, dtype=float)
+    if p_emp.ndim < 2:
+        return p_emp.copy()
+    N = p_emp.ndim
+    # Univariate marginals
+    marg1 = []
+    for i in range(N):
+        axes = tuple(a for a in range(N) if a != i)
+        mi = p_emp.sum(axis=axes)
+        marg1.append(mi)
+    # Initialize as product of marginals
+    p = marg1[0]
+    for i in range(1, N):
+        p = p[..., None] * marg1[i]
+    # p may need reshape to full shape
+    p = np.broadcast_to(p, p_emp.shape).astype(float).copy()
+    # Target pair marginals
+    targets = {}
+    for i in range(N):
+        for j in range(i + 1, N):
+            targets[(i, j)] = _pair_marginal(p_emp, i, j)
+
+    for _ in range(max_iter):
+        max_dev = 0.0
+        for i in range(N):
+            for j in range(i + 1, N):
+                cur = _pair_marginal(p, i, j)
+                tgt = targets[(i, j)]
+                # Avoid div by zero: only rescale cells with positive cur
+                ratio = np.ones_like(tgt)
+                mask = cur > 0
+                ratio[mask] = tgt[mask] / cur[mask]
+                # Broadcast ratio onto full joint
+                # Build scaling tensor
+                scale = ratio
+                # Insert singleton dims for axes other than i,j
+                shape = [1] * N
+                shape[i] = p.shape[i]
+                shape[j] = p.shape[j]
+                # ratio is (k_i, k_j); reshape
+                scale = scale.reshape(shape)
+                p = p * scale
+                # Renormalize lightly for numerical stability
+                s = p.sum()
+                if s > 0:
+                    p /= s
+                max_dev = max(max_dev, float(np.max(np.abs(cur - tgt))))
+        if max_dev < tol:
+            break
+    return p
+
+
+def kl_divergence(p: np.ndarray, q: np.ndarray, eps: float = 1e-12) -> float:
+    """KL(p||q) in bits over a common support table."""
+    p = np.asarray(p, dtype=float)
+    q = np.asarray(q, dtype=float)
+    mask = p > 0
+    q_safe = np.maximum(q, eps)
+    return float(np.sum(p[mask] * np.log2(p[mask] / q_safe[mask])))
+
+
+def compute_res_pair_window(win: np.ndarray, max_iter: int = 200) -> float:
+    """
+    Strong Level-3 residual on one window of joint symbols.
+
+        Res_pair = KL(P_emp || P^(2))
+
+    where P^(2) is the pairwise IPF / maxent fit to all bipolar marginals
+    (Foundations paper / Nota formal 2).
+
+    For N<3 the residual is identically 0 (no order-3 structure possible).
+    """
+    win = np.asarray(win)
+    if win.ndim != 2 or win.shape[0] == 0:
+        return float("nan")
+    if win.shape[1] < 3:
+        return 0.0
+    try:
+        p_emp, _ = _empirical_joint_table(win)
+    except ValueError:
+        return float("nan")
+    # Degenerate: if support is too thin, IPF still runs on observed alphabet
+    p2 = pairwise_maxent_ipf(p_emp, max_iter=max_iter)
+    return kl_divergence(p_emp, p2)
+
+
+def compute_res_pair(
+    S: np.ndarray,
+    window: int = DEFAULT_WINDOW_TAU,
+    stride: int = 1,
+    max_iter: int = 200,
+    fill: bool = False,
+) -> np.ndarray:
+    """
+    Windowed strong Level-3 residual Res_pair(t) on symbol matrix S (T, N).
+
+    Primary theoretical Level-3 object; excess3 remains the scalable proxy.
+    Computational cost grows with alphabet product; intended for small N
+    (e.g. m=3 Bandt–Pompe, N<=4–5) or as a validation diagnostic.
+    """
+    S = np.asarray(S)
+    T_eff, N = S.shape
+    out = np.full(T_eff, np.nan)
+    if T_eff < window or N < 3:
+        if N < 3:
+            out[:] = 0.0
+        return out
+    for t in range(window - 1, T_eff, stride):
+        out[t] = compute_res_pair_window(S[t - window + 1 : t + 1], max_iter=max_iter)
+    if fill:
+        last = np.nan
+        for t in range(T_eff):
+            if np.isfinite(out[t]):
+                last = out[t]
+            elif np.isfinite(last):
+                out[t] = last
+    return out
+
+
 def mean_excess_pre_post(
     excess3: np.ndarray,
     split: int,
@@ -404,6 +622,7 @@ def surrogate_pvalue_delta_excess3(
     delay: int = DEFAULT_DELAY,
     alpha_syn: float = ALPHA_SYN,
     alpha_surp: float = ALPHA_SURP,
+    legacy_pooled_counting: bool = False,
 ) -> Dict[str, float]:
     """
     Two-sided surrogate p-value for |Δ excess3| under independent phase-shuffle
@@ -444,6 +663,7 @@ def surrogate_pvalue_delta_excess3(
             stride=stride,
             alpha_syn=alpha_syn,
             alpha_surp=alpha_surp,
+            legacy_pooled_counting=legacy_pooled_counting,
         )
         _, _, d = mean_excess_pre_post(excess, split_s)
         return float(d)
@@ -515,7 +735,10 @@ def alpha_weights(
     delta3: float = 2.0
 ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
     """
-    Retorna α1(λ), α2(λ), α3(λ) según la forma propuesta.
+    Template α family (Via A / design engine defaults).
+
+    Returns α1(λ), α2(λ), α3(λ). Not normalized; used as relative weights
+    in ΔRECD and f_ℓ shares. Foundations Note 3.
     """
     a1 = alpha10 * np.exp(-beta1 * lam)
     a2 = alpha20 * (1.0 + gamma2 * lam)
@@ -523,6 +746,93 @@ def alpha_weights(
     return a1, a2, a3
 
 
+def alpha_weights_gibbs(
+    lam: np.ndarray,
+    u: Tuple[float, float, float] = (0.0, 1.0, 2.0),
+    beta0: float = 0.0,
+    kappa: float = 1.5,
+    normalize: bool = False,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Gibbs / maxent depth weights (Via B, Foundations Note 3).
+
+        α_ℓ^G(λ) ∝ exp( β(λ) · u(ℓ) ),   β(λ) = β0 + κ·λ ≥ 0
+
+    with u(1) < u(2) < u(3). Relative monotonicity α3/α1 = exp(β·Δu)
+    increases in λ when κ≥0. This is an *admissible design engine*, not
+    an observable of the joint S_t.
+
+    Parameters
+    ----------
+    lam : array-like
+        Regime intensity λ ≥ 0.
+    u : triple
+        Depth utilities (u1, u2, u3), strictly increasing recommended.
+    beta0, kappa :
+        β(λ) = max(0, β0 + κ·λ).
+    normalize :
+        If True, return simplex weights (sum_ℓ α_ℓ = 1). If False (default),
+        return unnormalized positive weights comparable in spirit to the
+        template family (which is also unnormalized).
+
+    Returns
+    -------
+    a1, a2, a3 : ndarrays
+        Gibbs depth weights.
+    """
+    lam = np.asarray(lam, dtype=float)
+    u1, u2, u3 = u
+    beta = np.maximum(0.0, beta0 + kappa * lam)
+    e1 = np.exp(beta * u1)
+    e2 = np.exp(beta * u2)
+    e3 = np.exp(beta * u3)
+    if normalize:
+        z = e1 + e2 + e3
+        return e1 / z, e2 / z, e3 / z
+    return e1, e2, e3
+
+
+def alpha_compare_template_gibbs(
+    lam_grid: Optional[np.ndarray] = None,
+    u: Tuple[float, float, float] = (0.0, 1.0, 2.0),
+    beta0: float = 0.0,
+    kappa: float = 1.5,
+    **template_kwargs,
+) -> Dict[str, np.ndarray]:
+    """
+    Compare normalized template vs Gibbs α on a λ grid (Conj. bridge Note 3).
+
+    Both families are L1-normalized per λ so shapes are comparable.
+    Returns dict with lam, a*_template, a*_gibbs, L1 and L∞ errors.
+    """
+    if lam_grid is None:
+        lam_grid = np.linspace(0.0, 2.0, 41)
+    lam_grid = np.asarray(lam_grid, dtype=float)
+    t1, t2, t3 = alpha_weights(lam_grid, **template_kwargs)
+    g1, g2, g3 = alpha_weights_gibbs(
+        lam_grid, u=u, beta0=beta0, kappa=kappa, normalize=False
+    )
+    # L1 normalize each family
+    ts = t1 + t2 + t3
+    gs = g1 + g2 + g3
+    nt = (t1 / ts, t2 / ts, t3 / ts)
+    ng = (g1 / gs, g2 / gs, g3 / gs)
+    l1 = np.abs(nt[0] - ng[0]) + np.abs(nt[1] - ng[1]) + np.abs(nt[2] - ng[2])
+    linf = np.maximum.reduce(
+        [np.abs(nt[0] - ng[0]), np.abs(nt[1] - ng[1]), np.abs(nt[2] - ng[2])]
+    )
+    return {
+        "lam": lam_grid,
+        "t1": nt[0], "t2": nt[1], "t3": nt[2],
+        "g1": ng[0], "g2": ng[1], "g3": ng[2],
+        "L1": l1,
+        "Linf": linf,
+        "max_L1": np.array([float(np.max(l1))]),
+        "max_Linf": np.array([float(np.max(linf))]),
+        "mean_L1": np.array([float(np.mean(l1))]),
+    }
+
+
 def regime_lambda_proxy(
     r: float,
     r_onset: float = 3.57,
@@ -561,17 +871,22 @@ def compute_recd_from_conjunctions(
     stride: int = 1,
     alpha_syn: float = ALPHA_SYN,
     alpha_surp: float = ALPHA_SURP,
+    compute_res: bool = False,
+    legacy_pooled_counting: bool = False,
     **alpha_kwargs
 ) -> Dict[str, np.ndarray]:
     """
     Full nested ordinal RECD pipeline:
     - Bandt–Pompe symbols
-    - Φ1, Φ2, Φ3 (binary) + continuous excess³ (primary Level-3 readout)
+    - Φ1, Φ2, Φ3 (binary) + continuous excess³ (exportable Level-3 proxy)
+    - optional ``res_pair`` strong residual (IPF / KL to pairwise maxent)
     - λ and α(λ) regime weights
     - ΔRECD and cumulative T_recd
 
-    Level-3 contract (excess³ methods):
-    - Continuous ``excess3`` is the primary magnitude for order-3 claims.
+    Level-3 contract (excess³ methods + foundations paper):
+    - Continuous ``excess3`` is the scalable primary *proxy* for order-3 claims.
+    - ``res_pair`` (if ``compute_res=True``) is the strong theoretical residual
+      Res_pair = KL(P || P^(2)); costly for large alphabets / N.
     - ``phi3`` is a secondary threshold discretisation of excess3.
     - ``delta_recd`` keeps the legacy λ-weighted clock using **binary** Φ₃
       (back-compat with CCTP / Discrete Extramental Clock nesting). Do not
@@ -591,6 +906,12 @@ def compute_recd_from_conjunctions(
         stride=stride,
         alpha_syn=alpha_syn,
         alpha_surp=alpha_surp,
+        legacy_pooled_counting=legacy_pooled_counting,
+    )
+    res_pair = (
+        compute_res_pair(S, window=window_tau, stride=stride)
+        if compute_res
+        else None
     )
 
     # Determinar λ: override > tau-derived > zero
@@ -619,7 +940,7 @@ def compute_recd_from_conjunctions(
     delta_recd = a1 * phi1 + a2 * phi2 + a3 * phi3_safe
     T_recd = np.nancumsum(delta_recd)
 
-    return {
+    result = {
         "S": S,
         "phi1": phi1,
         "phi2": phi2,
@@ -641,9 +962,15 @@ def compute_recd_from_conjunctions(
             "alpha_surp": alpha_surp,
             "level3_primary": "excess3",
             "level3_secondary": "phi3",
+            "level3_strong": "res_pair",
+            "compute_res": compute_res,
+            "legacy_pooled_counting": legacy_pooled_counting,
             **alpha_kwargs,
         },
     }
+    if res_pair is not None:
+        result["res_pair"] = res_pair
+    return result
 
 
 # ============================================================

{nested_recd-0.2.0 → nested_recd-0.2.3/src/nested_recd.egg-info}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: nested-recd
-Version: 0.2.0
-Summary: Nested ordinal RECD: Φ1–Φ3, continuous excess³ (primary Level-3), and λ-weighted Discrete Extramental Clock
+Version: 0.2.3
+Summary: Nested ordinal RECD: Φ1–Φ3, continuous excess³ (exportable Level-3 proxy), Res_pair (strong residual), and λ-weighted Discrete Extramental Clock
 Author-email: Johel Padilla-Villanueva <joel.padilla2@upr.edu>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/johelpadilla/nested-recd
 Project-URL: Repository, https://github.com/johelpadilla/nested-recd
 Project-URL: Issues, https://github.com/johelpadilla/nested-recd/issues
 Project-URL: Documentation, https://github.com/johelpadilla/nested-recd#readme
-Project-URL: DOI, https://doi.org/10.5281/zenodo.21270699
+Project-URL: DOI, https://doi.org/10.5281/zenodo.22970079
 Keywords: RECD,ordinal patterns,nested time,Systemic Tau,complexity,early-warning,network physiology,Bandt-Pompe
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -35,13 +35,26 @@ Dynamic: license-file
 
 # nested-recd
 
+> **Correction (0.2.3).** Versions ≤ 0.2.2 computed `H_joint` and the pairwise
+> entropies inside `Syn` with `np.unique` on a list of tuples and no `axis=0`.
+> NumPy flattens that input, so `Syn`, `excess3` and binary `phi3` were not the
+> published definition when `N ≥ 3`. `Surp` and `Res_pair` were not affected.
+> For `N = 2`, `Syn` is 0 either way. 0.2.3 counts joint rows.
+> `legacy_pooled_counting=True` reproduces the old numbers and warns.
+> See `CHANGELOG.md`. This version:
+> [10.5281/zenodo.22970079](https://doi.org/10.5281/zenodo.22970079).
+> The 0.2.2 deposit remains
+> [10.5281/zenodo.21937204](https://doi.org/10.5281/zenodo.21937204).
+
 [![PyPI version](https://img.shields.io/pypi/v/nested-recd.svg)](https://pypi.org/project/nested-recd/)
 [![Python](https://img.shields.io/pypi/pyversions/nested-recd.svg)](https://pypi.org/project/nested-recd/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 proxy, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 *proxy* (T-IV; not the strong residual), optional **Res_pair** \(=\mathrm{KL}(P\|P^{(2)})\), Gibbs-α weights, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+
+This is the **canonical nested-clock software** for the Systemic Tau / RECD stack (foundations paper, excess³ methods preprint, cardiac CCTP/SDDB pilot, Academy Learning Tau).
 
-This is the **canonical Level-3 software** for the Systemic Tau / RECD stack (cardiac CCTP/SDDB pilot, excess³ methods preprint, Academy Learning Tau).
+**Léxico (no negociable):** *strong Level-3* := `Res_pair`. *excess3* := exportable proxy. Report `w` with any Res_pair figure. Abundance (excess3) ≠ aggregation share \(f_3\).
 
 ## Install
 
@@ -88,6 +101,15 @@ print("weights:", out["params"]["alpha_syn"], out["params"]["alpha_surp"])
 print("final T_recd:", float(out["T_recd"][-1]))
 ```
 
+### Strong residual Res_pair (optional)
+
+```python
+out = compute_recd_from_conjunctions(X, compute_res=True)
+# or, on a symbol window:
+from nested_recd import compute_res_pair_window
+# Always report window length with Res_pair (Nota 4: w=13 can bias chaos).
+```
+
 ### Continuous excess³ only
 
 ```python
@@ -114,7 +136,7 @@ out = compute_recd_from_conjunctions(X, tau_s=tau_s)
 out = compute_recd_from_conjunctions(X, lam_override=0.5)
 ```
 
-**Note:** `delta_recd` / `T_recd` use **binary Φ₃** in the α-weighted clock (legacy Discrete Extramental Clock). For scientific Level-3 claims, report **continuous excess³** and nulls on `|Δ excess3|`.
+**Note:** `delta_recd` / `T_recd` use **binary Φ₃** in the α-weighted clock (legacy Discrete Extramental Clock). For **exportable / scalable** Level-3 reporting, use continuous **excess³** and nulls on `|Δ excess3|`. For **strong** Level-3 claims, report **`res_pair`** (enable `compute_res=True`) **and the window `w`**. Do not identify the two.
 
 ## What it computes
 
@@ -122,10 +144,11 @@ out = compute_recd_from_conjunctions(X, lam_override=0.5)
 |--------|---------|
 | **Φ₁** | Co-occurrence of identical ordinal symbols across variable pairs |
 | **Φ₂** | Persistence of pairwise ordinal relations over lag `d` |
-| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**primary** Level-3) |
+| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**exportable Level-3 proxy**; T-IV) |
 | **Φ₃** | Binary ticks of excess³ above `theta3` (**secondary**) |
+| **Res_pair** | Strong Level-3 residual `KL(P ‖ P^(2))` (optional; always report `w`) |
 | **λ** | Chaos / reorganization intensity (from `τ_s` or `lam_override`) |
-| **α(λ)** | Level weights: α₁ decays with λ; α₂, α₃ grow with λ |
+| **α(λ)** | Design-engine weights (template or Gibbs-α); **not** a joint observable |
 | **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` (legacy clock; binary Φ₃) |
 | **T_recd** | Cumulative sum of ΔRECD |
 
@@ -150,7 +173,8 @@ from nested_recd import (
     compute_phi1, compute_phi2, compute_phi3,
     compute_phi3_excess, compute_excess3_window,
     mean_excess_pre_post, surrogate_pvalue_delta_excess3,
-    compute_lambda, alpha_weights, regime_lambda_proxy,
+    compute_lambda, alpha_weights, alpha_weights_gibbs, regime_lambda_proxy,
+    compute_res_pair, compute_res_pair_window,
     compute_weighted_contributions, high_level3_rate,
     generate_multivariate_symbols,
     phase_shuffle_independent, generate_surrogate_ensemble,
@@ -173,6 +197,12 @@ If you use excess³ / Level-3 from this package, cite the **methods** preprint (
 
 > Padilla-Villanueva, J. (2026). *excess³: A Pre-Specified Continuous Proxy for Order-3 Synergistic Surplus* (methods). Zenodo. https://doi.org/10.5281/zenodo.21385937
 
+This software (0.2.3):
+
+> Padilla-Villanueva, J. (2026). *nested-recd 0.2.3: Nested ordinal RECD, excess³ proxy, and Res_pair*. Zenodo. https://doi.org/10.5281/zenodo.22970079
+
+The previous release (0.2.2), which pooled symbols inside Syn, remains citable as https://doi.org/10.5281/zenodo.21937204.
+
 Software / related stack:
 
 > Padilla-Villanueva, J. (2026). Systemic Tau software archive. Zenodo. https://doi.org/10.5281/zenodo.20576241
@@ -187,7 +217,8 @@ CCTP/SDDB pilot:
   title   = {nested-recd: Nested ordinal RECD levels and continuous excess³},
   year    = {2026},
   url     = {https://github.com/johelpadilla/nested-recd},
-  version = {0.2.0}
+  version = {0.2.3},
+  doi     = {10.5281/zenodo.22970079}
 }
 ```
 

{nested_recd-0.2.0 → nested_recd-0.2.3}/src/nested_recd.egg-info/SOURCES.txt

@@ -10,4 +10,5 @@ src/nested_recd.egg-info/SOURCES.txt
 src/nested_recd.egg-info/dependency_links.txt
 src/nested_recd.egg-info/requires.txt
 src/nested_recd.egg-info/top_level.txt
+tests/test_joint_counting.py
 tests/test_smoke.py

nested_recd-0.2.3/tests/test_joint_counting.py

@@ -0,0 +1,144 @@
+"""Regression tests for the joint-counting fix (0.2.3).
+
+nested-recd <= 0.2.2 computed H_joint and the pairwise H(S_i, S_j) inside
+``_joint_entropy_and_marginals`` over pooled symbol values (np.unique on a
+list of tuples flattens it). These tests pin the joint-tuple values.
+``test_xor_synergy_is_one_bit`` and ``test_joint_entropy_counts_tuples``
+fail on 0.2.2 and pass on 0.2.3.
+"""
+import inspect
+
+import numpy as np
+import pytest
+
+from nested_recd import compute_excess3_window, compute_phi3_excess
+from nested_recd.ordinal_levels import _joint_entropy_and_marginals
+
+
+def _xor_window(reps: int = 3) -> np.ndarray:
+    # columns: a, b independent fair bits; c = a XOR b; d constant
+    base = np.array(
+        [
+            [0, 0, 0, 0],
+            [0, 1, 1, 0],
+            [1, 0, 1, 0],
+            [1, 1, 0, 0],
+        ]
+    )
+    return np.tile(base, (reps, 1))
+
+
+def test_xor_synergy_is_one_bit():
+    """XOR: every pair is independent (MI = 0) but the triple carries 1 bit.
+
+    H_joint = 2, sum H_i = 3, TC = 1, mean MI = 0 -> Syn = 1 bit.
+    0.2.2 returns H_joint = 0.954 and Syn = 0.263.
+    """
+    H_joint, H_sum, syn = _joint_entropy_and_marginals(_xor_window())
+    assert H_joint == pytest.approx(2.0, abs=1e-9)
+    assert H_sum == pytest.approx(3.0, abs=1e-9)
+    assert syn == pytest.approx(1.0, abs=1e-9)
+
+
+def test_joint_entropy_counts_tuples():
+    """13 distinct joint tuples in a window of 13 -> H_joint = log2(13)."""
+    rng = np.random.default_rng(0)
+    while True:
+        win = rng.integers(0, 6, size=(13, 4))
+        if len({tuple(r) for r in win}) == 13:
+            break
+    H_joint, _, _ = _joint_entropy_and_marginals(win)
+    assert H_joint == pytest.approx(np.log2(13), abs=1e-9)
+
+
+def test_identical_columns_have_no_synergy():
+    """Four copies of one series: TC = 3 H, every MI = H -> Syn = 0."""
+    rng = np.random.default_rng(1)
+    x = rng.integers(0, 6, size=40)
+    win = np.stack([x, x, x, x], axis=1)
+    H_joint, H_sum, syn = _joint_entropy_and_marginals(win)
+    assert H_sum == pytest.approx(4 * H_joint, abs=1e-9)
+    assert syn == pytest.approx(0.0, abs=1e-9)
+
+
+def test_matches_counter_reference():
+    """Random windows agree with an independent Counter-over-tuples version."""
+    from collections import Counter
+
+    def H(counter):
+        c = np.array(list(counter.values()), float)
+        p = c / c.sum()
+        return float(-np.sum(p * np.log2(p + 1e-12)))
+
+    rng = np.random.default_rng(2)
+    for _ in range(200):
+        win = rng.integers(0, 6, size=(13, 4))
+        N = win.shape[1]
+        rows = [tuple(r) for r in win.tolist()]
+        Hj = H(Counter(rows))
+        Hm = [H(Counter(win[:, k].tolist())) for k in range(N)]
+        mi = [
+            max(
+                0.0,
+                Hm[i]
+                + Hm[j]
+                - H(Counter(zip(win[:, i].tolist(), win[:, j].tolist()))),
+            )
+            for i in range(N)
+            for j in range(i + 1, N)
+        ]
+        syn_ref = max(0.0, sum(Hm) - Hj - (N - 1) * np.mean(mi))
+        H_joint, H_sum, syn = _joint_entropy_and_marginals(win)
+        assert H_joint == pytest.approx(Hj, abs=1e-12)
+        assert syn == pytest.approx(syn_ref, abs=1e-12)
+
+
+def test_legacy_flag_reproduces_022():
+    """legacy_pooled_counting=True reproduces nested-recd 0.2.2."""
+    assert "legacy_pooled_counting" in inspect.signature(
+        _joint_entropy_and_marginals
+    ).parameters
+    H_joint, _, syn = _joint_entropy_and_marginals(
+        _xor_window(), legacy_pooled_counting=True
+    )
+    assert H_joint == pytest.approx(LEGACY_XOR_HJOINT, abs=1e-12)
+    assert syn == pytest.approx(LEGACY_XOR_SYN, abs=1e-12)
+    rng = np.random.default_rng(3)
+    win = rng.integers(0, 6, size=(13, 4))
+    assert compute_excess3_window(
+        win, legacy_pooled_counting=True
+    ) == pytest.approx(LEGACY_RANDOM_EXCESS3, abs=1e-12)
+
+
+def test_legacy_flag_warns():
+    S = np.random.default_rng(4).integers(0, 6, size=(40, 4))
+    with pytest.warns(UserWarning, match="0.2.2"):
+        compute_phi3_excess(S, legacy_pooled_counting=True)
+
+
+def test_surp_unchanged_by_fix():
+    """Surp always counted tuples: with Syn switched off both modes agree."""
+    rng = np.random.default_rng(5)
+    for _ in range(50):
+        win = rng.integers(0, 6, size=(13, 4))
+        a = compute_excess3_window(win, alpha_syn=0.0, alpha_surp=1.0)
+        b = compute_excess3_window(
+            win, alpha_syn=0.0, alpha_surp=1.0, legacy_pooled_counting=True
+        )
+        assert a == pytest.approx(b, abs=1e-15)
+
+
+def test_bivariate_synergy_is_zero():
+    """For N=2, Syn = TC - MI of that single pair, so both modes give 0."""
+    rng = np.random.default_rng(8)
+    win = rng.integers(0, 6, size=(13, 2))
+    _, _, syn = _joint_entropy_and_marginals(win)
+    _, _, legacy = _joint_entropy_and_marginals(win, legacy_pooled_counting=True)
+    assert syn == pytest.approx(0.0, abs=1e-12)
+    assert legacy == pytest.approx(0.0, abs=1e-12)
+
+
+# Frozen outputs of nested-recd 0.2.2
+LEGACY_XOR_HJOINT = 0.9544340029220797
+LEGACY_XOR_SYN = 0.2624831837630126
+LEGACY_RANDOM_EXCESS3 = 2.355186195068367

{nested_recd-0.2.0 → nested_recd-0.2.3}/tests/test_smoke.py

@@ -9,11 +9,15 @@ from nested_recd import (
     ALPHA_SURP,
     DEFAULT_THETA3,
     DEFAULT_THETA3_CARDIO,
+    alpha_weights,
+    alpha_weights_gibbs,
+    alpha_compare_template_gibbs,
     compute_recd_from_conjunctions,
     compute_phi1,
     compute_phi3,
     compute_phi3_excess,
     compute_excess3_window,
+    compute_res_pair_window,
     compute_weighted_contributions,
     generate_multivariate_symbols,
     mean_excess_pre_post,
@@ -24,7 +28,29 @@ from nested_recd import (
 
 
 def test_version():
-    assert __version__ == "0.2.0"
+    assert __version__ == "0.2.3"
+
+
+def test_gibbs_alpha_monotonicity():
+    """α3/α1 increases with λ when κ>0 (Note 3 Prop. Gibbs admissible)."""
+    lam = np.array([0.0, 0.5, 1.0, 2.0])
+    a1, a2, a3 = alpha_weights_gibbs(lam, kappa=1.5, normalize=False)
+    ratio = a3 / np.maximum(a1, 1e-15)
+    assert np.all(np.diff(ratio) >= -1e-12)
+    assert float(ratio[-1]) > float(ratio[0])
+    # normalized simplex
+    n1, n2, n3 = alpha_weights_gibbs(lam, normalize=True)
+    assert np.allclose(n1 + n2 + n3, 1.0)
+
+
+def test_template_gibbs_bridge_bounded():
+    """Conj. bridge: L∞ distance of normalized families on [0,2] is finite."""
+    cmp = alpha_compare_template_gibbs()
+    assert float(cmp["max_Linf"][0]) < 1.0
+    assert float(cmp["max_L1"][0]) < 2.0
+    # both put more mass on level 3 at high λ than at λ=0
+    assert float(cmp["t3"][-1]) > float(cmp["t3"][0])
+    assert float(cmp["g3"][-1]) > float(cmp["g3"][0])
 
 
 def test_weights_a_priori():
@@ -132,6 +158,42 @@ def test_excess3_window_weights():
     assert score >= 0.0
 
 
+def test_res_pair_xor_vs_common_driver():
+    """Strong L3: XOR residual > common-driver residual (Nota 2 geometry)."""
+    rng = np.random.default_rng(42)
+    n = 400
+    # XOR / parity lock
+    a = rng.integers(0, 2, size=n)
+    b = rng.integers(0, 2, size=n)
+    c = a ^ b
+    win_xor = np.column_stack([a, b, c]).astype(int)
+    res_xor = compute_res_pair_window(win_xor)
+    # Common driver: b,c ≈ a
+    driver = rng.integers(0, 2, size=n)
+    noise = rng.random(n) < 0.05
+    b2 = np.where(noise, 1 - driver, driver)
+    noise2 = rng.random(n) < 0.05
+    c2 = np.where(noise2, 1 - driver, driver)
+    win_drv = np.column_stack([driver, b2, c2]).astype(int)
+    res_drv = compute_res_pair_window(win_drv)
+    assert res_xor >= 0.0 and res_drv >= 0.0
+    assert res_xor > res_drv + 0.05  # clear geometric separation
+
+
+def test_res_pair_d2_is_zero():
+    win = np.column_stack([np.zeros(30, dtype=int), np.ones(30, dtype=int)])
+    assert compute_res_pair_window(win) == 0.0
+
+
+def test_pipeline_optional_res_pair():
+    rng = np.random.default_rng(9)
+    X = rng.normal(size=(180, 3)).cumsum(axis=0)
+    out = compute_recd_from_conjunctions(X, compute_res=True, window_tau=20, stride=5)
+    assert "res_pair" in out
+    assert out["res_pair"].shape == out["excess3"].shape
+    assert np.nanmin(out["res_pair"][np.isfinite(out["res_pair"])]) >= -1e-9
+
+
 def test_mean_excess_pre_post():
     x = np.array([0.0, 0.0, 1.0, 1.0, 1.0])
     pre, post, delta = mean_excess_pre_post(x, split=2)