nirvana-quant 1.0.0__tar.gz → 1.0.2__tar.gz

nirvana_quant-1.0.2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: nirvana-quant
+Version: 1.0.2
+Summary: Nirvana: Chrono-Cancer Meta-Architecture for High-Dimensional Cyclical Time-Series & Dynamical Network Analysis
+Home-page: https://github.com/yinyusi65/nirvana-quant
+Author: yinyusi65
+Project-URL: Homepage, https://github.com/yinyusi65/nirvana-quant
+Project-URL: Bug Tracker, https://github.com/yinyusi65/nirvana-quant/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.3.0,>=1.22.0
+Requires-Dist: pandas<3.0.0,>=1.4.0
+Requires-Dist: scipy>=1.8.0
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# nirvana-quant: A Statistical and Econometric Framework for Multivariate Cyclical Time Series
+
+<p align="center">
+  <a href="https://pypi.org/project/nirvana-quant/"><img src="https://img.shields.io/pypi/v/nirvana-quant.svg?color=007ec6&logo=pypi&logoColor=white" alt="PyPI Version"></a>
+  <a href="https://pypi.org/project/nirvana-quant/"><img src="https://img.shields.io/pypi/dm/nirvana-quant?color=blue&logo=python&logoColor=white" alt="Downloads"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg?logo=python&logoColor=white" alt="Python Versions"></a>
+  <a href="nirvana_cpp/"><img src="https://img.shields.io/badge/C%2B%2B-20%20Header--Only-purple.svg?logo=cplusplus&logoColor=white" alt="C++20"></a>
+  <a href="https://www.gnu.org/licenses/gpl-3.0"><img src="https://img.shields.io/badge/License-GPLv3-green.svg" alt="License: GPL v3"></a>
+  <a href="https://colab.research.google.com/github/yinyusi65/nirvana-quant/blob/main/test_nirvana_netbank_full_pipeline.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>
+</p>
+
+---
+
+`nirvana-quant` is an open-source Python and C++ research framework for **multivariate time-series econometrics**, state-space filtering, directional network spillover modeling, and counterfactual panel reconstruction.
+
+The library bridges classical econometric foundations (Vector Autoregressions, Diebold–Yılmaz connectedness, Kalman filters) with modern non-parametric methods (piecewise regression trees, Fisher Information regularization, and finite-sample Split Conformal Prediction).
+
+---
+
+## 🚀 Interactive Notebook Demo (1-Click Run)
+
+Test the complete end-to-end systemic risk pipeline across 27 commercial banks with interactive network graphs, SVD market decoupling, domino default contagion, and Basel IV macroprudential capital surcharge calibration:
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yinyusi65/nirvana-quant/blob/main/test_nirvana_netbank_full_pipeline.ipynb)
+
+---
+
+## 📊 Visualizations & Topological Risk Analytics
+
+The engine extracts systemic interbank connections from multivariate asset price series:
+
+| Pairwise Spillover Intensity Heatmap (27x27) | Directed Systemic Risk Network Topology |
+| :---: | :---: |
+| <img src="docs/images/banking_pairwise_spillover_heatmap.png" width="450"/> | <img src="docs/images/banking_network_directed_topology.png" width="450"/> |
+
+| Net Transmitter vs. Receiver Ranking | Hub vs. Authority Scatterplot |
+| :---: | :---: |
+| <img src="docs/images/banking_net_spillover_ranking.png" width="450"/> | <img src="docs/images/banking_hub_vs_authority_scatter.png" width="450"/> |
+
+---
+
+## ⚡ Quickstart in 3 Lines
+
+```bash
+pip install nirvana-quant
+```
+
+```python
+import pandas as pd
+from nirvana import NirvanaConnectedness
+
+# Fit a TVP-VAR causal Kalman network model
+model = NirvanaConnectedness(kalman_q=1e-3, kalman_r=1e-2, orthogonalize_market=True)
+results = model.fit(df_asset_returns)
+
+print(f"Total Connectedness Index (TCI): {results.total_connectedness_index:.2f}%")
+print("Top Shock Transmitters:", results.top_transmitters[:5])
+print("Top Shock Receivers:", results.top_receivers[:5])
+```
+
+---
+
+## 🔬 Core Methodological Modules
+
+### 1. Harmonic Feature Mapping (`nirvana.manifold`)
+* Maps multi-frequency cyclical signals (such as quarterly financial reporting and annual cycles) onto periodic manifold coordinates ($\mathbb{T}^2 = S^1 \times S^1$).
+* Incorporates Discrete Fourier Transform (DFT) power spectral estimation to identify dominant frequencies empirically.
+
+### 2. Causal State-Space Filtering & TVP (`nirvana.kalman`)
+* Implements sequential Kalman state-space estimation with strictly causal updates (zero lookahead bias).
+* Utilizes the Joseph-stabilized covariance formulation:
+  $$P_t = (I - K_t H) P_{t|t-1} (I - K_t H)^T + K_t R K_t^T$$
+  to ensure positive semi-definiteness under ill-conditioned measurement environments.
+* Employs Huber-type innovation bounds to limit sensitivity to fat-tailed shocks.
+
+### 3. Regularized Piecewise Regression (`nirvana.tree`)
+* Captures non-linear residual structures via bounded piecewise regression trees.
+* Utilizes Fisher Information Matrix metrics and sample-margin density criteria to guide terminal-node pruning and mitigate finite-sample overfitting.
+
+### 4. Directional Spillover & Network Topology (`nirvana.network`)
+* Computes directional connectedness matrices via Vector Autoregressions (VAR) and Generalized Forecast Error Variance Decomposition (GFEVD, Koop–Pesaran–Potter).
+* Employs Singular Value Decomposition (SVD) to isolate pervasive common market factors from idiosyncratic innovations.
+* Evaluates Kleinberg graph centrality measures (Hub and Authority scores) to distinguish net transmitters from net receivers of shocks.
+
+### 5. Counterfactual Panel Reconstruction (`nirvana.multiverse`)
+* Implements counterfactual imputation for unbalanced historical panels (such as pre-listing asset periods).
+* Evaluates sensitivity across structured simulation paths anchored on peer-group dynamics and macroeconomic benchmarks.
+* Uses cubic Hermite transition polynomials ($3t^2 - 2t^3$) to ensure boundary continuity between reconstructed and observed sample periods.
+
+### 6. Two-Stage Estimation & Conformal Prediction (`nirvana.static`, `nirvana.proof`)
+* Combines parametric base estimators (OLS, Ridge, Lasso) with non-linear residual trees in a two-stage additive framework.
+* Computes distribution-free prediction intervals via Split Conformal Prediction, satisfying finite-sample coverage guarantees:
+  $$P\Big(Y_{n+1} \in [\hat{Y}_{n+1} - q, \hat{Y}_{n+1} + q]\Big) \ge 1 - \alpha$$
+
+---
+
+## 🏛️ Domain Extensions (`nirvana.domains`)
+
+Domain-specific structural parameters are maintained in modular extensions:
+
+* **`banking`**: Empirical asset-scaling adjustments, exchange price-band limits, and interbank liquidity position mappings for systemic risk studies.
+* **`cybersecurity`**: Directed network graph modeling for anomalous traffic flows and node centrality analysis.
+* **`supply_chain`**: Multi-tier propagation models for inventory volatility and supplier dependency shocks.
+
+---
+
+## 💻 C++ Implementation (`nirvana_cpp/`)
+
+For low-latency execution and integration into compiled pipelines, the repository includes a self-contained C++20 header library:
+
+* Header-only: `#include <nirvana/nirvana.hpp>`.
+* Self-contained linear algebra routines (matrix decomposition, SVD, pseudoinverse) without mandatory external dependencies.
+* Compatible with standard C++20 compilers (GCC 12+, Clang 15+, MSVC 19.30+).
+
+---
+
+## 📦 Installation Options
+
+### From PyPI (Recommended)
+```bash
+pip install nirvana-quant
+```
+
+### From GitHub
+```bash
+pip install git+https://github.com/yinyusi65/nirvana-quant.git
+```
+
+### From Local Source
+```bash
+git clone https://github.com/yinyusi65/nirvana-quant.git
+cd nirvana-quant
+pip install -e .
+```
+
+---
+
+## 📖 Usage Examples
+
+### 1. Two-Stage Regression with Conformal Prediction Intervals
+```python
+import numpy as np
+from nirvana import NirvanaTwoStageRegressor
+
+# Cross-sectional sample
+np.random.seed(42)
+X = np.random.randn(120, 3)
+y = 1.8 * X[:, 0] - 0.7 * (X[:, 1] ** 2) + np.random.randn(120) * 0.15
+
+# Fit two-stage additive model
+regressor = NirvanaTwoStageRegressor(base_estimator="ols", max_depth=4)
+regressor.fit(X, y)
+
+# Compute 95% conformal prediction intervals
+y_pred, y_lower, y_upper = regressor.predict_interval(X, alpha=0.05)
+print(f"Point Forecast: {y_pred[0]:.3f}, 95% Interval: [{y_lower[0]:.3f}, {y_upper[0]:.3f}]")
+```
+
+---
+
+## 👤 Authors & Maintainers
+* **yinyusi65**
+
+## 📄 License
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

