Publish org-ready clean-main with docs layout and packaging.

Reorganize LaTeX report and slides under docs/, add pyproject.toml,
CITATION.cff, CI workflow, and a professional README for CttQuantLab.

Author: ctt062

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main, clean-main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          pip install -r requirements.txt
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+venv/
+.env
+.env.*
+
+# Notebooks
+.ipynb_checkpoints/
+*.nbconvert.ipynb
+
+# Data caches
+/data/raw/
+*.parquet
+*.csv
+*.feather
+
+# Logs
+*.log
+
+# LaTeX build artifacts
+*.aux
+*.nav
+*.out
+*.snm
+*.toc
+*.vrb
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+*.bbl
+*.blg
+
+# IDE / OS
+.DS_Store
+.cursor/
+.pytest_cache/

CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: If you use this software, please cite it as below.
+title: "Quantifying VIX Tail Risk: Volatility Clustering and Jump Processes"
+authors:
+  - family-names: Chandrean
+    given-names: Vittorio Prana
+  - family-names: Chong
+    given-names: Tin Tak
+  - family-names: Choi
+    given-names: Man Hou
+version: 1.0.0
+date-released: "2025-12-17"
+license: MIT
+repository-code: https://github.com/CttQuantLab/Quantifying-VIX-Tail-Risk
+url: https://github.com/CttQuantLab/Quantifying-VIX-Tail-Risk
+abstract: >-
+  Comparative study of GARCH-family volatility models and Compound Poisson
+  jump processes for VIX tail-risk quantification, including regime analysis
+  and out-of-sample VaR/CVaR evaluation.
+keywords:
+  - VIX
+  - GARCH
+  - compound Poisson
+  - tail risk
+  - quantitative finance
+  - volatility clustering

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tin Tak (Douglas) CHONG 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,155 @@
+# Quantifying VIX Tail Risk
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Org](https://img.shields.io/badge/org-CttQuantLab-0B3D91.svg)](https://github.com/CttQuantLab)
+
+Research codebase comparing GARCH-family volatility models and Compound Poisson Process (CPP) jump models for VIX tail-risk quantification.
+The pipeline fits EGARCH/GARCH on daily VIX log changes, identifies shock events, models arrival rates and jump magnitudes, and evaluates VaR/CVaR with regime and out-of-sample checks.
+
+Developed for **IEDA4000E - Statistical Modelling for Financial Engineering** at the Hong Kong University of Science and Technology (HKUST).
+Maintained under [CttQuantLab](https://github.com/CttQuantLab).
+
+> **Not financial advice.** This repository is for research and education only.
+> Historical results do not imply future performance.
+
+## Highlights
+
+- GARCH(1,1) and EGARCH(1,1) with automatic GED/t/normal selection via PIT diagnostics
+- Shock identification by quantile and volatility-relative thresholds
+- Homogeneous and Hawkes arrival models plus Compound Poisson jump-risk estimation
+- Regime analysis across pre-COVID, COVID, post-COVID, and recent windows
+- Out-of-sample CPP forecast evaluation (2022-2025 holdout)
+- Reproducible pipeline (`runall.py`), notebooks, tests, report, and slides
+
+### Headline results
+
+| Model / metric | Value | Notes |
+|----------------|-------|-------|
+| Best volatility fit | EGARCH(1,1), GED | AIC 27,395 vs GARCH 27,531 |
+| Volatility half-life | 10.2 days | EGARCH persistence 0.934 |
+| CPP arrival rate | 12.64 / year | Full-sample Poisson rate |
+| CPP VaR (95%) | 4.24 | Annual cumulative shock impact |
+| CPP CVaR (95%) | 5.01 | Expected shortfall |
+| OOS forecast error | -17.8% | 2022-2025; VaR not exceeded |
+
+Full tables and discussion: [`docs/SUMMARY.md`](docs/SUMMARY.md), [`docs/report/report.pdf`](docs/report/report.pdf).
+
+## Repository layout
+
+```text
+.
+├── docs/
+│   ├── SUMMARY.md           # Results digest
+│   ├── report/              # Academic report (LaTeX + PDF)
+│   └── slides/              # Beamer presentation (LaTeX + PDF)
+├── figures/                 # Published plots by category
+├── notebooks/               # Step-by-step analysis notebooks
+├── src/                     # Core library modules
+├── tests/                   # Pytest suite
+├── runall.py                # End-to-end pipeline driver
+├── requirements.txt
+├── pyproject.toml
+└── LICENSE
+```
+
+## Quick start
+
+```bash
+git clone https://github.com/CttQuantLab/Quantifying-VIX-Tail-Risk.git
+cd Quantifying-VIX-Tail-Risk
+
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+pip install -U pip
+pip install -r requirements.txt
+pip install -e .
+
+pytest -q
+```
+
+## Run the pipeline
+
+Download VIX data (Yahoo Finance), fit models, and regenerate figures:
+
+```bash
+python runall.py
+```
+
+Optional flags:
+
+```bash
+python runall.py --force-download   # refresh cached VIX history
+python runall.py --skip-plots       # models only, no figure export
+```
+
+Outputs land under `figures/` (grouped by topic) and cached data under `data/raw/`.
+
+## Data
+
+- **Source:** Yahoo Finance `^VIX` daily closes
+- **Window:** 2010-01-05 to latest available (4,100+ business days in the published run)
+- **Preprocessing:** business-day alignment, forward-fill, 0.1% winsorization, log-level and log-change features
+- **Train/test split:** 75% train (2010-2021), 25% test (2022-2025) for forecast evaluation
+
+## Method sketch
+
+**Volatility.** GARCH and EGARCH on daily log VIX changes; distribution chosen by PIT Kolmogorov-Smirnov fit.
+
+**Shocks.** Threshold exceedances on standardized returns; inter-arrival times fit to Poisson and Hawkes processes.
+
+**Jump risk.** Compound Poisson accumulation \(S(T)=\sum_{i=1}^{N(T)} J_i\) with Pareto jump sizes; Monte Carlo paths for VaR/CVaR.
+
+See the report for full equations, parameter tables, and diagnostic figures.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [`docs/SUMMARY.md`](docs/SUMMARY.md) | Condensed results and regime tables |
+| [`docs/report/report.pdf`](docs/report/report.pdf) | Full academic write-up |
+| [`docs/slides/slides.pdf`](docs/slides/slides.pdf) | Presentation deck |
+| [`figures/`](figures/) | Standalone result figures |
+
+## Development
+
+```bash
+pytest -q
+pip install -e ".[dev]"
+```
+
+Random seeds default to `42` in `src/config.py`.
+
+## Citation
+
+If this repository is useful for your work, please cite the course project report and link this repository:
+
+```bibtex
+@misc{chong2025vixtailrisk,
+  author       = {Chandrean, Vittorio Prana and Chong, Tin Tak and Choi, Man Hou},
+  title        = {Quantifying VIX Tail Risk: Volatility Clustering and Jump Processes},
+  year         = {2025},
+  howpublished = {\url{https://github.com/CttQuantLab/Quantifying-VIX-Tail-Risk}},
+  note         = {IEDA4000E course project, HKUST}
+}
+```
+
+See also [`CITATION.cff`](CITATION.cff) for machine-readable metadata.
+
+## References
+
+1. Bollerslev, T. (1986). Generalized Autoregressive Conditional Heteroskedasticity. *Journal of Econometrics*.
+2. Nelson, D. B. (1991). Conditional Heteroskedasticity in Asset Returns. *Econometrica*.
+3. Cont, R., and Tankov, P. (2004). *Financial Modelling with Jump Processes*. Chapman and Hall/CRC.
+4. McNeil, A. J., Frey, R., and Embrechts, P. (2015). *Quantitative Risk Management*. Princeton University Press.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+- Course: IEDA4000E - Statistical Modelling for Financial Engineering, HKUST
+- Authors: Vittorio Prana CHANDREAN, CHONG Tin Tak, CHOI Man Hou
+- Core stack: arch, statsmodels, pandas, scipy, matplotlib, yfinance