nardl-fourier 1.0.0

Nonlinear ARDL with Fourier approximation and Bootstrap cointegration tests

NARDL-Fourier: Nonlinear ARDL with Fourier Approximation

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

pip install nardl-fourier

Or install from source:

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

📖 Quick Start

Standard NARDL

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

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

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

# 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

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

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: [e-mail]
🌐 GitHub: https://github.com/merwanroudane/fnardl

📄 License

This project is licensed under the MIT License - see the 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:

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