Metadata-Version: 2.4
Name: nardl-fourier
Version: 1.0.0
Summary: Nonlinear ARDL with Fourier approximation and Bootstrap cointegration tests
Author-email: "Dr. Merwan Roudane" <merwanroudane920@gmail.com>
Maintainer-email: "Dr. Merwan Roudane" <merwanroudane920@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/merwanroudane/fnardl
Project-URL: Documentation, https://merwanroudane.github.io/fnardl/
Project-URL: Repository, https://github.com/merwanroudane/fnardl
Project-URL: Issues, https://github.com/merwanroudane/fnardl/issues
Keywords: econometrics,NARDL,cointegration,asymmetric,Fourier,bootstrap,time-series,bounds-test
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: tabulate>=0.8.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"
Requires-Dist: plotly>=5.0.0; extra == "notebook"
Requires-Dist: openpyxl>=3.0.0; extra == "notebook"
Dynamic: license-file

# NARDL-Fourier: Nonlinear ARDL with Fourier Approximation

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://img.shields.io/badge/DOI-10.xxxx%2Fxxxxxx-blue)](https://doi.org/)

A comprehensive Python library for **Nonlinear Autoregressive Distributed Lag (NARDL)** modeling with **Fourier approximation** for smooth structural breaks and **Bootstrap cointegration tests**.

## 📚 Features

### Three Core Models

| Model | Description | Reference |
|-------|-------------|-----------|
| **NARDL** | Standard Nonlinear ARDL | Shin, Yu & Greenwood-Nimmo (2014) |
| **FourierNARDL** | NARDL with Fourier terms for structural breaks | Zaghdoudi et al. (2023) |
| **BootstrapNARDL** | Bootstrap cointegration tests | Bertelli, Vacca & Zoia (2022) |

### Key Capabilities

- ✅ **Asymmetric decomposition**: Positive and negative partial sums
- ✅ **Automatic lag selection**: AIC/BIC optimization
- ✅ **Long-run multipliers**: With delta-method standard errors
- ✅ **Short-run ECM analysis**: Error correction term with half-life
- ✅ **Wald tests**: Long-run and short-run asymmetry testing
- ✅ **PSS bounds test**: With Pesaran et al. (2001) critical values
- ✅ **Bootstrap bounds test**: Eliminates inconclusive zones
- ✅ **Dynamic multipliers**: With 95% bootstrap confidence intervals
- ✅ **Diagnostic tests**: Normality, serial correlation, heteroskedasticity
- ✅ **Stability tests**: CUSUM and CUSUM of Squares
- ✅ **Publication-ready output**: LaTeX, HTML, and markdown tables

## 🚀 Installation

```bash
pip install nardl-fourier
```

Or install from source:

```bash
git clone https://github.com/merwanroudane/fnardl.git
cd fnardl
pip install -e .
```

## 📖 Quick Start

### Standard NARDL

```python
from nardl_fourier import NARDL
import pandas as pd

# Load your data
data = pd.read_excel('your_data.xlsx')

# Fit NARDL model
model = NARDL(
    data=data,
    depvar='coal',           # Dependent variable
    exog_vars=['gdp'],       # Control variables (symmetric)
    decomp_vars=['oil'],     # Variables to decompose (asymmetric)
    maxlag=4,                # Maximum lag to consider
    ic='AIC'                 # Information criterion
)

# View summary
print(model.summary())

# Long-run multipliers
print(model.long_run_table())

# Plot dynamic multipliers
fig = model.plot_multipliers()
```

### Fourier NARDL

```python
from nardl_fourier import FourierNARDL

# Fit Fourier NARDL (captures smooth structural breaks)
model = FourierNARDL(
    data=data,
    depvar='coal',
    exog_vars=['gdp', 'gdp2'],
    decomp_vars=['oil'],
    maxlag=4,
    max_freq=3,              # Maximum Fourier frequency
    ic='AIC'
)

print(f"Optimal frequency: k* = {model.best_freq}")
print(model.summary())
```

### Bootstrap NARDL

```python
from nardl_fourier import BootstrapNARDL

# Fit with bootstrap cointegration tests
model = BootstrapNARDL(
    data=data,
    depvar='coal',
    exog_vars=['gdp', 'gdp2'],
    decomp_vars=['oil'],
    maxlag=4,
    n_bootstrap=1000         # Bootstrap replications
)

# Cointegration decision (no inconclusive zone!)
print(model.cointegration_decision())

# Plot bootstrap distributions
fig = model.plot_bootstrap_distributions()
```

