Metadata-Version: 2.4
Name: qvar-model
Version: 0.1.0
Summary: Quantile Vector Autoregression: estimation, Granger causality, forecasting, and impulse responses
Author-email: "Dr. Merwan Roudane" <merwanroudane920@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/merwanroudane/QVAR
Project-URL: Repository, https://github.com/merwanroudane/QVAR
Project-URL: Issues, https://github.com/merwanroudane/QVAR/issues
Keywords: quantile regression,VAR,vector autoregression,Granger causality,stress testing,growth at risk,impulse response,econometrics,quantile forecasting,structural breaks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: scipy>=1.7
Requires-Dist: statsmodels>=0.13
Requires-Dist: matplotlib>=3.5
Requires-Dist: seaborn>=0.12
Requires-Dist: tabulate>=0.9
Dynamic: license-file

# QVAR — Quantile Vector Autoregression

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/badge/PyPI-v0.1.0-orange.svg)](https://pypi.org/project/qvar/)

A comprehensive Python library for **Quantile Vector Autoregression**: estimation, Granger causality testing with structural break detection, forecasting, stress testing, impulse response analysis, and publication-quality visualization.

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

---

## 📚 Theoretical Foundations

This library implements methods from six key research papers:

| Paper | Method | Module |
|-------|--------|--------|
| **Chavleishvili & Manganelli (2019)** *ECB WP 2330* | QVAR estimation, forecasting, stress testing | `core`, `forecasting` |
| **Mayer, Wied & Troster (2025)** *Journal of Econometrics* | Quantile Granger causality under instability | `granger` |
| **Carboni et al. (2024)** *ECB WP 3171* | VAR-QR Growth-at-Risk | `varqr` |
| **Surprenant (2025)** *Bank of Canada SWP* | QVAR forecast evaluation | `evaluation` |
| **White, Kim & Manganelli (2015)** *J. Econometrics* | MVMQ-CAViaR, QIRF foundations | `irf` |
| **Ando, Hoshino & Tsay (2026)** *arXiv* | Non-crossing QVAR (SQVAR) | *Phase 2* |

---

## 🚀 Installation

```bash
pip install qvar
```

Or install from source:
```bash
git clone https://github.com/merwanroudane/QVAR.git
cd QVAR
pip install -e .
```

---

## 📖 Quick Start

### QVAR Estimation

```python
import pandas as pd
from qvar import QuantileVAR

# Prepare data
data = pd.DataFrame({'Y1': y1_series, 'Y2': y2_series})

# Estimate QVAR(1) at multiple quantiles
model = QuantileVAR(lags=1, recursive=True)
results = model.fit(data, taus=[0.05, 0.25, 0.50, 0.75, 0.95])

# View publication-quality coefficient table
from qvar.tables import format_qvar_summary
print(format_qvar_summary(results))
```

### Quantile Granger Causality

```python
from qvar import QuantileGrangerCausality

# Test: does Z Granger-cause Y in quantiles?
gc = QuantileGrangerCausality(lags=1, n_bootstrap=499)
results = gc.test(y=dep, z=cause, detect_regimes=True)
print(results.summary())

# Visualize CUSUM process and detected regimes
from qvar.plotting import plot_cusum_process, plot_regime_gc
plot_cusum_process(results, process_type="exp")
plot_regime_gc(results, dep_name="GDP", cause_name="FinStress")
```

### Growth-at-Risk (VAR-QR)

```python
from qvar import VARQR

model = VARQR(var_lags=2, qr_lags=1, taus=[0.10, 0.50, 0.90])
results = model.fit(data)

# Time-varying conditional variance
sigma_t = results.conditional_variance()

# Simulate forecasts
fc = model.simulate_forecast(results, horizon=12)
```

### Quantile Impulse Responses

```python
from qvar import QuantileIRF

qirf = QuantileIRF(results)
irf = qirf.compute(shock_var="WTI", horizon=20, tau_path=[0.10]*20)
irf_multi = qirf.compute_across_quantiles(
    shock_var="WTI", taus_to_compare=[0.10, 0.50, 0.90]
)

from qvar.plotting import plot_qirf_fan, plot_qirf_across_quantiles
plot_qirf_fan(irf, response_var="GDP")
plot_qirf_across_quantiles(irf_multi, response_var="GDP")
```

### Forecast Evaluation

```python
from qvar.evaluation import qw_crps, diebold_mariano_test, coverage_test

scores_qvar = qw_crps(qvar_forecasts, actual, weight_fn="tails")
scores_var  = qw_crps(var_forecasts, actual, weight_fn="tails")

dm = diebold_mariano_test(scores_qvar, scores_var)
cov = coverage_test(lower_q, upper_q, actual, nominal_coverage=0.90)
```

---

## 🎨 Visualizations

The library produces beautiful, publication-ready charts with a curated color palette:

- **Coefficient heatmaps** across quantiles
- **CUSUM process** with structural break markers
- **Regime timelines** for Granger causality
- **Fan chart forecasts** with confidence bands
- **Quantile IRFs** — single and multi-quantile comparison
- **Growth-at-Risk** plots with tail risk markers

---

## 📊 Publication Tables

All output is formatted for direct inclusion in academic papers:

```python
from qvar.tables import format_results_table, format_granger_table

# LaTeX output
table = format_results_table(df, fmt="latex", title="Table 1: QVAR Coefficients")

# Console output with significance stars
table = format_granger_table(results_list, pairs, lags)
```

---

## 📁 Examples

| Example | Description |
|---------|-------------|
| `example_qvar_basic.py` | QVAR estimation, IRFs, forecasting, stress testing |
| `example_granger_causality.py` | Quantile GC test replicating Mayer et al. (2025) |
| `example_growth_at_risk.py` | VAR-QR model for Growth-at-Risk |
| `example_forecast_evaluation.py` | QVAR vs VAR-N comparison with DM tests |

Run any example:
```bash
python examples/example_qvar_basic.py
```

---

## 🔧 Dependencies

- `numpy >= 1.21`
- `pandas >= 1.3`
- `scipy >= 1.7`
- `statsmodels >= 0.13`
- `matplotlib >= 3.5`
- `seaborn >= 0.12`
- `tabulate >= 0.9`

---

## 📝 References

1. Chavleishvili, S. and Manganelli, S. (2019). *Forecasting and Stress Testing with Quantile Vector Autoregression*. ECB Working Paper 2330.
2. Mayer, A., Wied, D. and Troster, B. (2025). *Quantile Granger Causality in the Presence of Instability*. Journal of Econometrics, 249.
3. Carboni, G., Fonseca, L., Fornari, F. and Urrutia, A. (2024). *Structural Drivers of Growth at Risk*. ECB Working Paper 3171.
4. Surprenant, S. (2025). *Quantile VARs and Macroeconomic Risk Forecasting*. Bank of Canada Staff Working Paper 2025-4.
5. White, H., Kim, T.-H. and Manganelli, S. (2015). *VAR for VaR: Measuring Tail Dependence Using Multivariate Regression Quantiles*. Journal of Econometrics, 187.
6. Ando, T., Hoshino, T. and Tsay, R. (2026). *Quantile Vector Autoregression without Crossing*. arXiv:2601.04663v3.

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.

## 🤝 Contributing

Contributions welcome! Please open an issue or pull request at [GitHub](https://github.com/merwanroudane/QVAR).
