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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: nested-recd
-Version: 0.1.0
-Summary: Nested ordinal RECD: Φ1–Φ3 conjunction levels and λ-weighted Discrete Extramental Clock
+Version: 0.2.0
+Summary: Nested ordinal RECD: Φ1–Φ3, continuous excess³ (primary Level-3), 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
@@ -39,9 +39,9 @@ Dynamic: license-file
 [![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 (Φ₁, Φ₂, Φ₃) and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 proxy, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
 
-This is the standalone library behind the nested-time structure used in the CCTP/SDDB cardiac pilot and the experimental design in *Conversación de la naturaleza del tiempo*.
+This is the **canonical Level-3 software** for the Systemic Tau / RECD stack (cardiac CCTP/SDDB pilot, excess³ methods preprint, Academy Learning Tau).
 
 ## Install
 
@@ -49,56 +49,85 @@ This is the standalone library behind the nested-time structure used in the CCTP
 pip install nested-recd
 ```
 
-From source:
+From source (development):
 
 ```bash
-pip install git+https://github.com/johelpadilla/nested-recd.git
+pip install -e ".[dev]"
 ```
 
+## excess³ contract (methods)
+
+Canonical specification: Padilla-Villanueva (2026), *excess³: A Pre-Specified Continuous Proxy…*  
+DOI: [10.5281/zenodo.21385937](https://doi.org/10.5281/zenodo.21385937) · repo: [github.com/johelpadilla/excess3](https://github.com/johelpadilla/excess3)
+
+| Rule | Software |
+|------|----------|
+| `excess3 = 0.6·Syn + 0.4·Surp` | `ALPHA_SYN`, `ALPHA_SURP` (fixed a priori) |
+| Continuous primary | `out["excess3"]` / `compute_phi3_excess` |
+| Φ₃ secondary | binary ticks of excess3 vs `theta3` |
+| Null on full contrast | `surrogate_pvalue_delta_excess3` (phase-shuffle / permute on `\|Δ\|`) |
+| Proxy ≠ full PID | documented; no complete Williams–Beer atom claimed |
+| Parallel nesting | Φ₁, Φ₂, excess³ computed without hard Boolean ascent |
+
+Defaults: `m=3`, delay `1`, window `13`, `theta3=0.10` (software); cardio-like reference `DEFAULT_THETA3_CARDIO=0.08`.
+
 ## Quick start
 
 ```python
 import numpy as np
-from nested_recd import compute_recd_from_conjunctions, compute_weighted_contributions
+from nested_recd import compute_recd_from_conjunctions, ALPHA_SYN, ALPHA_SURP
 
-# Multivariate series: shape (T, N)
 rng = np.random.default_rng(0)
 X = rng.normal(size=(800, 3)).cumsum(axis=0)
 
 out = compute_recd_from_conjunctions(X, m=3, d=4, theta3=0.10)
 
-print("mean Φ1:", float(np.nanmean(out["phi1"])))
-print("mean Φ2:", float(np.nanmean(out["phi2"])))
+print("mean excess³ (primary):", float(np.nanmean(out["excess3"])))
 print("Φ3 active fraction:", float(np.nanmean(out["phi3"] > 0)))
+print("weights:", out["params"]["alpha_syn"], out["params"]["alpha_surp"])
 print("final T_recd:", float(out["T_recd"][-1]))
+```
 
-w = compute_weighted_contributions(out)
-print("frac level-3 contribution:", w["frac_contrib3"])
+### Continuous excess³ only
+
+```python
+from nested_recd import generate_multivariate_symbols, compute_phi3_excess
+
+S = generate_multivariate_symbols(X, m=3)
+phi3, excess3 = compute_phi3_excess(S, window=13, theta=0.10, stride=1)
 ```
 
-Optional: supply a Systemic Tau series `tau_s` (aligned in time) so that λ is derived empirically:
+### Surrogate p-value on |Δ excess3|
 
 ```python
-out = compute_recd_from_conjunctions(X, tau_s=tau_s)
+from nested_recd import surrogate_pvalue_delta_excess3
+
+res = surrogate_pvalue_delta_excess3(X, split=400, n_surr=99, method="phase", seed=0)
+print(res["delta_obs"], res["p_value"])
 ```
 
-Or fix the regime weight with a scalar / array override:
+### Optional τ_s for λ regime weights
 
 ```python
+out = compute_recd_from_conjunctions(X, tau_s=tau_s)
+# or
 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|`.
+
 ## What it computes
 
 | Symbol | Meaning |
 |--------|---------|
 | **Φ₁** | Co-occurrence of identical ordinal symbols across variable pairs |
 | **Φ₂** | Persistence of pairwise ordinal relations over lag `d` |
-| **Φ₃** | Higher-order synergy proxy (total-correlation excess + joint surprise) |
+| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**primary** Level-3) |
+| **Φ₃** | Binary ticks of excess³ above `theta3` (**secondary**) |
 | **λ** | Chaos / reorganization intensity (from `τ_s` or `lam_override`) |
 | **α(λ)** | Level weights: α₁ decays with λ; α₂, α₃ grow with λ |
-| **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` |
-| **T_recd** | Cumulative sum of ΔRECD (nested-time clock) |
+| **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` (legacy clock; binary Φ₃) |
+| **T_recd** | Cumulative sum of ΔRECD |
 
 Ordinal symbols use Bandt–Pompe patterns (`m=3` by default).
 
@@ -107,7 +136,7 @@ Ordinal symbols use Bandt–Pompe patterns (`m=3` by default).
 ```python
 from nested_recd import phase_shuffle_independent, random_permutation_independent
 
-X_null = phase_shuffle_independent(X, seed=42)   # IAAFT per column
+X_null = phase_shuffle_independent(X, seed=42)
 X_perm = random_permutation_independent(X, seed=42)
 ```
 
@@ -115,8 +144,12 @@ X_perm = random_permutation_independent(X, seed=42)
 
 ```python
 from nested_recd import (
+    ALPHA_SYN, ALPHA_SURP,
+    DEFAULT_THETA3, DEFAULT_THETA3_CARDIO,
     compute_recd_from_conjunctions,
     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_weighted_contributions, high_level3_rate,
     generate_multivariate_symbols,
@@ -128,25 +161,33 @@ from nested_recd import (
 
 | Project | Role |
 |---------|------|
-| [`systemictau`](https://pypi.org/project/systemictau/) | Full Systemic Tau library (τ_s, platform, studio) |
-| [`cctp-sddb-systemic-tau`](https://github.com/johelpadilla/cctp-sddb-systemic-tau) | Cardiac VF pilot using this nested RECD pipeline |
-| This package | Lightweight, installable nested-time / ordinal RECD core |
+| [`systemictau`](https://pypi.org/project/systemictau/) | Full Systemic Tau library (τ_s, gate RECD, studio) — optional `[nested]` extra |
+| [`systemictau-web`](https://github.com/johelpadilla/systemictau-web) | Streamlit app; depends on this package |
+| [`excess3`](https://github.com/johelpadilla/excess3) | Methods + intro ES + primer (specification) |
+| [`cctp-sddb-systemic-tau`](https://github.com/johelpadilla/cctp-sddb-systemic-tau) | Cardiac VF pilot |
+| This package | Lightweight, installable nested-time / excess³ core |
 
 ## Citation
 
-If you use this software, please cite the CCTP/SDDB pilot archive:
+If you use excess³ / Level-3 from this package, cite the **methods** preprint (canonical specification):
 
-> Padilla-Villanueva, J. (2026). *CCTP/SDDB: Systemic Tau and ordinal RECD before spontaneous ventricular fibrillation* (v1.0.1). Zenodo. https://doi.org/10.5281/zenodo.21270699
+> Padilla-Villanueva, J. (2026). *excess³: A Pre-Specified Continuous Proxy for Order-3 Synergistic Surplus* (methods). Zenodo. https://doi.org/10.5281/zenodo.21385937
 
-And the theoretical nested-time / RECD framework as appropriate for your venue.
+Software / related stack:
+
+> Padilla-Villanueva, J. (2026). Systemic Tau software archive. Zenodo. https://doi.org/10.5281/zenodo.20576241
+
+CCTP/SDDB pilot:
+
+> Padilla-Villanueva, J. (2026). *CCTP/SDDB: Systemic Tau and ordinal RECD before spontaneous ventricular fibrillation* (v1.0.1). Zenodo. https://doi.org/10.5281/zenodo.21270699
 
 ```bibtex
 @software{padilla_nested_recd_2026,
   author  = {Padilla-Villanueva, Johel},
-  title   = {nested-recd: Nested ordinal RECD levels},
+  title   = {nested-recd: Nested ordinal RECD levels and continuous excess³},
   year    = {2026},
   url     = {https://github.com/johelpadilla/nested-recd},
-  version = {0.1.0}
+  version = {0.2.0}
 }
 ```
 

nested_recd-0.2.0/README.md

@@ -0,0 +1,162 @@
+# nested-recd
+
+[![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.
+
+This is the **canonical Level-3 software** for the Systemic Tau / RECD stack (cardiac CCTP/SDDB pilot, excess³ methods preprint, Academy Learning Tau).
+
+## Install
+
+```bash
+pip install nested-recd
+```
+
+From source (development):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## excess³ contract (methods)
+
+Canonical specification: Padilla-Villanueva (2026), *excess³: A Pre-Specified Continuous Proxy…*  
+DOI: [10.5281/zenodo.21385937](https://doi.org/10.5281/zenodo.21385937) · repo: [github.com/johelpadilla/excess3](https://github.com/johelpadilla/excess3)
+
+| Rule | Software |
+|------|----------|
+| `excess3 = 0.6·Syn + 0.4·Surp` | `ALPHA_SYN`, `ALPHA_SURP` (fixed a priori) |
+| Continuous primary | `out["excess3"]` / `compute_phi3_excess` |
+| Φ₃ secondary | binary ticks of excess3 vs `theta3` |
+| Null on full contrast | `surrogate_pvalue_delta_excess3` (phase-shuffle / permute on `\|Δ\|`) |
+| Proxy ≠ full PID | documented; no complete Williams–Beer atom claimed |
+| Parallel nesting | Φ₁, Φ₂, excess³ computed without hard Boolean ascent |
+
+Defaults: `m=3`, delay `1`, window `13`, `theta3=0.10` (software); cardio-like reference `DEFAULT_THETA3_CARDIO=0.08`.
+
+## Quick start
+
+```python
+import numpy as np
+from nested_recd import compute_recd_from_conjunctions, ALPHA_SYN, ALPHA_SURP
+
+rng = np.random.default_rng(0)
+X = rng.normal(size=(800, 3)).cumsum(axis=0)
+
+out = compute_recd_from_conjunctions(X, m=3, d=4, theta3=0.10)
+
+print("mean excess³ (primary):", float(np.nanmean(out["excess3"])))
+print("Φ3 active fraction:", float(np.nanmean(out["phi3"] > 0)))
+print("weights:", out["params"]["alpha_syn"], out["params"]["alpha_surp"])
+print("final T_recd:", float(out["T_recd"][-1]))
+```
+
+### Continuous excess³ only
+
+```python
+from nested_recd import generate_multivariate_symbols, compute_phi3_excess
+
+S = generate_multivariate_symbols(X, m=3)
+phi3, excess3 = compute_phi3_excess(S, window=13, theta=0.10, stride=1)
+```
+
+### Surrogate p-value on |Δ excess3|
+
+```python
+from nested_recd import surrogate_pvalue_delta_excess3
+
+res = surrogate_pvalue_delta_excess3(X, split=400, n_surr=99, method="phase", seed=0)
+print(res["delta_obs"], res["p_value"])
+```
+
+### Optional τ_s for λ regime weights
+
+```python
+out = compute_recd_from_conjunctions(X, tau_s=tau_s)
+# or
+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|`.
+
+## What it computes
+
+| Symbol | Meaning |
+|--------|---------|
+| **Φ₁** | 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) |
+| **Φ₃** | Binary ticks of excess³ above `theta3` (**secondary**) |
+| **λ** | Chaos / reorganization intensity (from `τ_s` or `lam_override`) |
+| **α(λ)** | Level weights: α₁ decays with λ; α₂, α₃ grow with λ |
+| **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` (legacy clock; binary Φ₃) |
+| **T_recd** | Cumulative sum of ΔRECD |
+
+Ordinal symbols use Bandt–Pompe patterns (`m=3` by default).
+
+## Surrogates
+
+```python
+from nested_recd import phase_shuffle_independent, random_permutation_independent
+
+X_null = phase_shuffle_independent(X, seed=42)
+X_perm = random_permutation_independent(X, seed=42)
+```
+
+## API surface
+
+```python
+from nested_recd import (
+    ALPHA_SYN, ALPHA_SURP,
+    DEFAULT_THETA3, DEFAULT_THETA3_CARDIO,
+    compute_recd_from_conjunctions,
+    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_weighted_contributions, high_level3_rate,
+    generate_multivariate_symbols,
+    phase_shuffle_independent, generate_surrogate_ensemble,
+)
+```
+
+## Relation to other projects
+
+| Project | Role |
+|---------|------|
+| [`systemictau`](https://pypi.org/project/systemictau/) | Full Systemic Tau library (τ_s, gate RECD, studio) — optional `[nested]` extra |
+| [`systemictau-web`](https://github.com/johelpadilla/systemictau-web) | Streamlit app; depends on this package |
+| [`excess3`](https://github.com/johelpadilla/excess3) | Methods + intro ES + primer (specification) |
+| [`cctp-sddb-systemic-tau`](https://github.com/johelpadilla/cctp-sddb-systemic-tau) | Cardiac VF pilot |
+| This package | Lightweight, installable nested-time / excess³ core |
+
+## Citation
+
+If you use excess³ / Level-3 from this package, cite the **methods** preprint (canonical specification):
+
+> Padilla-Villanueva, J. (2026). *excess³: A Pre-Specified Continuous Proxy for Order-3 Synergistic Surplus* (methods). Zenodo. https://doi.org/10.5281/zenodo.21385937
+
+Software / related stack:
+
+> Padilla-Villanueva, J. (2026). Systemic Tau software archive. Zenodo. https://doi.org/10.5281/zenodo.20576241
+
+CCTP/SDDB pilot:
+
+> Padilla-Villanueva, J. (2026). *CCTP/SDDB: Systemic Tau and ordinal RECD before spontaneous ventricular fibrillation* (v1.0.1). Zenodo. https://doi.org/10.5281/zenodo.21270699
+
+```bibtex
+@software{padilla_nested_recd_2026,
+  author  = {Padilla-Villanueva, Johel},
+  title   = {nested-recd: Nested ordinal RECD levels and continuous excess³},
+  year    = {2026},
+  url     = {https://github.com/johelpadilla/nested-recd},
+  version = {0.2.0}
+}
+```
+
+## License
+
+MIT © 2026 Johel Padilla-Villanueva  
+ORCID: [0000-0002-5797-6931](https://orcid.org/0000-0002-5797-6931)

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

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nested-recd"
-version = "0.1.0"
-description = "Nested ordinal RECD: Φ1–Φ3 conjunction levels and λ-weighted Discrete Extramental Clock"
+version = "0.2.0"
+description = "Nested ordinal RECD: Φ1–Φ3, continuous excess³ (primary Level-3), and λ-weighted Discrete Extramental Clock"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"

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

@@ -2,8 +2,8 @@
 nested-recd
 ===========
 
-Nested ordinal RECD: Φ₁ / Φ₂ / Φ₃ conjunction levels and λ-weighted
-Discrete Extramental Clock accumulation.
+Nested ordinal RECD: Φ₁ / Φ₂ / Φ₃ conjunction levels, continuous excess³
+(primary Level-3 readout), and λ-weighted Discrete Extramental Clock.
 
 Quick start
 -----------
@@ -11,7 +11,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)
->>> out["T_recd"][-1]
+>>> float(np.nanmean(out["excess3"]))  # continuous primary Level-3 score
 """
 
 from nested_recd.ordinal_levels import (
@@ -19,13 +19,21 @@ from nested_recd.ordinal_levels import (
     DEFAULT_DELAY,
     DEFAULT_D_PERSIST,
     DEFAULT_WINDOW_TAU,
+    DEFAULT_WINDOW,
     DEFAULT_THETA_CHAOS,
     DEFAULT_THETA3,
+    DEFAULT_THETA3_CARDIO,
     DELTA_FEIGENBAUM,
+    ALPHA_SYN,
+    ALPHA_SURP,
     generate_multivariate_symbols,
     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,
@@ -43,7 +51,7 @@ from nested_recd.surrogates import (
     compute_null_distribution,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "__version__",
@@ -51,13 +59,21 @@ __all__ = [
     "DEFAULT_DELAY",
     "DEFAULT_D_PERSIST",
     "DEFAULT_WINDOW_TAU",
+    "DEFAULT_WINDOW",
     "DEFAULT_THETA_CHAOS",
     "DEFAULT_THETA3",
+    "DEFAULT_THETA3_CARDIO",
     "DELTA_FEIGENBAUM",
+    "ALPHA_SYN",
+    "ALPHA_SURP",
     "generate_multivariate_symbols",
     "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",

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

@@ -19,14 +19,20 @@ import numpy as np
 from typing import Dict, Tuple, Optional
 import warnings
 
-# Defaults quirúrgicos (ver diseño)
+# Defaults quirúrgicos (ver diseño + excess³ methods contract)
 DEFAULT_M = 3
 DEFAULT_DELAY = 1
 DEFAULT_D_PERSIST = 4
 DEFAULT_WINDOW_TAU = 13
+DEFAULT_WINDOW = DEFAULT_WINDOW_TAU  # alias (methods paper)
 DEFAULT_THETA_CHAOS = 0.41
 DELTA_FEIGENBAUM = 4.6692016091
-DEFAULT_THETA3 = 0.10  # Ajustado a la baja tras piloto (más sensible sin perder especificidad)
+DEFAULT_THETA3 = 0.10  # software default
+DEFAULT_THETA3_CARDIO = 0.08  # methods cardio-like reference
+
+# excess³ = α_Syn · Syn + α_Surp · Surp  (fixed a priori; never fit on target data)
+ALPHA_SYN = 0.6
+ALPHA_SURP = 0.4
 
 def _gen_ordinal(x: np.ndarray, m: int = DEFAULT_M, delay: int = DEFAULT_DELAY) -> np.ndarray:
     """Bandt–Pompe ordinal symbols (pure NumPy, no numba required)."""
@@ -234,77 +240,248 @@ def _joint_entropy_and_marginals(S_window: np.ndarray) -> Tuple[float, float, fl
     return H_joint, H_marg_sum, synergy_proxy
 
 
-def compute_phi3(
+def compute_excess3_window(
+    win: np.ndarray,
+    use_surprise: bool = True,
+    alpha_syn: float = ALPHA_SYN,
+    alpha_surp: float = ALPHA_SURP,
+) -> float:
+    """
+    excess³ score on a single window of joint ordinal symbols (shape (w, N)).
+
+    Canonical hybrid proxy (methods contract):
+        excess3 = alpha_syn · Syn + alpha_surp · Surp
+    with default weights (0.6, 0.4) fixed a priori — never optimised on the
+    scientific dataset under test.
+
+    Syn: synergistic residual multiinformation proxy
+         max(0, TC − (N−1)·MĪ_pair).
+    Surp: observed-vs-independence joint surprise (frequency-weighted log-ratio).
+
+    This is a **proxy**, not a complete PID synergy atom.
+    """
+    win = np.asarray(win)
+    if win.ndim != 2 or win.shape[0] == 0:
+        return float("nan")
+    if win.shape[1] < 2:
+        return 0.0
+
+    _, _, syn = _joint_entropy_and_marginals(win)
+    if not use_surprise:
+        return float(syn)
+
+    from collections import Counter
+
+    joint_tuples = [tuple(int(v) for v in row) for row in win]
+    counter = Counter(joint_tuples)
+    T_win = len(joint_tuples)
+    surprises = []
+    for u, cnt in counter.items():
+        p_indep = 1.0
+        for k, val in enumerate(u):
+            p_indep *= max(float(np.mean(win[:, k] == val)), 1e-9)
+        p_obs = cnt / T_win
+        ratio = p_obs / max(p_indep, 1e-9)
+        excess_log = max(0.0, np.log2(ratio)) if ratio > 1 else 0.0
+        surprises.append(excess_log * (cnt / T_win))
+    joint_surprise = float(np.sum(surprises)) if surprises else 0.0
+    return float(alpha_syn * syn + alpha_surp * joint_surprise)
+
+
+def compute_phi3_excess(
     S: np.ndarray,
-    window: int = 13,
+    window: int = DEFAULT_WINDOW_TAU,
     theta: float = DEFAULT_THETA3,
     stride: int = 1,
-    use_surprise: bool = True
+    use_surprise: bool = True,
+    alpha_syn: float = ALPHA_SYN,
+    alpha_surp: float = ALPHA_SURP,
+    fill: bool = False,
 ) -> Tuple[np.ndarray, np.ndarray]:
     """
-    Φ₃(t): Score de sinergia / irreductibilidad (proxy mejorado post-piloto).
-
-    Dos componentes:
-    - excess (total correlation - pairwise) del método anterior.
-    - joint_surprise: promedio de "sorpresa" de las tuplas observadas
-      vs modelo de independencia ( -log2(P_indep) ponderado por frecuencia observada ).
-
-    Si use_surprise=True, el score combina ambos. Esto hace el proxy
-    más sensible a configuraciones conjuntas "improbables bajo independencia"
-    que no se explican por marginales (más cerca de irreductibilidad).
-
-    Retorna (phi3_binary, excess_raw)  -- excess ahora es el score combinado.
+    Continuous excess³ (primary) and binary Φ₃ (secondary) on symbol matrix S.
+
+    Returns
+    -------
+    phi3 : ndarray
+        Binary ticks: 1 if excess3 > theta else 0 (NaN before first full window).
+    excess3 : ndarray
+        Continuous hybrid score (primary Level-3 readout).
+
+    Parameters
+    ----------
+    fill : bool
+        If True, forward-fill NaNs after the first finite score (plot convenience).
+        Default False preserves sparse stride semantics.
     """
+    S = np.asarray(S)
     T_eff, N = S.shape
     phi3 = np.full(T_eff, np.nan)
     excess = np.full(T_eff, np.nan)
 
-    if T_eff < window:
+    if T_eff < window or N < 2:
         return phi3, excess
 
     for t in range(window - 1, T_eff, stride):
-        win = S[t - window + 1 : t + 1]
-        T_win = len(win)
-
-        # Componente 1: exceso sinérgico previo (total corr - pairwise)
-        _, _, syn = _joint_entropy_and_marginals(win)
-
-        # Componente 2: Joint surprise (más directo para "irreductible")
-        if use_surprise:
-            from collections import Counter
-            joint_tuples = [tuple(int(v) for v in row) for row in win]  # asegurar python ints
-            counter = Counter(joint_tuples)
-            uniq = list(counter.keys())
-            counts = np.array(list(counter.values()))
-            T_win = len(joint_tuples)
-
-            # P_indep por tupla + "exceso de ocurrencia" (log ratio observado / independencia)
-            # Esto captura configuraciones que ocurren MÁS de lo esperado por marginales → más "irreducible"
-            surprises = []
-            for u, cnt in zip(uniq, counts):
-                p_indep = 1.0
-                for k, val in enumerate(u):
-                    pk = np.mean([row[k] == val for row in joint_tuples])
-                    p_indep *= max(pk, 1e-9)
-                p_obs = cnt / T_win
-                # log-ratio: >0 cuando ocurre más de lo esperado por independencia
-                ratio = p_obs / max(p_indep, 1e-9)
-                excess_log = max(0.0, np.log2(ratio)) if ratio > 1 else 0.0
-                weight = cnt / T_win
-                surprises.append(excess_log * weight)
-
-            joint_surprise = float(np.sum(surprises)) if surprises else 0.0
-            # Combinar (syn ya es en bits-ish, surprise también)
-            combined = 0.6 * syn + 0.4 * joint_surprise   # pesos heurísticos pero transparentes
-        else:
-            combined = syn
-
-        excess[t] = combined
-        phi3[t] = 1.0 if combined > theta else 0.0
+        score = compute_excess3_window(
+            S[t - window + 1 : t + 1],
+            use_surprise=use_surprise,
+            alpha_syn=alpha_syn,
+            alpha_surp=alpha_surp,
+        )
+        excess[t] = score
+        phi3[t] = 1.0 if score > theta else 0.0
+
+    if fill:
+        last = np.nan
+        for t in range(T_eff):
+            if np.isfinite(excess[t]):
+                last = excess[t]
+            elif np.isfinite(last):
+                excess[t] = last
+                phi3[t] = 1.0 if last > theta else 0.0
 
     return phi3, excess
 
 
+def compute_phi3(
+    S: np.ndarray,
+    window: int = 13,
+    theta: float = DEFAULT_THETA3,
+    stride: int = 1,
+    use_surprise: bool = True,
+    alpha_syn: float = ALPHA_SYN,
+    alpha_surp: float = ALPHA_SURP,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Φ₃(t) binary + continuous excess³ series.
+
+    Continuous excess³ is the **primary** Level-3 magnitude (methods contract);
+    Φ₃ only counts threshold crossings. Weights default to (ALPHA_SYN, ALPHA_SURP).
+
+    Returns (phi3_binary, excess3_continuous).
+    """
+    return compute_phi3_excess(
+        S,
+        window=window,
+        theta=theta,
+        stride=stride,
+        use_surprise=use_surprise,
+        alpha_syn=alpha_syn,
+        alpha_surp=alpha_surp,
+        fill=False,
+    )
+
+
+def mean_excess_pre_post(
+    excess3: np.ndarray,
+    split: int,
+) -> Tuple[float, float, float]:
+    """
+    Mean continuous excess³ before / after a split index, and Δ = post − pre.
+
+    ``split`` is an index into the excess3 array (same time base as returned by
+    compute_recd_from_conjunctions / compute_phi3_excess).
+    """
+    excess3 = np.asarray(excess3, dtype=float)
+    if split <= 0 or split >= len(excess3):
+        raise ValueError(f"split={split} out of range for length {len(excess3)}")
+    pre = float(np.nanmean(excess3[:split]))
+    post = float(np.nanmean(excess3[split:]))
+    return pre, post, post - pre
+
+
+def surrogate_pvalue_delta_excess3(
+    X: np.ndarray,
+    split: int,
+    n_surr: int = 199,
+    method: str = "phase",
+    seed: int = 0,
+    m: int = DEFAULT_M,
+    window: int = DEFAULT_WINDOW_TAU,
+    theta3: float = DEFAULT_THETA3,
+    stride: int = 1,
+    delay: int = DEFAULT_DELAY,
+    alpha_syn: float = ALPHA_SYN,
+    alpha_surp: float = ALPHA_SURP,
+) -> Dict[str, float]:
+    """
+    Two-sided surrogate p-value for |Δ excess3| under independent phase-shuffle
+    (default) or column permutation — methods-paper null protocol.
+
+    Inference is on the **full contrast** |Δ|, not mean-vs-mean of means alone.
+
+    Parameters
+    ----------
+    X : (T, N) array
+        Multivariate series (raw values; symbols computed inside).
+    split : int
+        Split index on the **raw** time axis; mapped to symbol time via
+        embedding length (m, delay).
+    method : {"phase", "permute"}
+        "phase" uses per-column IAAFT / phase-shuffle; "permute" shuffles time.
+    """
+    from nested_recd.surrogates import (
+        phase_shuffle_independent,
+        random_permutation_independent,
+    )
+
+    X = np.asarray(X)
+    if X.ndim != 2:
+        raise ValueError("X must be shape (T, N)")
+
+    def _delta_on(arr: np.ndarray) -> float:
+        S = generate_multivariate_symbols(arr, m=m, delay=delay)
+        if len(S) == 0:
+            return float("nan")
+        # Map split from raw time to symbol index (conservative)
+        emb = (m - 1) * delay
+        split_s = int(np.clip(split - emb, 1, len(S) - 1))
+        _, excess = compute_phi3_excess(
+            S,
+            window=window,
+            theta=theta3,
+            stride=stride,
+            alpha_syn=alpha_syn,
+            alpha_surp=alpha_surp,
+        )
+        _, _, d = mean_excess_pre_post(excess, split_s)
+        return float(d)
+
+    obs = _delta_on(X)
+    null = []
+    rng = np.random.default_rng(seed)
+    for _ in range(n_surr):
+        s = int(rng.integers(0, 2**31 - 1))
+        if method == "permute":
+            Xs = random_permutation_independent(X, seed=s)
+        else:
+            Xs = phase_shuffle_independent(X, seed=s)
+        null.append(_delta_on(Xs))
+    null = np.asarray(null, dtype=float)
+    null = null[np.isfinite(null)]
+    if not np.isfinite(obs) or len(null) == 0:
+        return {
+            "delta_obs": float(obs) if np.isfinite(obs) else float("nan"),
+            "abs_delta_obs": float("nan"),
+            "p_value": float("nan"),
+            "n_surr": float(len(null)),
+            "method": method,
+        }
+    abs_obs = abs(obs)
+    # Add-one smoothing: (1 + #{|null| >= |obs|}) / (1 + n)
+    p = (1.0 + float(np.sum(np.abs(null) >= abs_obs))) / (1.0 + len(null))
+    return {
+        "delta_obs": float(obs),
+        "abs_delta_obs": float(abs_obs),
+        "p_value": float(p),
+        "n_surr": float(len(null)),
+        "method": method,
+        "null_mean_abs": float(np.mean(np.abs(null))),
+        "null_std_abs": float(np.std(np.abs(null))),
+    }
+
+
 # ============================================================
 # λ(t) y pesos α(λ)
 # ============================================================
@@ -381,27 +558,40 @@ def compute_recd_from_conjunctions(
     theta3: float = DEFAULT_THETA3,
     window_tau: int = DEFAULT_WINDOW_TAU,
     lam_override: Optional[np.ndarray] = None,
+    stride: int = 1,
+    alpha_syn: float = ALPHA_SYN,
+    alpha_surp: float = ALPHA_SURP,
     **alpha_kwargs
 ) -> Dict[str, np.ndarray]:
     """
-    Pipeline quirúrgico completo:
-    - Símbolos ordinales
-    - Φ1, Φ2, Φ3
-    - λ y α(λ)
-    - ΔRECD_new y T_new
-
-    Si tau_s no se provee, se espera que el caller lo calcule con la infraestructura existente.
-
-    lam_override: si se provee (escalar o array), se usa directamente para calcular α(λ)
-                  en lugar de derivar λ de tau_s. Útil para Opción 1 (ground-truth r)
-                  o alphas fijos, para aislar el efecto de régimen sobre Nivel 3.
+    Full nested ordinal RECD pipeline:
+    - Bandt–Pompe symbols
+    - Φ1, Φ2, Φ3 (binary) + continuous excess³ (primary Level-3 readout)
+    - λ and α(λ) regime weights
+    - ΔRECD and cumulative T_recd
+
+    Level-3 contract (excess³ methods):
+    - Continuous ``excess3`` is the primary magnitude for order-3 claims.
+    - ``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
+      treat ``delta_recd`` alone as the Level-3 scientific readout.
+
+    If tau_s is omitted, λ=0 (warning). Use ``lam_override`` for regime ground truth.
     """
     S = generate_multivariate_symbols(X, m=m)
     T_eff = S.shape[0]
 
     phi1 = compute_phi1(S)
     phi2 = compute_phi2(S, d=d)
-    phi3, excess3 = compute_phi3(S, window=window_tau, theta=theta3)
+    phi3, excess3 = compute_phi3(
+        S,
+        window=window_tau,
+        theta=theta3,
+        stride=stride,
+        alpha_syn=alpha_syn,
+        alpha_surp=alpha_surp,
+    )
 
     # Determinar λ: override > tau-derived > zero
     if lam_override is not None:
@@ -425,6 +615,7 @@ def compute_recd_from_conjunctions(
     phi3_safe = np.nan_to_num(phi3, nan=0.0)
     excess3_safe = np.nan_to_num(excess3, nan=0.0)
 
+    # Legacy RECD clock: binary Φ₃ in the α-weighted sum (back-compat)
     delta_recd = a1 * phi1 + a2 * phi2 + a3 * phi3_safe
     T_recd = np.nancumsum(delta_recd)
 
@@ -441,9 +632,17 @@ def compute_recd_from_conjunctions(
         "delta_recd": delta_recd,
         "T_recd": T_recd,
         "params": {
-            "m": m, "d": d, "theta3": theta3,
-            "window_tau": window_tau, **alpha_kwargs
-        }
+            "m": m,
+            "d": d,
+            "theta3": theta3,
+            "window_tau": window_tau,
+            "stride": stride,
+            "alpha_syn": alpha_syn,
+            "alpha_surp": alpha_surp,
+            "level3_primary": "excess3",
+            "level3_secondary": "phi3",
+            **alpha_kwargs,
+        },
     }
 
 

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: nested-recd
-Version: 0.1.0
-Summary: Nested ordinal RECD: Φ1–Φ3 conjunction levels and λ-weighted Discrete Extramental Clock
+Version: 0.2.0
+Summary: Nested ordinal RECD: Φ1–Φ3, continuous excess³ (primary Level-3), 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
@@ -39,9 +39,9 @@ Dynamic: license-file
 [![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 (Φ₁, Φ₂, Φ₃) and λ-weighted Discrete Extramental Clock (RECD) accumulation.
+**Nested ordinal RECD** — pure-NumPy implementation of nested ordinal conjunction levels (Φ₁, Φ₂, Φ₃), the continuous **excess³** Level-3 proxy, and λ-weighted Discrete Extramental Clock (RECD) accumulation.
 
-This is the standalone library behind the nested-time structure used in the CCTP/SDDB cardiac pilot and the experimental design in *Conversación de la naturaleza del tiempo*.
+This is the **canonical Level-3 software** for the Systemic Tau / RECD stack (cardiac CCTP/SDDB pilot, excess³ methods preprint, Academy Learning Tau).
 
 ## Install
 
@@ -49,56 +49,85 @@ This is the standalone library behind the nested-time structure used in the CCTP
 pip install nested-recd
 ```
 
-From source:
+From source (development):
 
 ```bash
-pip install git+https://github.com/johelpadilla/nested-recd.git
+pip install -e ".[dev]"
 ```
 
+## excess³ contract (methods)
+
+Canonical specification: Padilla-Villanueva (2026), *excess³: A Pre-Specified Continuous Proxy…*  
+DOI: [10.5281/zenodo.21385937](https://doi.org/10.5281/zenodo.21385937) · repo: [github.com/johelpadilla/excess3](https://github.com/johelpadilla/excess3)
+
+| Rule | Software |
+|------|----------|
+| `excess3 = 0.6·Syn + 0.4·Surp` | `ALPHA_SYN`, `ALPHA_SURP` (fixed a priori) |
+| Continuous primary | `out["excess3"]` / `compute_phi3_excess` |
+| Φ₃ secondary | binary ticks of excess3 vs `theta3` |
+| Null on full contrast | `surrogate_pvalue_delta_excess3` (phase-shuffle / permute on `\|Δ\|`) |
+| Proxy ≠ full PID | documented; no complete Williams–Beer atom claimed |
+| Parallel nesting | Φ₁, Φ₂, excess³ computed without hard Boolean ascent |
+
+Defaults: `m=3`, delay `1`, window `13`, `theta3=0.10` (software); cardio-like reference `DEFAULT_THETA3_CARDIO=0.08`.
+
 ## Quick start
 
 ```python
 import numpy as np
-from nested_recd import compute_recd_from_conjunctions, compute_weighted_contributions
+from nested_recd import compute_recd_from_conjunctions, ALPHA_SYN, ALPHA_SURP
 
-# Multivariate series: shape (T, N)
 rng = np.random.default_rng(0)
 X = rng.normal(size=(800, 3)).cumsum(axis=0)
 
 out = compute_recd_from_conjunctions(X, m=3, d=4, theta3=0.10)
 
-print("mean Φ1:", float(np.nanmean(out["phi1"])))
-print("mean Φ2:", float(np.nanmean(out["phi2"])))
+print("mean excess³ (primary):", float(np.nanmean(out["excess3"])))
 print("Φ3 active fraction:", float(np.nanmean(out["phi3"] > 0)))
+print("weights:", out["params"]["alpha_syn"], out["params"]["alpha_surp"])
 print("final T_recd:", float(out["T_recd"][-1]))
+```
 
-w = compute_weighted_contributions(out)
-print("frac level-3 contribution:", w["frac_contrib3"])
+### Continuous excess³ only
+
+```python
+from nested_recd import generate_multivariate_symbols, compute_phi3_excess
+
+S = generate_multivariate_symbols(X, m=3)
+phi3, excess3 = compute_phi3_excess(S, window=13, theta=0.10, stride=1)
 ```
 
-Optional: supply a Systemic Tau series `tau_s` (aligned in time) so that λ is derived empirically:
+### Surrogate p-value on |Δ excess3|
 
 ```python
-out = compute_recd_from_conjunctions(X, tau_s=tau_s)
+from nested_recd import surrogate_pvalue_delta_excess3
+
+res = surrogate_pvalue_delta_excess3(X, split=400, n_surr=99, method="phase", seed=0)
+print(res["delta_obs"], res["p_value"])
 ```
 
-Or fix the regime weight with a scalar / array override:
+### Optional τ_s for λ regime weights
 
 ```python
+out = compute_recd_from_conjunctions(X, tau_s=tau_s)
+# or
 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|`.
+
 ## What it computes
 
 | Symbol | Meaning |
 |--------|---------|
 | **Φ₁** | Co-occurrence of identical ordinal symbols across variable pairs |
 | **Φ₂** | Persistence of pairwise ordinal relations over lag `d` |
-| **Φ₃** | Higher-order synergy proxy (total-correlation excess + joint surprise) |
+| **excess³** | Continuous hybrid: `0.6·Syn + 0.4·Surp` (**primary** Level-3) |
+| **Φ₃** | Binary ticks of excess³ above `theta3` (**secondary**) |
 | **λ** | Chaos / reorganization intensity (from `τ_s` or `lam_override`) |
 | **α(λ)** | Level weights: α₁ decays with λ; α₂, α₃ grow with λ |
-| **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` |
-| **T_recd** | Cumulative sum of ΔRECD (nested-time clock) |
+| **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` (legacy clock; binary Φ₃) |
+| **T_recd** | Cumulative sum of ΔRECD |
 
 Ordinal symbols use Bandt–Pompe patterns (`m=3` by default).
 
@@ -107,7 +136,7 @@ Ordinal symbols use Bandt–Pompe patterns (`m=3` by default).
 ```python
 from nested_recd import phase_shuffle_independent, random_permutation_independent
 
-X_null = phase_shuffle_independent(X, seed=42)   # IAAFT per column
+X_null = phase_shuffle_independent(X, seed=42)
 X_perm = random_permutation_independent(X, seed=42)
 ```
 
@@ -115,8 +144,12 @@ X_perm = random_permutation_independent(X, seed=42)
 
 ```python
 from nested_recd import (
+    ALPHA_SYN, ALPHA_SURP,
+    DEFAULT_THETA3, DEFAULT_THETA3_CARDIO,
     compute_recd_from_conjunctions,
     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_weighted_contributions, high_level3_rate,
     generate_multivariate_symbols,
@@ -128,25 +161,33 @@ from nested_recd import (
 
 | Project | Role |
 |---------|------|
-| [`systemictau`](https://pypi.org/project/systemictau/) | Full Systemic Tau library (τ_s, platform, studio) |
-| [`cctp-sddb-systemic-tau`](https://github.com/johelpadilla/cctp-sddb-systemic-tau) | Cardiac VF pilot using this nested RECD pipeline |
-| This package | Lightweight, installable nested-time / ordinal RECD core |
+| [`systemictau`](https://pypi.org/project/systemictau/) | Full Systemic Tau library (τ_s, gate RECD, studio) — optional `[nested]` extra |
+| [`systemictau-web`](https://github.com/johelpadilla/systemictau-web) | Streamlit app; depends on this package |
+| [`excess3`](https://github.com/johelpadilla/excess3) | Methods + intro ES + primer (specification) |
+| [`cctp-sddb-systemic-tau`](https://github.com/johelpadilla/cctp-sddb-systemic-tau) | Cardiac VF pilot |
+| This package | Lightweight, installable nested-time / excess³ core |
 
 ## Citation
 
-If you use this software, please cite the CCTP/SDDB pilot archive:
+If you use excess³ / Level-3 from this package, cite the **methods** preprint (canonical specification):
 
-> Padilla-Villanueva, J. (2026). *CCTP/SDDB: Systemic Tau and ordinal RECD before spontaneous ventricular fibrillation* (v1.0.1). Zenodo. https://doi.org/10.5281/zenodo.21270699
+> Padilla-Villanueva, J. (2026). *excess³: A Pre-Specified Continuous Proxy for Order-3 Synergistic Surplus* (methods). Zenodo. https://doi.org/10.5281/zenodo.21385937
 
-And the theoretical nested-time / RECD framework as appropriate for your venue.
+Software / related stack:
+
+> Padilla-Villanueva, J. (2026). Systemic Tau software archive. Zenodo. https://doi.org/10.5281/zenodo.20576241
+
+CCTP/SDDB pilot:
+
+> Padilla-Villanueva, J. (2026). *CCTP/SDDB: Systemic Tau and ordinal RECD before spontaneous ventricular fibrillation* (v1.0.1). Zenodo. https://doi.org/10.5281/zenodo.21270699
 
 ```bibtex
 @software{padilla_nested_recd_2026,
   author  = {Padilla-Villanueva, Johel},
-  title   = {nested-recd: Nested ordinal RECD levels},
+  title   = {nested-recd: Nested ordinal RECD levels and continuous excess³},
   year    = {2026},
   url     = {https://github.com/johelpadilla/nested-recd},
-  version = {0.1.0}
+  version = {0.2.0}
 }
 ```
 

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

@@ -1,21 +1,38 @@
-"""Smoke and invariant tests for nested-recd."""
+"""Smoke and invariant tests for nested-recd (excess³ contract)."""
 
 import numpy as np
 import pytest
 
 from nested_recd import (
     __version__,
+    ALPHA_SYN,
+    ALPHA_SURP,
+    DEFAULT_THETA3,
+    DEFAULT_THETA3_CARDIO,
     compute_recd_from_conjunctions,
     compute_phi1,
+    compute_phi3,
+    compute_phi3_excess,
+    compute_excess3_window,
     compute_weighted_contributions,
     generate_multivariate_symbols,
+    mean_excess_pre_post,
     phase_shuffle_independent,
     random_permutation_independent,
+    surrogate_pvalue_delta_excess3,
 )
 
 
 def test_version():
-    assert __version__ == "0.1.0"
+    assert __version__ == "0.2.0"
+
+
+def test_weights_a_priori():
+    assert ALPHA_SYN == 0.6
+    assert ALPHA_SURP == 0.4
+    assert abs(ALPHA_SYN + ALPHA_SURP - 1.0) < 1e-12
+    assert DEFAULT_THETA3 == 0.10
+    assert DEFAULT_THETA3_CARDIO == 0.08
 
 
 def test_pipeline_shapes_and_bounds():
@@ -26,6 +43,7 @@ def test_pipeline_shapes_and_bounds():
     T = out["phi1"].shape[0]
     assert out["phi2"].shape == (T,)
     assert out["phi3"].shape == (T,)
+    assert out["excess3"].shape == (T,)
     assert out["delta_recd"].shape == (T,)
     assert out["T_recd"].shape == (T,)
     assert out["S"].shape[1] == 3
@@ -34,7 +52,12 @@ def test_pipeline_shapes_and_bounds():
     assert np.all((out["phi2"] >= 0) & (out["phi2"] <= 1))
     assert np.nanmax(out["phi3"]) <= 1.0
     assert np.nanmin(out["phi3"]) >= 0.0 or np.isnan(np.nanmin(out["phi3"]))
-    assert np.all(np.diff(out["T_recd"]) >= -1e-12)  # cumulative non-decreasing (nan-safe path)
+    assert np.all(np.diff(out["T_recd"]) >= -1e-12)
+
+    # Contract: continuous primary declared in params
+    assert out["params"]["level3_primary"] == "excess3"
+    assert out["params"]["alpha_syn"] == ALPHA_SYN
+    assert out["params"]["alpha_surp"] == ALPHA_SURP
 
 
 def test_identical_series_high_phi1():
@@ -85,3 +108,46 @@ def test_phi1_single_variable_zeros():
     S = np.zeros((50, 1), dtype=int)
     phi1 = compute_phi1(S)
     assert np.all(phi1 == 0)
+
+
+def test_phi3_delegates_to_phi3_excess():
+    rng = np.random.default_rng(6)
+    S = generate_multivariate_symbols(rng.normal(size=(120, 3)).cumsum(0), m=3)
+    a = compute_phi3(S, window=13, theta=0.10)
+    b = compute_phi3_excess(S, window=13, theta=0.10)
+    np.testing.assert_allclose(a[0], b[0], equal_nan=True)
+    np.testing.assert_allclose(a[1], b[1], equal_nan=True)
+
+
+def test_excess3_window_weights():
+    rng = np.random.default_rng(7)
+    # XOR-like synergistic lock: pairs weak, triple determined
+    n = 40
+    a = rng.integers(0, 2, size=n)
+    b = rng.integers(0, 2, size=n)
+    c = a ^ b
+    win = np.column_stack([a, b, c]).astype(int)
+    score = compute_excess3_window(win)
+    assert np.isfinite(score)
+    assert score >= 0.0
+
+
+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)
+    assert pre == 0.0
+    assert post == 1.0
+    assert delta == 1.0
+
+
+def test_surrogate_pvalue_smoke():
+    rng = np.random.default_rng(8)
+    T = 180
+    # Independent noise: |Δ| should not be extreme
+    X = rng.normal(size=(T, 3))
+    res = surrogate_pvalue_delta_excess3(
+        X, split=T // 2, n_surr=19, method="permute", seed=1, window=11, stride=2
+    )
+    assert "p_value" in res
+    assert 0.0 <= res["p_value"] <= 1.0
+    assert res["n_surr"] >= 1

nested_recd-0.1.0/README.md

@@ -1,121 +0,0 @@
-# nested-recd
-
-[![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 (Φ₁, Φ₂, Φ₃) and λ-weighted Discrete Extramental Clock (RECD) accumulation.
-
-This is the standalone library behind the nested-time structure used in the CCTP/SDDB cardiac pilot and the experimental design in *Conversación de la naturaleza del tiempo*.
-
-## Install
-
-```bash
-pip install nested-recd
-```
-
-From source:
-
-```bash
-pip install git+https://github.com/johelpadilla/nested-recd.git
-```
-
-## Quick start
-
-```python
-import numpy as np
-from nested_recd import compute_recd_from_conjunctions, compute_weighted_contributions
-
-# Multivariate series: shape (T, N)
-rng = np.random.default_rng(0)
-X = rng.normal(size=(800, 3)).cumsum(axis=0)
-
-out = compute_recd_from_conjunctions(X, m=3, d=4, theta3=0.10)
-
-print("mean Φ1:", float(np.nanmean(out["phi1"])))
-print("mean Φ2:", float(np.nanmean(out["phi2"])))
-print("Φ3 active fraction:", float(np.nanmean(out["phi3"] > 0)))
-print("final T_recd:", float(out["T_recd"][-1]))
-
-w = compute_weighted_contributions(out)
-print("frac level-3 contribution:", w["frac_contrib3"])
-```
-
-Optional: supply a Systemic Tau series `tau_s` (aligned in time) so that λ is derived empirically:
-
-```python
-out = compute_recd_from_conjunctions(X, tau_s=tau_s)
-```
-
-Or fix the regime weight with a scalar / array override:
-
-```python
-out = compute_recd_from_conjunctions(X, lam_override=0.5)
-```
-
-## What it computes
-
-| Symbol | Meaning |
-|--------|---------|
-| **Φ₁** | Co-occurrence of identical ordinal symbols across variable pairs |
-| **Φ₂** | Persistence of pairwise ordinal relations over lag `d` |
-| **Φ₃** | Higher-order synergy proxy (total-correlation excess + joint surprise) |
-| **λ** | Chaos / reorganization intensity (from `τ_s` or `lam_override`) |
-| **α(λ)** | Level weights: α₁ decays with λ; α₂, α₃ grow with λ |
-| **ΔRECD** | `α₁Φ₁ + α₂Φ₂ + α₃Φ₃` |
-| **T_recd** | Cumulative sum of ΔRECD (nested-time clock) |
-
-Ordinal symbols use Bandt–Pompe patterns (`m=3` by default).
-
-## Surrogates
-
-```python
-from nested_recd import phase_shuffle_independent, random_permutation_independent
-
-X_null = phase_shuffle_independent(X, seed=42)   # IAAFT per column
-X_perm = random_permutation_independent(X, seed=42)
-```
-
-## API surface
-
-```python
-from nested_recd import (
-    compute_recd_from_conjunctions,
-    compute_phi1, compute_phi2, compute_phi3,
-    compute_lambda, alpha_weights, regime_lambda_proxy,
-    compute_weighted_contributions, high_level3_rate,
-    generate_multivariate_symbols,
-    phase_shuffle_independent, generate_surrogate_ensemble,
-)
-```
-
-## Relation to other projects
-
-| Project | Role |
-|---------|------|
-| [`systemictau`](https://pypi.org/project/systemictau/) | Full Systemic Tau library (τ_s, platform, studio) |
-| [`cctp-sddb-systemic-tau`](https://github.com/johelpadilla/cctp-sddb-systemic-tau) | Cardiac VF pilot using this nested RECD pipeline |
-| This package | Lightweight, installable nested-time / ordinal RECD core |
-
-## Citation
-
-If you use this software, please cite the CCTP/SDDB pilot archive:
-
-> Padilla-Villanueva, J. (2026). *CCTP/SDDB: Systemic Tau and ordinal RECD before spontaneous ventricular fibrillation* (v1.0.1). Zenodo. https://doi.org/10.5281/zenodo.21270699
-
-And the theoretical nested-time / RECD framework as appropriate for your venue.
-
-```bibtex
-@software{padilla_nested_recd_2026,
-  author  = {Padilla-Villanueva, Johel},
-  title   = {nested-recd: Nested ordinal RECD levels},
-  year    = {2026},
-  url     = {https://github.com/johelpadilla/nested-recd},
-  version = {0.1.0}
-}
-```
-
-## License
-
-MIT © 2026 Johel Padilla-Villanueva  
-ORCID: [0000-0002-5797-6931](https://orcid.org/0000-0002-5797-6931)