nirvana_quant-1.0.2/README.md

@@ -0,0 +1,165 @@
+# nirvana-quant: A Statistical and Econometric Framework for Multivariate Cyclical Time Series
+
+<p align="center">
+  <a href="https://pypi.org/project/nirvana-quant/"><img src="https://img.shields.io/pypi/v/nirvana-quant.svg?color=007ec6&logo=pypi&logoColor=white" alt="PyPI Version"></a>
+  <a href="https://pypi.org/project/nirvana-quant/"><img src="https://img.shields.io/pypi/dm/nirvana-quant?color=blue&logo=python&logoColor=white" alt="Downloads"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg?logo=python&logoColor=white" alt="Python Versions"></a>
+  <a href="nirvana_cpp/"><img src="https://img.shields.io/badge/C%2B%2B-20%20Header--Only-purple.svg?logo=cplusplus&logoColor=white" alt="C++20"></a>
+  <a href="https://www.gnu.org/licenses/gpl-3.0"><img src="https://img.shields.io/badge/License-GPLv3-green.svg" alt="License: GPL v3"></a>
+  <a href="https://colab.research.google.com/github/yinyusi65/nirvana-quant/blob/main/test_nirvana_netbank_full_pipeline.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>
+</p>
+
+---
+
+`nirvana-quant` is an open-source Python and C++ research framework for **multivariate time-series econometrics**, state-space filtering, directional network spillover modeling, and counterfactual panel reconstruction.
+
+The library bridges classical econometric foundations (Vector Autoregressions, Diebold–Yılmaz connectedness, Kalman filters) with modern non-parametric methods (piecewise regression trees, Fisher Information regularization, and finite-sample Split Conformal Prediction).
+
+---
+
+## 🚀 Interactive Notebook Demo (1-Click Run)
+
+Test the complete end-to-end systemic risk pipeline across 27 commercial banks with interactive network graphs, SVD market decoupling, domino default contagion, and Basel IV macroprudential capital surcharge calibration:
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yinyusi65/nirvana-quant/blob/main/test_nirvana_netbank_full_pipeline.ipynb)
+
+---
+
+## 📊 Visualizations & Topological Risk Analytics
+
+The engine extracts systemic interbank connections from multivariate asset price series:
+
+| Pairwise Spillover Intensity Heatmap (27x27) | Directed Systemic Risk Network Topology |
+| :---: | :---: |
+| <img src="docs/images/banking_pairwise_spillover_heatmap.png" width="450"/> | <img src="docs/images/banking_network_directed_topology.png" width="450"/> |
+
+| Net Transmitter vs. Receiver Ranking | Hub vs. Authority Scatterplot |
+| :---: | :---: |
+| <img src="docs/images/banking_net_spillover_ranking.png" width="450"/> | <img src="docs/images/banking_hub_vs_authority_scatter.png" width="450"/> |
+
+---
+
+## ⚡ Quickstart in 3 Lines
+
+```bash
+pip install nirvana-quant
+```
+
+```python
+import pandas as pd
+from nirvana import NirvanaConnectedness
+
+# Fit a TVP-VAR causal Kalman network model
+model = NirvanaConnectedness(kalman_q=1e-3, kalman_r=1e-2, orthogonalize_market=True)
+results = model.fit(df_asset_returns)
+
+print(f"Total Connectedness Index (TCI): {results.total_connectedness_index:.2f}%")
+print("Top Shock Transmitters:", results.top_transmitters[:5])
+print("Top Shock Receivers:", results.top_receivers[:5])
+```
+
+---
+
+## 🔬 Core Methodological Modules
+
+### 1. Harmonic Feature Mapping (`nirvana.manifold`)
+* Maps multi-frequency cyclical signals (such as quarterly financial reporting and annual cycles) onto periodic manifold coordinates ($\mathbb{T}^2 = S^1 \times S^1$).
+* Incorporates Discrete Fourier Transform (DFT) power spectral estimation to identify dominant frequencies empirically.
+
+### 2. Causal State-Space Filtering & TVP (`nirvana.kalman`)
+* Implements sequential Kalman state-space estimation with strictly causal updates (zero lookahead bias).
+* Utilizes the Joseph-stabilized covariance formulation:
+  $$P_t = (I - K_t H) P_{t|t-1} (I - K_t H)^T + K_t R K_t^T$$
+  to ensure positive semi-definiteness under ill-conditioned measurement environments.
+* Employs Huber-type innovation bounds to limit sensitivity to fat-tailed shocks.
+
+### 3. Regularized Piecewise Regression (`nirvana.tree`)
+* Captures non-linear residual structures via bounded piecewise regression trees.
+* Utilizes Fisher Information Matrix metrics and sample-margin density criteria to guide terminal-node pruning and mitigate finite-sample overfitting.
+
+### 4. Directional Spillover & Network Topology (`nirvana.network`)
+* Computes directional connectedness matrices via Vector Autoregressions (VAR) and Generalized Forecast Error Variance Decomposition (GFEVD, Koop–Pesaran–Potter).
+* Employs Singular Value Decomposition (SVD) to isolate pervasive common market factors from idiosyncratic innovations.
+* Evaluates Kleinberg graph centrality measures (Hub and Authority scores) to distinguish net transmitters from net receivers of shocks.
+
+### 5. Counterfactual Panel Reconstruction (`nirvana.multiverse`)
+* Implements counterfactual imputation for unbalanced historical panels (such as pre-listing asset periods).
+* Evaluates sensitivity across structured simulation paths anchored on peer-group dynamics and macroeconomic benchmarks.
+* Uses cubic Hermite transition polynomials ($3t^2 - 2t^3$) to ensure boundary continuity between reconstructed and observed sample periods.
+
+### 6. Two-Stage Estimation & Conformal Prediction (`nirvana.static`, `nirvana.proof`)
+* Combines parametric base estimators (OLS, Ridge, Lasso) with non-linear residual trees in a two-stage additive framework.
+* Computes distribution-free prediction intervals via Split Conformal Prediction, satisfying finite-sample coverage guarantees:
+  $$P\Big(Y_{n+1} \in [\hat{Y}_{n+1} - q, \hat{Y}_{n+1} + q]\Big) \ge 1 - \alpha$$
+
+---
+
+## 🏛️ Domain Extensions (`nirvana.domains`)
+
+Domain-specific structural parameters are maintained in modular extensions:
+
+* **`banking`**: Empirical asset-scaling adjustments, exchange price-band limits, and interbank liquidity position mappings for systemic risk studies.
+* **`cybersecurity`**: Directed network graph modeling for anomalous traffic flows and node centrality analysis.
+* **`supply_chain`**: Multi-tier propagation models for inventory volatility and supplier dependency shocks.
+
+---
+
+## 💻 C++ Implementation (`nirvana_cpp/`)
+
+For low-latency execution and integration into compiled pipelines, the repository includes a self-contained C++20 header library:
+
+* Header-only: `#include <nirvana/nirvana.hpp>`.
+* Self-contained linear algebra routines (matrix decomposition, SVD, pseudoinverse) without mandatory external dependencies.
+* Compatible with standard C++20 compilers (GCC 12+, Clang 15+, MSVC 19.30+).
+
+---
+
+## 📦 Installation Options
+
+### From PyPI (Recommended)
+```bash
+pip install nirvana-quant
+```
+
+### From GitHub
+```bash
+pip install git+https://github.com/yinyusi65/nirvana-quant.git
+```
+
+### From Local Source
+```bash
+git clone https://github.com/yinyusi65/nirvana-quant.git
+cd nirvana-quant
+pip install -e .
+```
+
+---
+
+## 📖 Usage Examples
+
+### 1. Two-Stage Regression with Conformal Prediction Intervals
+```python
+import numpy as np
+from nirvana import NirvanaTwoStageRegressor
+
+# Cross-sectional sample
+np.random.seed(42)
+X = np.random.randn(120, 3)
+y = 1.8 * X[:, 0] - 0.7 * (X[:, 1] ** 2) + np.random.randn(120) * 0.15
+
+# Fit two-stage additive model
+regressor = NirvanaTwoStageRegressor(base_estimator="ols", max_depth=4)
+regressor.fit(X, y)
+
+# Compute 95% conformal prediction intervals
+y_pred, y_lower, y_upper = regressor.predict_interval(X, alpha=0.05)
+print(f"Point Forecast: {y_pred[0]:.3f}, 95% Interval: [{y_lower[0]:.3f}, {y_upper[0]:.3f}]")
+```
+
+---
+
+## 👤 Authors & Maintainers
+* **yinyusi65**
+
+## 📄 License
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

