rals-unitroot 1.1.0

RALS Unit Root Tests: More Powerful Unit Root Tests with Non-Normal Errors

RALS Unit Root Tests

A comprehensive Python library implementing Residual Augmented Least Squares (RALS) unit root tests with and without structural breaks. These tests provide significantly improved power over traditional unit root tests when errors deviate from normality.

📚 Overview

This library implements three main unit root tests:

1. RALS-ADF - RALS Augmented Dickey-Fuller test (Im et al., 2014)
2. RALS-LM - RALS Lagrange Multiplier test (Meng et al., 2014)
3. RALS-LM with Breaks - RALS-LM test with structural breaks (Meng et al., 2014, 2017)

Key Features

• ✅ Improved Power: Significantly higher power than traditional tests when errors are non-normal
• ✅ Non-normal Errors: Utilizes information from second and third moments of residuals
• ✅ Structural Breaks: Support for endogenous break detection (1 or 2 breaks)
• ✅ Publication-Ready Output: Formatted results suitable for academic publications
• ✅ Critical Values: Comprehensive tables from the original papers
• ✅ Easy to Use: Simple API matching the original GAUSS implementation

📦 Installation

pip install rals-unitroot

Or install from source:

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

🚀 Quick Start

RALS-ADF Test

import numpy as np
from rals_unitroot import rals_adf

# Generate sample data (random walk)
np.random.seed(42)
y = np.cumsum(np.random.randn(200))

# Run RALS-ADF test with constant
result = rals_adf(y, model=1)

# Access results
print(f"Test Statistic: {result.statistic:.4f}")
print(f"Rho-squared: {result.rho2:.4f}")
print(f"Critical Values (1%, 5%, 10%): {result.critical_values}")
print(f"Conclusion: {'Reject H0' if result.is_significant_5pct else 'Cannot reject H0'}")

RALS-LM Test

from rals_unitroot import rals_lm

# Run RALS-LM test
result = rals_lm(y, pmax=8, ic=3)

# Print formatted summary
print(result.summary())

RALS-LM Test with Structural Breaks

from rals_unitroot import rals_lm_breaks

# Generate data with a structural break
np.random.seed(42)
T = 200
y = np.cumsum(np.random.randn(T))
y[100:] += 5  # Add level shift at t=100

# Run test with 1 level break
result = rals_lm_breaks(y, model=1, nbreaks=1)

print(f"Break location: {result.breaks[0]}")
print(f"Break fraction: {result.break_fractions[0]:.4f}")

📖 Detailed Documentation

RALS-ADF Function

rals_adf(y, model=1, pmax=8, ic=3, print_results=True)

Parameters:

• y: Time series data (numpy array)
• model: 1 = Constant only, 2 = Constant and trend
• pmax: Maximum lag order (default: 8)
• ic: Information criterion (1=AIC, 2=BIC, 3=t-stat, default: 3)
• print_results: Print formatted output (default: True)

Returns: RALSResult object with:

• statistic: RALS-ADF test statistic
• rho2: Estimated ρ² value
• critical_values: Critical values at 1%, 5%, 10%
• lags: Selected lag order
• nobs: Number of observations

RALS-LM Function

rals_lm(y, pmax=8, ic=3, print_results=True)

Parameters:

• y: Time series data
• pmax: Maximum lag order (default: 8)
• ic: Information criterion (default: 3)
• print_results: Print formatted output

RALS-LM with Breaks Function

rals_lm_breaks(y, model, nbreaks, pmax=8, ic=3, trimm=0.10, print_results=True)

Parameters:

• y: Time series data
• model: 1 = Level break, 2 = Level and trend break
• nbreaks: Number of breaks (1 or 2)
• pmax: Maximum lag order (default: 8)
• ic: Information criterion (default: 3)
• trimm: Trimming rate (default: 0.10)

📊 Model Specifications

Model 1: Constant Only

y_t = μ + β*y_{t-1} + Σδ_j*Δy_{t-j} + e_t

Model 2: Constant and Trend

y_t = μ + δ*t + β*y_{t-1} + Σδ_j*Δy_{t-j} + e_t

RALS Augmentation

The RALS procedure augments the testing regression with:

w_t = (e_t² - m₂, e_t³ - m₃ - 3*m₂*e_t)

where m_j = (1/T) * Σe_t^j for j = 2, 3.

📈 Simulation Functions

The library includes functions for Monte Carlo simulation:

