Metadata-Version: 2.4
Name: systemictau
Version: 4.6.0
Summary: Systemic Tau, gate RECD, and optional nested ordinal excess³ (via nested-recd)
Author-email: Johel Padilla-Villanueva <joel.padilla2@upr.edu>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numba>=0.57.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: networkx>=3.0.0
Requires-Dist: matplotlib>=3.7.0
Provides-Extra: reports
Requires-Dist: Jinja2>=3.1.0; extra == "reports"
Requires-Dist: python-docx>=1.1.0; extra == "reports"
Requires-Dist: kaleido>=0.2.1; extra == "reports"
Requires-Dist: plotly>=5.0.0; extra == "reports"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Provides-Extra: nested
Requires-Dist: nested-recd>=0.2.0; extra == "nested"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.7; extra == "visualization"
Requires-Dist: seaborn; extra == "visualization"
Provides-Extra: platform
Requires-Dist: fastapi; extra == "platform"
Requires-Dist: uvicorn; extra == "platform"
Requires-Dist: streamlit; extra == "platform"
Requires-Dist: python-multipart; extra == "platform"
Requires-Dist: pandas; extra == "platform"
Requires-Dist: xarray; extra == "platform"
Requires-Dist: folium; extra == "platform"
Requires-Dist: streamlit-folium; extra == "platform"
Requires-Dist: celery; extra == "platform"
Requires-Dist: redis; extra == "platform"
Requires-Dist: websockets; extra == "platform"
Requires-Dist: pyjwt; extra == "platform"
Requires-Dist: faust-streaming; extra == "platform"
Requires-Dist: neo4j; extra == "platform"
Requires-Dist: python-rocksdb; extra == "platform"
Requires-Dist: prometheus-client; extra == "platform"
Requires-Dist: pydantic-settings; extra == "platform"
Requires-Dist: tenacity; extra == "platform"
Requires-Dist: aiokafka; extra == "platform"
Provides-Extra: gis
Requires-Dist: geopandas; extra == "gis"
Requires-Dist: libpysal; extra == "gis"
Provides-Extra: validation
Requires-Dist: scikit-learn; extra == "validation"
Provides-Extra: performance
Requires-Dist: numba; extra == "performance"
Requires-Dist: dask; extra == "performance"
Requires-Dist: jax; extra == "performance"
Requires-Dist: jaxlib; extra == "performance"
Requires-Dist: pluggy; extra == "performance"
Provides-Extra: ai
Requires-Dist: google-genai; extra == "ai"
Requires-Dist: pydantic; extra == "ai"
Provides-Extra: desktop
Requires-Dist: customtkinter; extra == "desktop"
Provides-Extra: studio
Requires-Dist: streamlit>=1.28; extra == "studio"
Requires-Dist: matplotlib>=3.7; extra == "studio"
Requires-Dist: pandas; extra == "studio"
Requires-Dist: openpyxl; extra == "studio"
Requires-Dist: pywebview; extra == "studio"
Provides-Extra: full
Requires-Dist: matplotlib>=3.7; extra == "full"
Requires-Dist: seaborn; extra == "full"
Requires-Dist: pandas; extra == "full"
Requires-Dist: openpyxl; extra == "full"
Requires-Dist: xarray; extra == "full"
Requires-Dist: streamlit; extra == "full"
Requires-Dist: typer; extra == "full"
Requires-Dist: fastapi; extra == "full"
Requires-Dist: uvicorn; extra == "full"
Requires-Dist: python-multipart; extra == "full"
Requires-Dist: geopandas; extra == "full"
Requires-Dist: libpysal; extra == "full"
Requires-Dist: scikit-learn; extra == "full"
Requires-Dist: numba; extra == "full"
Requires-Dist: dask; extra == "full"
Requires-Dist: folium; extra == "full"
Requires-Dist: streamlit-folium; extra == "full"
Requires-Dist: google-genai; extra == "full"
Requires-Dist: celery; extra == "full"
Requires-Dist: redis; extra == "full"
Requires-Dist: websockets; extra == "full"
Requires-Dist: pyjwt; extra == "full"
Requires-Dist: jax; extra == "full"
Requires-Dist: jaxlib; extra == "full"
Requires-Dist: faust-streaming; extra == "full"
Requires-Dist: neo4j; extra == "full"
Requires-Dist: pluggy; extra == "full"
Requires-Dist: python-rocksdb; extra == "full"
Requires-Dist: prometheus-client; extra == "full"
Requires-Dist: pydantic-settings; extra == "full"
Requires-Dist: tenacity; extra == "full"
Requires-Dist: aiokafka; extra == "full"
Requires-Dist: customtkinter; extra == "full"
Requires-Dist: pywebview; extra == "full"
Requires-Dist: nested-recd>=0.2.0; extra == "full"
Dynamic: license-file

