Metadata-Version: 2.4
Name: phi3-recd
Version: 0.5.0
Summary: Φ₃ (excess³) → RECD clock maps: hardened A₃ gate, multiplicative gain Γ₃ (P1), dual-channel experimental P2
Author-email: Johel Padilla-Villanueva <joel.padilla2@upr.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/johelpadilla/phi3-recd
Project-URL: Repository, https://github.com/johelpadilla/phi3-recd
Project-URL: Documentation, https://github.com/johelpadilla/phi3-recd#readme
Keywords: RECD,excess3,Phi3,Systemic Tau,ordinal synergy,early-warning,discrete clock,Feigenbaum
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: ordinal
Requires-Dist: nested-recd>=0.2.0; extra == "ordinal"
Provides-Extra: plots
Requires-Dist: matplotlib>=3.7; extra == "plots"
Provides-Extra: full
Requires-Dist: nested-recd>=0.2.0; extra == "full"
Requires-Dist: matplotlib>=3.7; extra == "full"
Requires-Dist: pandas>=1.5; extra == "full"
Dynamic: license-file

# Preprint: Dynamic Integration of Level-3 Ordinal Synergy into the RECD

**Working title:** *Integrating Φ₃ (excess³) into RECD Dynamics: From Parallel Metric to Structural Clock Contribution*

**Author:** Johel Padilla-Villanueva  
**Status:** Draft **v0.5** — methods + synthetic S0–S2 + dual-domain real-data smoke, unified contrast narrative (July 2026)  
**Folder:** `Investigaciones/Preprint_Phi3_RECD_Dynamic_Integration/`  
**Python package:** `phi3-recd` **v0.5.0** (optional coupling layer; NumPy only)

## Purpose

Close a structural gap in the Systemic Tau / RECD programme: `excess³` (Level Φ₃) is a strong continuous proxy for irreducible ordinal surplus, but in most operational pipelines it remains a **parallel** early-warning readout. This preprint proposes **falsifiable, implementable** ways to let Φ₃ modify the discrete clock update itself — linking the 2026 nested hierarchy to legacy surveillance pipelines.

## Package (`phi3-recd`)

This is a **clock-map** library, not a new ordinal-metric suite. It does **not** recompute \(\tau_s\) or excess³; those come from prior work (e.g. [`nested-recd`](https://github.com/johelpadilla/nested-recd) or Systemic Tau pipelines). What it ships:

| Symbol | Role |
|--------|------|
| Hardened \(A_3\) | Level-3 activation gate (conditions A–D) |
| \(\Gamma_3\) / **P1** | Multiplicative surplus gain on legacy \(\Delta t\) (default) |
| **P2** | Dual-channel experimental map |
| \(\rho_3\), \(\rho_3^{\mathrm{marg}}\) | Contribution diagnostics for ablation / validation |

### Install (editable / local)

```bash
cd Investigaciones/Preprint_Phi3_RECD_Dynamic_Integration
python3 -m pip install -e ".[dev]"
python3 -m phi3_recd          # synthetic demo
pytest -q                     # contract tests
```

Optional extras: `pip install -e ".[ordinal]"` pulls `nested-recd` for excess³ upstream; `.[full]` adds plotting/pandas for the preprint smokes.

### Minimal API

```python
import numpy as np
from phi3_recd import ActivationConfig, P1Config, recd_base, recd_p1

# tau_s, excess3: precomputed series; baseline: bool mask for normalization
tau = np.asarray(...)
e3 = np.asarray(...)
baseline = np.zeros(len(tau), dtype=bool)
baseline[:50] = True

base = recd_base(tau)
p1 = recd_p1(tau, e3, baseline, n_vars=4, cfg=P1Config(beta=0.5),
             act_cfg=ActivationConfig())
# audit: P1Config(beta=0.0) recovers base["t"] exactly
```

### Publish to PyPI (when you want)

```bash
python3 -m build
python3 -m twine upload dist/*
```

Not uploaded from this session — package is installable and versioned only.

## Contents

| Path | Description |
|------|-------------|
| `manuscript.md` | Full research preprint, **v0.5** |
| `src/phi3_recd/` | Installable package: hardened A₃, P1, P2 |
| `src/validate_synthetic.py` | S0–S2 synthetic validation + figure export |
| `src/smoke_real_sddb.py` | Real-data smoke: SDDB events + NSRDB controls |
| `src/smoke_dengai.py` | Real-data smoke: DengAI San Juan / Iquitos |
| `tests/` | Package contract tests |
| `pyproject.toml` | `phi3-recd` packaging metadata |
| `data/dengai/` | DengAI train features + labels (DrivenData) |
| `refs/references.bib` | Core bibliography stubs |
| `figures/` | Synthetic + smoke figures and tables |
| `HANDOFF.md` | Session handoff for agents |

## Quick run

```bash
# package demo (after pip install -e .)
python3 -m phi3_recd

# preprint validation scripts
cd src
python3 validate_synthetic.py  # S0–S2 tables + PNG figures
python3 smoke_real_sddb.py     # needs ../Cardiac_CCTP_Pilot/data/
python3 smoke_dengai.py        # uses ../data/dengai/
```

## v0.5 highlights (vs v0.4)

- **Narrative:** Holter + DengAI smokes merged into one §6.4 strategic contrast (protocol table + joint comparison + four defensible conclusions)
- **Density:** removed duplicated “honest reading” lists; single message across domains
- **Consistency:** soft_offset \(s_0=3.25\) + soft_floor aligned with `phi3_recd.py`; Appendix A → v0.5
- **No new empirical runs** — numbers same as v0.3–v0.4

## v0.4 highlights (kept)

- **DengAI smoke:** SJ + IQ; IQ-2004 ΔT legacy +1.24; A₃ sens 3/6; control FAR ~1.6/52w
- Chaos-band still high (~98%) with 4-var proxy; dt_base active ~7% vs ~0.1% Holter

## v0.3 highlights (kept)

- **Holter smoke:** SDDB 30/31/35 + NSRDB; Feigenbaum freeze; A₃ sparse under hyperpersist
- P2 experimental; Holter-path diagnostic clock reported alongside legacy T

## v0.2 highlights (kept)

- Hardened A₃; synthetic S0–S2 gates; corr(Γ−1, f₃) ≈ 0.99 on S1

## Scope

**Is:** mathematical coupling of Φ₃ into `Δt_k`; two graded designs (P1 recommended, P2 experimental); activation; synthetic results; dual-domain real-data smokes with limitations  
**Is not:** strong ontology; full PID; operational EWS claim (smokes do not support FAR superiority)

## Recommended citation (placeholder)

Padilla-Villanueva, J. (2026). *Integrating Φ₃ (excess³) into RECD Dynamics: From Parallel Metric to Structural Clock Contribution* (Preprint draft v0.5).
