Metadata-Version: 2.4
Name: mtnardl1
Version: 1.0.0
Summary: Multiple Threshold Nonlinear Autoregressive Distributed Lag (MTNARDL) Models for Python
Home-page: https://github.com/merwanroudane/mtnardl1
Author: Dr Merwan Roudane
Author-email: Dr Merwan Roudane <merwanroudane920@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Dr. Merwan Roudane
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/merwanroudane/mtnardl1
Project-URL: Documentation, https://github.com/merwanroudane/mtnardl1#readme
Project-URL: Repository, https://github.com/merwanroudane/mtnardl1
Project-URL: Issues, https://github.com/merwanroudane/mtnardl1/issues
Keywords: econometrics,time-series,cointegration,ARDL,NARDL,nonlinear,asymmetric,oil-prices,threshold-models
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Office/Business :: Financial
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
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: plotting
Requires-Dist: matplotlib>=3.5.0; extra == "plotting"
Provides-Extra: docs
Requires-Dist: sphinx>=4.5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# MTNARDL: Multiple Threshold Nonlinear ARDL Models for Python

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive Python library for Multiple Threshold Nonlinear Autoregressive Distributed Lag (MTNARDL) models, implementing the methodology from **Pal & Mitra (2015)** "Asymmetric impact of crude price on oil product pricing in the United States: An application of multiple threshold nonlinear autoregressive distributed lag model" published in *Economic Modelling*.

## Author

**Dr. Merwan Roudane**
- Email: merwanroudane920@gmail.com
- GitHub: https://github.com/merwanroudane/mtnardl1

## Overview

This library provides a complete implementation of:
- **ARDL** (Autoregressive Distributed Lag) models
- **NARDL** (Nonlinear ARDL) models with single threshold
- **MTNARDL** (Multiple Threshold NARDL) models with quantile-based or custom thresholds

The package enables researchers to:
1. Test for asymmetric price transmission
2. Analyze the "Rockets and Feathers" phenomenon
3. Examine threshold effects across different quantiles
4. Perform bounds tests for cointegration (Pesaran et al., 2001)
5. Test for long-run and short-run asymmetry

## Key Features

✅ **Full replication capability** of Pal & Mitra (2015) methodology  
✅ **Multiple threshold decomposition**: quintiles, deciles, or custom thresholds  
✅ **Comprehensive statistical tests**: unit root, cointegration, causality, asymmetry  
✅ **Publication-ready output**: formatted tables and visualizations  
✅ **Cross-platform compatibility**: Windows, macOS, Linux  
✅ **Well-documented**: extensive docstrings and examples  

## Installation

```bash
pip install mtnardl1
```

For development installation:

```bash
git clone https://github.com/merwanroudane/mtnardl1.git
cd mtnardl1
pip install -e ".[dev,plotting]"
```

## Quick Start

```python
import pandas as pd
from mtnardl1 import MTNARDL

# Load your data
data = pd.read_csv('your_data.csv')

# Estimate MTNARDL model with quintile decomposition
model = MTNARDL(
    data=data,
    dependent_var='gasoline_price',
    independent_vars=['volume', 'crude_price'],
    nonlinear_var='crude_price',
    n_thresholds=5,  # Quintile decomposition
    lags_dependent=1,
    lags_independent=0
)

# Fit the model
model.fit()

# View results
print(model.summary())

# Test for cointegration
coint_test = model.bounds_test_cointegration()
print(coint_test)

# Test for asymmetry
asymmetry = model.summary_asymmetry()
print(asymmetry)

# Get threshold effects
effects = model.get_threshold_effects()
print(effects)

# Visualize threshold effects
fig, ax = model.plot_threshold_effects()
fig.savefig('threshold_effects.png')
```

## Models Available

### 1. ARDL Model (Linear)

Standard autoregressive distributed lag model following Pesaran et al. (2001).

```python
from mtnardl1 import ARDL

model = ARDL(
    data=data,
    dependent_var='price',
    independent_vars=['volume', 'crude'],
    lags_dependent=1,
    lags_independent=0
)
model.fit()
```

### 2. NARDL Model (Single Threshold)

Nonlinear ARDL with positive/negative decomposition (Shin et al., 2014).

```python
from mtnardl1 import NARDL

model = NARDL(
    data=data,
    dependent_var='price',
    independent_vars=['volume', 'crude'],
    nonlinear_var='crude',  # Decompose into positive/negative
    lags_dependent=1,
    lags_independent=0
)
model.fit()

# Test asymmetry
lr_asymmetry = model.test_asymmetry_long_run()
sr_asymmetry = model.test_asymmetry_short_run()
```

### 3. MTNARDL Model (Multiple Thresholds)

Multiple threshold NARDL with quantile-based decomposition (Pal & Mitra, 2015).

```python
from mtnardl1 import MTNARDL

# Quintile decomposition (5 thresholds)
model = MTNARDL(
    data=data,
    dependent_var='price',
    independent_vars=['volume', 'crude'],
    nonlinear_var='crude',
    n_thresholds=5
)

# Decile decomposition (10 thresholds)
model = MTNARDL(
    data=data,
    dependent_var='price',
    independent_vars=['volume', 'crude'],
    nonlinear_var='crude',
    n_thresholds=10
)

# Custom thresholds
model = MTNARDL(
    data=data,
    dependent_var='price',
    independent_vars=['volume', 'crude'],
    nonlinear_var='crude',
    custom_thresholds=[-2.0, -1.0, 0.0, 1.0, 2.0]
)
```

