Metadata-Version: 2.4
Name: rals-unitroot
Version: 1.1.0
Summary: RALS Unit Root Tests: More Powerful Unit Root Tests with Non-Normal Errors
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/rals
Project-URL: Repository, https://github.com/merwanroudane/rals
Project-URL: Documentation, https://github.com/merwanroudane/rals#readme
Project-URL: Bug Tracker, https://github.com/merwanroudane/rals/issues
Keywords: unit root,RALS,econometrics,time series,stationarity,ADF test,LM test,structural breaks,non-normal errors,hypothesis testing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
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 :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: numpydoc>=1.5.0; extra == "docs"
Provides-Extra: all
Requires-Dist: rals-unitroot[dev,docs]; extra == "all"
Dynamic: license-file

# RALS Unit Root Tests

[![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)
[![PyPI version](https://badge.fury.io/py/rals-unitroot.svg)](https://badge.fury.io/py/rals-unitroot)

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

```bash
pip install rals-unitroot
```

Or install from source:

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

## 🚀 Quick Start

### RALS-ADF Test

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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:

```python
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:

```bash
pytest tests/ -v
```

## 📄 License

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

## 👤 Author

**Dr. Merwan Roudane**
- Email: merwanroudane920@gmail.com
- GitHub: [https://github.com/merwanroudane/rals](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:

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

```bibtex
@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}
}
```
