Metadata-Version: 2.4
Name: qardl
Version: 1.0.5
Summary: Quantile Autoregressive Distributed Lag (QARDL) Models - GAUSS/MATLAB Compatible
Author-email: "Dr. Merwan Roudane" <merwanroudane920@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/merwanroudane/qardl
Project-URL: Documentation, https://github.com/merwanroudane/qardl#readme
Project-URL: Bug Tracker, https://github.com/merwanroudane/qardl/issues
Keywords: econometrics,quantile regression,cointegration,ARDL,time series,QARDL
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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 :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

# QARDL - Quantile Autoregressive Distributed Lag Models

**Version 1.0.3** - GAUSS/MATLAB Compatible Implementation

Exact Python implementation of the QARDL methodology from:

> Cho, J.S., Kim, T.-H., & Shin, Y. (2015). Quantile cointegration in the autoregressive distributed-lag modeling framework. *Journal of Econometrics*, 188(1), 281-300.

## Features

- ✅ **GAUSS Compatible**: Design matrix construction matches original GAUSS `qardl.src` exactly
- ✅ **Correct Long-run Formula**: β = θ₀ / (1 - Σφ) using only current X coefficient
- ✅ **Proper Wald Tests**: Exact scaling factors `(n-1)²` for long-run, `(n-1)` for short-run
- ✅ **ECM Representation**: MATLAB `qardlecm.m` compatible Error Correction Model
- ✅ **Rolling Estimation**: `rollingQardl` with Wald tests at each window
- ✅ **Simulation**: `qardlAR2Sim` for Monte Carlo experiments
- ✅ **Plotting**: `plotQARDL` equivalent visualization
- ✅ **BIC Lag Selection**: Automatic optimal (p, q) selection

## Installation

```bash
pip install qardl
```

Or from source:

```bash
pip install -e .
```

## Quick Start

```python
import numpy as np
from qardl import qardl, QARDL, pq_order

# Prepare data: [y | X1 | X2 | ...]
data = np.column_stack([y, X])

# Select optimal lag orders
p_opt, q_opt = pq_order(data, p_max=7, q_max=7)
print(f"Optimal lags: p={p_opt}, q={q_opt}")

# Estimate QARDL model
tau = np.array([0.10, 0.25, 0.50, 0.75, 0.90])
qaOut = qardl(data, p_opt, q_opt, tau)

# Results
print("Long-run β:", qaOut.bigbt)
print("Short-run φ:", qaOut.phi)
print("Short-run γ:", qaOut.gamma)
print(qaOut.summary())
```

## Wald Tests

```python
from qardl import wtestlrb, wtestsrp, wtestsrg

# Define restrictions: R * β = r
# Example: Test β₁(τ₁) = β₁(τ₂)
R = np.zeros((1, len(qaOut.bigbt)))
R[0, 0] = 1   # β₁(τ₁)
R[0, k] = -1  # β₁(τ₂)
r = np.zeros(1)

# Long-run parameter test (uses (n-1)² scaling)
wt, pv = wtestlrb(qaOut.bigbt, qaOut.bigbt_cov, R, r, data)
print(f"Wald statistic: {wt:.4f}, p-value: {pv:.4f}")

# Short-run tests (use (n-1) scaling)
wt_phi, pv_phi = wtestsrp(qaOut.phi, qaOut.phi_cov, R_phi, r_phi, data)
wt_gam, pv_gam = wtestsrg(qaOut.gamma, qaOut.gamma_cov, R_gam, r_gam, data)
```

## Rolling QARDL Estimation

```python
from qardl import rolling_qardl, create_wald_restrictions

# Create Wald test restrictions
tau = np.array([0.25, 0.50, 0.75])
wctl = create_wald_restrictions(k=2, p_max=7, num_tau=len(tau))

# Run rolling estimation
rqaOut = rolling_qardl(data, p_max=7, q_max=7, tau=tau, wctl=wctl)

# Results
print(f"Window size: {rqaOut.window_size}")
print(f"Beta array shape: {rqaOut.bigbt.shape}")  # (k x num_est x num_tau)

# Get specific estimates
beta1_05 = rqaOut.get_beta(var_idx=0, tau_idx=1)  # β₁(τ=0.5)

# Wald test results
print("Wald beta:", rqaOut.rWaldOut.wald_beta)
```

## ECM Representation

```python
from qardl import qardl_ecm, QARDLECM

# Direct ECM estimation
ecmOut = qardl_ecm(data, p, q, tau)

# Results
print("Adjustment speed (ζ):", ecmOut.zeta)
print("Long-run β:", ecmOut.beta)
print("Half-life:", ecmOut.get_half_life(0))  # For first quantile
```

## Simulation

