MTNARDL: Multiple Threshold Nonlinear ARDL Models for Python

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

pip install mtnardl1

For development installation:

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

Quick Start

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

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

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

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

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

# 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

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

# 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

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

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:

cd examples
python example_replication.py

Testing

Run the test suite:

pytest tests/ -v --cov=mtnardl1

Documentation

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

cd docs
make html

Citation

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

@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:

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