QVAR — Quantile Vector Autoregression

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:

🚀 Installation

pip install qvar

Or install from source:

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

📖 Quick Start

QVAR Estimation

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

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)

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

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

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:

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

Run any example:

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 for details.

🤝 Contributing

Contributions welcome! Please open an issue or pull request at GitHub.