```python
from qardl import qardl_ar2_sim, DGPParams, simulate_wald_tests

# Generate QARDL data (matches GAUSS qardlAR2Sim)
y, X = qardl_ar2_sim(n=500, alpha=1.0, phi=0.25, rho=0.5, 
                      theta0=2.0, theta1=3.0, seed=42)

# With custom parameters
params = DGPParams(alpha=1.0, phi=0.25, theta0=2.0, theta1=3.0)
print(f"Long-run β = {params.beta:.4f}")

# Monte Carlo simulation for Wald test size
results = simulate_wald_tests(n=500, n_iter=1000, p=1, q=2, 
                               tau=np.array([0.2, 0.4, 0.6, 0.8]))
```

## Plotting

```python
from qardl import plot_qardl, plot_beta, plot_rolling

# Plot all parameters
fig = plot_qardl(qaOut)
plt.show()

# Plot with confidence intervals
fig = plot_beta(qaOut, with_ci=True, alpha=0.05)
plt.show()

# Plot rolling results
fig = plot_rolling(rqaOut, var_idx=0, tau_idx=1, param_type='beta')
plt.show()
```

## Design Matrix Structure

The design matrix follows GAUSS ordering exactly:

```
ONEX = [1 | eei | xxi | yyi]
```

Where:
- `1`: Intercept
- `eei`: Lagged first differences of X (Δx_{t}, Δx_{t-1}, ..., Δx_{t-q+1})
- `xxi`: Current levels of X (x_t)
- `yyi`: Lagged dependent variable (y_{t-1}, ..., y_{t-p})

## Complete Function Reference

### Core Estimation
| Function | Description | GAUSS Equivalent |
|----------|-------------|------------------|
| `qardl(data, p, q, tau)` | Main QARDL estimation | `qardl()` |
| `QARDL` class | OOP interface | - |
| `pq_order(data, p_max, q_max)` | BIC lag selection | `pqorder()` |

### Wald Tests
| Function | Description | GAUSS Equivalent |
|----------|-------------|------------------|
| `wtestlrb()` | Long-run β test | `wtestlrb.src` |
| `wtestsrp()` | Short-run φ test | `wtestsrp.src` |
| `wtestsrg()` | Short-run γ test | `wtestsrg.src` |

### Rolling Estimation
| Function | Description | GAUSS Equivalent |
|----------|-------------|------------------|
| `rolling_qardl()` | Rolling window estimation | `rollingQardl()` |
| `create_wald_restrictions()` | Create restriction matrices | - |

### ECM
| Function | Description | MATLAB Equivalent |
|----------|-------------|-------------------|
| `qardl_ecm()` | ECM estimation | `qardlecm.m` |
| `convert_qardl_to_ecm()` | Convert QARDL to ECM params | - |

### Simulation
| Function | Description | GAUSS Equivalent |
|----------|-------------|------------------|
| `qardl_ar2_sim()` | Generate QARDL data | `qardlAR2Sim()` |
| `generate_qardl_data()` | Flexible data generation | - |
| `simulate_wald_tests()` | Monte Carlo simulation | `wald_tests_sim.e` |

### Plotting
| Function | Description | GAUSS Equivalent |
|----------|-------------|------------------|
| `plot_qardl()` | Plot all parameters | `plotQARDL()` |
| `plot_beta()` | Plot long-run with CI | `plotBetaGraphs()` |
| `plot_gamma()` | Plot short-run γ | `plotGammaGraphs()` |
| `plot_phi()` | Plot AR φ | `plotPhiGraphs()` |
| `plot_rolling()` | Plot rolling results | - |

## Output Structure (matches GAUSS)

| Output | Description | Dimension |
|--------|-------------|-----------|
| `bigbt` | Long-run parameters β | (k×s) × 1 |
| `bigbt_cov` | Covariance of β | (k×s) × (k×s) |
| `phi` | Short-run AR parameters φ | (p×s) × 1 |
| `phi_cov` | Covariance of φ | (p×s) × (p×s) |
| `gamma` | Short-run impact parameters γ | (k×s) × 1 |
| `gamma_cov` | Covariance of γ | (k×s) × (k×s) |

Where `k` = number of X variables, `s` = number of quantiles, `p` = AR order.

## Citation

If you use this package, please cite:

```bibtex
@article{cho2015quantile,
  title={Quantile cointegration in the autoregressive distributed-lag modeling framework},
  author={Cho, Jin Seo and Kim, Tae-hwan and Shin, Yongcheol},
  journal={Journal of Econometrics},
  volume={188},
  number={1},
  pages={281--300},
  year={2015},
  publisher={Elsevier}
}
```

## Author

**Dr. Merwan Roudane**  
Email: merwanroudane920@gmail.com

## License

MIT License