## Statistical Tests

### Unit Root Tests

```python
from mtnardl1.tests import unit_root_tests

# ADF, PP, and KPSS tests
results = unit_root_tests(
    series=data['price'],
    tests=['adf', 'pp', 'kpss'],
    regression='c'  # 'c', 'ct', or 'n'
)
print(results)
```

### Bounds Test for Cointegration

```python
# Pesaran et al. (2001) bounds test
coint_test = model.bounds_test_cointegration(alpha=0.05)
print(f"F-statistic: {coint_test['f_statistic']:.4f}")
print(f"Decision: {coint_test['decision']}")
```

### Toda-Yamamoto Causality

```python
from mtnardl1.tests import toda_yamamoto_causality

causality = toda_yamamoto_causality(
    y=data['price'],
    x=data['crude'],
    max_lag=4,
    dmax=1
)
print(causality)
```

### Asymmetry Tests

```python
# Long-run asymmetry (Wald test)
lr_test = model.test_asymmetry_long_run(alpha=0.05)

# Short-run asymmetry (Wald test)
sr_test = model.test_asymmetry_short_run(alpha=0.05)

# Combined summary
summary = model.summary_asymmetry()
print(summary)
```

## Utilities

### Series Decomposition

```python
from mtnardl1.utils import (
    decompose_positive_negative,
    decompose_quantiles,
    decompose_multiple_thresholds
)

# Positive/negative decomposition
cr_plus, cr_minus = decompose_positive_negative(data['crude'])

# Quantile decomposition
partial_sums = decompose_quantiles(data['crude'], n_quantiles=5)

# Custom threshold decomposition
partial_sums = decompose_multiple_thresholds(
    data['crude'],
    thresholds=[-2.0, -1.0, 0.0, 1.0, 2.0]
)
```

### Critical Values

```python
from mtnardl1.critical_values import get_critical_values

# Bounds test critical values (Pesaran et al., 2001)
cv = get_critical_values(
    test='bounds',
    k=2,  # Number of regressors
    case=3,  # Unrestricted intercept, no trend
    alpha=0.05
)

# Simulate critical values for larger models
cv_simulated = get_critical_values(
    test='bounds',
    k=15,
    simulate=True,
    n_simulations=10000
)
```

## Methodology

This library implements the following key methodological contributions from Pal & Mitra (2015):

### 1. Single Threshold NARDL

Decomposes the exogenous variable into positive and negative partial sums:

```
CR_t = CR_0 + CR⁺_t + CR⁻_t
```

where:
- `CR⁺_t = Σ max(ΔCR_i, 0)` (positive changes)
- `CR⁻_t = Σ min(ΔCR_i, 0)` (negative changes)

### 2. Multiple Threshold NARDL

Extends the decomposition to multiple quantiles:

```
CR_t = CR_0 + Σⱼ CR_t(ζⱼ)
```

where `CR_t(ζⱼ)` are partial sums based on quantile thresholds.

### 3. Asymmetry Testing

- **Long-run asymmetry**: Tests if coefficients on different components are equal
- **Short-run asymmetry**: Tests if dynamic adjustments are symmetric
- Uses Wald test with chi-squared distribution

### 4. Bounds Test

Implements Pesaran et al. (2001) bounds testing approach:
- Tests for cointegration without requiring pre-testing for unit roots
- Works with I(0), I(1), or fractionally integrated variables
- Provides lower and upper critical value bounds

## Examples

The `examples/` directory contains:

1. **example_replication.py**: Full replication of Pal & Mitra (2015)
2. **example_basic.py**: Simple introductory examples
3. **example_advanced.py**: Advanced features and customization

Run examples:

```bash
cd examples
python example_replication.py
```

## Testing

Run the test suite:

```bash
pytest tests/ -v --cov=mtnardl1
```

## Documentation

Detailed documentation is available in the docstrings. Generate HTML documentation:

```bash
cd docs
make html
```

## Citation

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

```bibtex
@software{roudane2025mtnardl,
  author = {Roudane, Merwan},
  title = {MTNARDL: Multiple Threshold Nonlinear ARDL Models for Python},
  year = {2025},
  url = {https://github.com/merwanroudane/mtnardl1},
  version = {1.0.0}
}
```

And the original methodology paper:

```bibtex
@article{pal2015asymmetric,
  title={Asymmetric impact of crude price on oil product pricing in the United States: An application of multiple threshold nonlinear autoregressive distributed lag model},
  author={Pal, Debdatta and Mitra, Subrata Kumar},
  journal={Economic Modelling},
  volume={51},
  pages={436--443},
  year={2015},
  publisher={Elsevier}
}
```

## References

- Pal, D., & Mitra, S. K. (2015). Asymmetric impact of crude price on oil product pricing in the United States: An application of multiple threshold nonlinear autoregressive distributed lag model. *Economic Modelling*, 51, 436-443.

- 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.

- 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.

## 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.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Support

For questions, issues, or suggestions:
- Open an issue on GitHub
- Email: merwanroudane920@gmail.com

## Changelog

### Version 1.0.0 (2025-01-28)
- Initial release
- Full implementation of ARDL, NARDL, and MTNARDL models
- Comprehensive statistical tests
- Publication-ready output
- Complete documentation and examples

---

**Made with ❤️ for econometrics research**