## 📊 Output Examples

### Regression Results
```
================================================================================
NARDL MODEL ESTIMATION RESULTS
================================================================================
Dependent Variable: coal
Decomposed Variables: oil
Control Variables: gdp, gdp2
--------------------------------------------------------------------------------
Observations: 118
R-squared: 0.9847
Adj. R-squared: 0.9812
Information Criterion (AIC): -245.6732
--------------------------------------------------------------------------------
Optimal Lag Structure:
  p (Y lags): 3
  q (X lags): 2
  r (Z lags): gdp=1, gdp2=0
================================================================================
```

### Bounds Test
```
PSS BOUNDS TEST FOR COINTEGRATION
------------------------------------------------------------
F-statistic: 8.2341
Critical Values (5%): I(0)=3.79, I(1)=4.85
Decision: Cointegration
```

### Bootstrap Test
```
BOOTSTRAP COINTEGRATION TESTS (Bertelli et al., 2022)
------------------------------------------------------------
F_ov:  Statistic=8.234, CV(5%)=5.891, p=0.012 → ✓ Reject H₀
t:     Statistic=-4.56, CV(5%)=-3.21, p=0.008 → ✓ Reject H₀ 
F_ind: Statistic=6.123, CV(5%)=4.567, p=0.023 → ✓ Reject H₀
------------------------------------------------------------
✅ CONCLUSION: COINTEGRATION DETECTED
```

## 📈 Visualizations

The library provides publication-quality plots:

- **Dynamic Multipliers**: Asymmetric cumulative effects with 95% CI
- **CUSUM/CUSUMSQ**: Parameter stability tests
- **Short-run Coefficients**: Bar charts by lag
- **ECT Adjustment Path**: Convergence visualization
- **Residual Diagnostics**: Q-Q plot, histogram, time series

```python
# All plots
model.plot_multipliers()
model.plot_cusum()
model.plot_cusumsq()

# Using NARDLPlots class
from nardl_fourier import NARDLPlots
plots = NARDLPlots(model)
plots.residuals()
```

## 📋 Export to LaTeX

```python
from nardl_fourier import ResultsTable

table = ResultsTable(model)

# Export all tables to LaTeX
table.to_latex('results.tex')

# Individual tables
print(table.long_run_table('latex'))
print(table.diagnostics_table('latex'))
```

## 🔬 Diagnostic Tests

```python
from nardl_fourier.diagnostics import run_all_diagnostics

results = run_all_diagnostics(model)

# Summary
print(f"Issues detected: {results['summary']['issues_detected']}")

# Individual tests
print(results['normality']['jarque_bera'])
print(results['serial_correlation']['breusch_godfrey'])
print(results['heteroskedasticity']['breusch_pagan'])
```

## 📚 References

1. **Shin, Y., Yu, B., & Greenwood-Nimmo, M.** (2014). Modelling asymmetric cointegration and dynamic multipliers in a nonlinear ARDL framework. In *Festschrift in Honor of Peter Schmidt* (pp. 281-314). Springer.

2. **Pesaran, M. H., Shin, Y., & Smith, R. J.** (2001). Bounds testing approaches to the analysis of level relationships. *Journal of Applied Econometrics*, 16(3), 289-326.

3. **Zaghdoudi, T., Tissaoui, K., Maaloul, M. H., Bahou, Y., & Kammoun, N.** (2023). Asymmetric connectedness between oil price, coal and renewable energy consumption in China: Evidence from Fourier NARDL approach. *Energy*, 285, 129416.

4. **Bertelli, S., Vacca, G., & Zoia, M.** (2022). Bootstrap cointegration tests in ARDL models. *Economic Modelling*, 116, 105987.

5. **Narayan, P. K.** (2005). The saving and investment nexus for China: Evidence from cointegration tests. *Applied Economics*, 37(17), 1979-1990.

## 👨‍🔬 Author

**Dr. Merwan Roudane**  
📧 Email: merwanroudane920@gmail.com  
🌐 GitHub: [https://github.com/merwanroudane/fnardl](https://github.com/merwanroudane/fnardl)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📊 Citation

If you use this package in your research, please cite:

```bibtex
@software{roudane2024nardl,
  author = {Roudane, Merwan},
  title = {NARDL-Fourier: Nonlinear ARDL with Fourier Approximation and Bootstrap Tests},
  year = {2024},
  url = {https://github.com/merwanroudane/fnardl}
}
```