# Systemic Tau & Discrete Extramental Clock (RECD)

[![PyPI version](https://badge.fury.io/py/systemictau.svg)](https://pypi.org/project/systemictau/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**`systemictau`** implements the **Systemic Tau** paradigm and the **Discrete Extramental Clock (RECD)** for ordinal multivariate time-series analysis (early-warning, regime reorganization, multi-scale structure).

**Current library version:** 4.6.0

## Installation

```bash
pip install systemictau
# Level-3 nested ordinal RECD / continuous excess³:
pip install "systemictau[nested]"   # pulls nested-recd>=0.2
```

From source:

```bash
git clone https://github.com/johelpadilla/systemictau
cd systemictau
pip install -e ".[nested,dev]"
```

## Two RECD notions (do not confuse)

| Name | API | What it is |
|------|-----|------------|
| **Gate RECD** | `compute_recd_increments`, `accumulate_time` | Clock from **τ_s** + Feigenbaum gate |
| **Nested ordinal RECD / excess³** | `compute_nested_recd` → [`nested-recd`](https://pypi.org/project/nested-recd/) | Φ₁–Φ₃ on Bandt–Pompe; **excess³ = 0.6·Syn + 0.4·Surp** primary Level-3 |

Canonical Level-3 methods: [DOI 10.5281/zenodo.21385937](https://doi.org/10.5281/zenodo.21385937) · [github.com/johelpadilla/excess3](https://github.com/johelpadilla/excess3)

## Quick start

```python
import numpy as np
import systemictau as st

np.random.seed(42)
X = np.random.randn(500, 4)

# Systemic Tau
taus_global, taus_per_module = st.compute_taus(X, window_size=13)

# Gate RECD
T_series, dtk_series, gate_series, depths = st.accumulate_time(taus_global)

# Nested ordinal RECD / continuous excess³ (requires nested-recd)
if st.has_nested_recd():
    nested = st.compute_nested_recd(X, tau_s=taus_global, m=3, theta3=0.10)
    print("mean excess³:", float(np.nanmean(nested["excess3"])))

# Full pipeline with optional Level-3
res = st.run_full_analysis(X, window_size=13, compute_nested_recd=True)
print("t* =", res.t_star)
if res.nested_recd_results:
    print("mean excess³:", res.nested_recd_results["mean_excess3"])
```

## Studio (optional)

```bash
pip install "systemictau[studio]"
systemictau-studio
# or: PYTHONPATH=src streamlit run src/systemictau/studio/app.py
```

## Related packages

| Project | Role |
|---------|------|
| [`nested-recd`](https://pypi.org/project/nested-recd/) | Canonical Φ₁–Φ₃ + excess³ core |
| [`excess3`](https://github.com/johelpadilla/excess3) | Methods + intro ES + primer |
| [`systemictau-web`](https://github.com/johelpadilla/systemictau-web) | Streamlit analytical app |

## Citation

> Padilla-Villanueva, Johel. (2026). *Síntesis Magna del Tau Sistémico*. Zenodo. DOI: [10.5281/zenodo.20576241](https://doi.org/10.5281/zenodo.20576241)

For excess³ / Level-3 claims, also cite:

> Padilla-Villanueva, J. (2026). *excess³* methods. DOI: [10.5281/zenodo.21385937](https://doi.org/10.5281/zenodo.21385937)

## License

MIT © Johel Padilla-Villanueva  
ORCID: [0000-0002-5797-6931](https://orcid.org/0000-0002-5797-6931)