{nirvana_quant-1.0.0 → nirvana_quant-1.0.2}/nirvana/__init__.py

@@ -1,75 +1,76 @@
-"""
-NIRVANA: Chrono-Cancer Meta-Architecture for High-Dimensional Financial Risk & Network Dynamics
-================================================================================================
-A causal, manifold-based quantitative engine for financial time-series, volatility spillover,
-and systemic risk analysis across interconnected banking systems.
-
-Author: yinyusi65 & Nirvana Quant Team
-License: MIT / Academic Research
-"""
-
-__version__ = "1.0.0"
-
-from .manifold import Base12Manifold, DualClockCoordinates
-from .kalman import CausalOnlineKalman, MultivariateCausalKalman, CausalKalmanTVPRegressor
-from .tree import NirvanaTreeEngine, TrainingSample
-from .network import (
-    NirvanaConnectedness,
-    SystemicRiskReport,
-    DynamicSystemicRiskReport,
-    DEFAULT_ASSET_WEIGHTS,
-    DEFAULT_EXCHANGE_BANDS,
-)
-from .multiplex import MultiplexNetworkEngine
-from .multiverse import MultiverseReconstructor
-from .volatility import compute_parkinson, compute_garman_klass, compute_yang_zhang
-from .static import (
-    NirvanaStaticBooster,
-    StaticEconometricReport,
-    NirvanaTreeRegressor,
-    NirvanaTwoStageRegressor,
-    parse_formula,
-)
-from .stata import stata_regress, StataRegressionResult, stata_summarize, stata_pwcorr
-from .proof import (
-    prove_phase2_variable,
-    Phase2MultiverseProofReport,
-    rank_phase2_discovered_variables,
-    Phase2RankedVariablesReport,
-    DiscoveredVariableItem,
-)
-from . import domains
-
-__all__ = [
-    "Base12Manifold",
-    "DualClockCoordinates",
-    "CausalOnlineKalman",
-    "MultivariateCausalKalman",
-    "NirvanaTreeEngine",
-    "TrainingSample",
-    "NirvanaStaticBooster",
-    "StaticEconometricReport",
-    "NirvanaTreeRegressor",
-    "NirvanaTwoStageRegressor",
-    "parse_formula",
-    "stata_regress",
-    "StataRegressionResult",
-    "stata_summarize",
-    "stata_pwcorr",
-    "prove_phase2_variable",
-    "Phase2MultiverseProofReport",
-    "rank_phase2_discovered_variables",
-    "Phase2RankedVariablesReport",
-    "DiscoveredVariableItem",
-    "NirvanaConnectedness",
-    "SystemicRiskReport",
-    "DynamicSystemicRiskReport",
-    "DEFAULT_ASSET_WEIGHTS",
-    "DEFAULT_EXCHANGE_BANDS",
-    "MultiplexNetworkEngine",
-    "MultiverseReconstructor",
-    "compute_parkinson",
-    "compute_garman_klass",
-    "compute_yang_zhang",
-    "domains",
-]
+"""
+NIRVANA: Chrono-Cancer Meta-Architecture for High-Dimensional Financial Risk & Network Dynamics
+================================================================================================
+A causal, manifold-based quantitative engine for financial time-series, volatility spillover,
+and systemic risk analysis across interconnected banking systems.
+
+Author: yinyusi65 & Nirvana Quant Team
+License: MIT / Academic Research
+"""
+
+__version__ = "1.0.2"
+
+from .manifold import Base12Manifold, FractionalBase12Manifold, DualClockCoordinates
+from .kalman import CausalOnlineKalman, MultivariateCausalKalman, CausalKalmanTVPRegressor
+from .tree import NirvanaTreeEngine, TrainingSample
+from .network import (
+    NirvanaConnectedness,
+    SystemicRiskReport,
+    DynamicSystemicRiskReport,
+    DEFAULT_ASSET_WEIGHTS,
+    DEFAULT_EXCHANGE_BANDS,
+)
+from .multiplex import MultiplexNetworkEngine
+from .multiverse import MultiverseReconstructor
+from .volatility import compute_parkinson, compute_garman_klass, compute_yang_zhang
+from .static import (
+    NirvanaStaticBooster,
+    StaticEconometricReport,
+    NirvanaTreeRegressor,
+    NirvanaTwoStageRegressor,
+    parse_formula,
+)
+from .stata import stata_regress, StataRegressionResult, stata_summarize, stata_pwcorr
+from .proof import (
+    prove_phase2_variable,
+    Phase2MultiverseProofReport,
+    rank_phase2_discovered_variables,
+    Phase2RankedVariablesReport,
+    DiscoveredVariableItem,
+)
+from . import domains
+
+__all__ = [
+    "Base12Manifold",
+    "FractionalBase12Manifold",
+    "DualClockCoordinates",
+    "CausalOnlineKalman",
+    "MultivariateCausalKalman",
+    "NirvanaTreeEngine",
+    "TrainingSample",
+    "NirvanaStaticBooster",
+    "StaticEconometricReport",
+    "NirvanaTreeRegressor",
+    "NirvanaTwoStageRegressor",
+    "parse_formula",
+    "stata_regress",
+    "StataRegressionResult",
+    "stata_summarize",
+    "stata_pwcorr",
+    "prove_phase2_variable",
+    "Phase2MultiverseProofReport",
+    "rank_phase2_discovered_variables",
+    "Phase2RankedVariablesReport",
+    "DiscoveredVariableItem",
+    "NirvanaConnectedness",
+    "SystemicRiskReport",
+    "DynamicSystemicRiskReport",
+    "DEFAULT_ASSET_WEIGHTS",
+    "DEFAULT_EXCHANGE_BANDS",
+    "MultiplexNetworkEngine",
+    "MultiverseReconstructor",
+    "compute_parkinson",
+    "compute_garman_klass",
+    "compute_yang_zhang",
+    "domains",
+]