from rals_unitroot import power_simulation, size_simulation

# Simulate power under the alternative
power = power_simulation(T=200, rho=0.9, n_rep=5000, 
                         model=1, test_type='adf', 
                         error_dist='chi2')
print(f"Power at 5%: {power['5%']:.3f}")

# Simulate size under the null
size = size_simulation(T=200, n_rep=5000, 
                       model=1, test_type='adf')
print(f"Empirical size at 5%: {size['5%']:.3f}")

📋 Critical Values

Critical values are based on the original papers. The library includes:

Standard Tests (RALS-ADF, RALS-LM)

• Asymptotic critical values (T → ∞)
• Finite sample critical values for T = 25, 50, 100
• Hansen (1995) interpolation for ρ² values (0.1 to 1.0)

LM Tests with Structural Breaks

• Response Surface Estimates (Nazlioglu & Lee, 2020): Finite sample critical values accounting for sample size (T) and lag order (p) for up to 3 trend breaks
• RALS-LM with Breaks (Meng et al., 2017): Complete critical value tables for T = 50, 100, 300, 1000 and ρ² from 0 to 1.0

Response Surface Function

The LM test critical values use the response surface formula from Nazlioglu & Lee (2020):

CV(T,p) = α∞ + α₁/T + α₂/T² + β₁(p/T) + β₂(p/T)²

This accounts for both sample size and lag order effects in finite samples.

📚 References

1. Im, K.S., Lee, J., & Tieslau, M.A. (2014). More powerful unit root tests with non-normal errors. In Festschrift in Honor of Peter Schmidt (pp. 315-342). Springer New York.

2. Meng, M., Im, K.S., Lee, J., & Tieslau, M.A. (2014). More powerful LM unit root tests with non-normal errors. In Festschrift in Honor of Peter Schmidt (pp. 343-357). Springer New York.

3. Meng, M., Lee, J., & Payne, J.E. (2017). RALS-LM unit root test with trend breaks and non-normal errors: application to the Prebisch-Singer hypothesis. Studies in Nonlinear Dynamics & Econometrics, 21(1), 31-45.

4. Nazlioglu, S., Lee, J. (2020). Response Surface Estimates of the LM Unit Root Tests. Economics Letters, Vol. 192, Article 109136.

5. Hansen, B.E. (1995). Rethinking the univariate approach to unit root testing: using covariates to increase power. Econometric Theory, 11, 1148-1171.

6. Lee, J. & Strazicich, M.C. (2003). Minimum Lagrange multiplier unit root test with two structural breaks. Review of Economics and Statistics, 85, 1082-1089.

🧪 Testing

Run the test suite:

pytest tests/ -v

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Dr. Merwan Roudane

• Email: [e-mail]
• GitHub: https://github.com/merwanroudane/rals

🤝 Contributing

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

📝 Citation

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

@software{roudane2024rals,
  author = {Roudane, Merwan},
  title = {RALS Unit Root Tests: A Python Library for More Powerful Unit Root Testing},
  year = {2024},
  url = {https://github.com/merwanroudane/rals}
}

And the original papers:

@incollection{im2014powerful,
  title={More powerful unit root tests with non-normal errors},
  author={Im, Kyung So and Lee, Junsoo and Tieslau, Margie A},
  booktitle={Festschrift in Honor of Peter Schmidt},
  pages={315--342},
  year={2014},
  publisher={Springer}
}

@incollection{meng2014powerful,
  title={More powerful LM unit root tests with non-normal errors},
  author={Meng, Ming and Im, Kyung So and Lee, Junsoo and Tieslau, Margie A},
  booktitle={Festschrift in Honor of Peter Schmidt},
  pages={343--357},
  year={2014},
  publisher={Springer}
}

@article{meng2017rals,
  title={RALS-LM unit root test with trend breaks and non-normal errors: application to the Prebisch-Singer hypothesis},
  author={Meng, Ming and Lee, Junsoo and Payne, James E},
  journal={Studies in Nonlinear Dynamics \& Econometrics},
  volume={21},
  number={1},
  pages={31--45},
  year={2017},
  publisher={De Gruyter}
}

@article{nazlioglu2020response,
  title={Response surface estimates of the LM unit root tests},
  author={Nazlioglu, Saban and Lee, Junsoo},
  journal={Economics Letters},
  volume={192},
  pages={109136},
  year={2020},
  publisher={Elsevier}
}