Risk-Aware Building Control with Quantile Patch Transformers (QR‑PatchTST)

Probabilistic short‑term load forecasting for whole‑building energy using a Quantile Regression Patch Transformer (QR‑PatchTST), followed by a validation of risk‑aware supervisory control that acts on the upper prediction bound (Q90) to mitigate peak events. The repository includes a fully reproducible Jupyter notebook, a rendered HTML version, and aggregated floor‑level datasets for a seven‑story office building (CU‑BEMS—Chamchuri 5, Bangkok).

TL;DR: Median MAE ≈ 24.06 kWh; 80% PI coverage (PICP) ≈ 83.26% with mean width ≈ 70.28 kWh. Using Q90 for control reduces critical missed peaks by ~73.3% compared with a standard median‑based controller (60 → 16).

---

Why this project

Building operators need forecasts with uncertainty, not just point estimates. This project implements a Transformer‑based quantile regression model that outputs Q10/Q50/Q90 and demonstrates how the upper bound (Q90) can drive a safer, risk‑aware peak‑mitigation strategy. Beyond metrics, it quantifies decision trade‑offs with a contingency analysis and a focused critical‑event case study.

---

Repository structure

.
├── QR-PatchTST.ipynb          # Full pipeline: data → model → evaluation → control
├── QR-PatchTST.html           # Rendered notebook for quick reading
├── dataset/                   # Aggregated floor CSVs (hourly kWh)
│   ├── Floor1.csv
│   ├── Floor2.csv
│   ├── Floor3.csv
│   ├── Floor4.csv
│   ├── Floor5.csv
│   ├── Floor6.csv
│   └── Floor7.csv
├── requirements.txt           # Pip environment (see below)
├── environment.yml            # Conda environment (optional)
├── LICENSE                    # MIT License
└── README.md

Large data? This repo recommends Git LFS for *.csv files (instructions below).

---

Results (1‑hour ahead, single‑step forecast)

Metric	Value
RMSE (kWh)	55.18
MAE (kWh)	24.06
PICP (80% PI)	83.26%
MPIW (kWh)	70.28

Control validation (threshold = 650 kWh)

Controller	True Positives	False Positives	False Negatives	Total Alerts
Standard (Median/Q50)	44	32	60	76
Risk‑Aware (Upper/Q90)	88	216	16	304

Key takeaway: the risk‑aware controller halves missed peaks (−73.3%) at the cost of more false alarms—appropriate for high‑stakes peak avoidance.

---

Data

• Source: CU‑BEMS (Chamchuri 5 building, Bangkok), originally minute‑level data aggregated to hourly kWh and summed across seven floors to create the whole‑building target series.
• Files: dataset/Floor1.csv … dataset/Floor7.csv.
• Attribution: Please cite CU‑BEMS in any publications and comply with the dataset’s license/terms.

Git LFS (recommended for CSVs)

git lfs install
git lfs track "*.csv"
git add .gitattributes

---

Modeling at a glance

• Architecture: Patch‑wise Transformer encoder (PatchTST style) with positional encoding; final dense head outputs [Q10, Q50, Q90] in one pass.
• Loss: multi‑quantile pinball loss.
• Look‑back window: 24 hours → predict t+1 hour.
• Features: cyclic encodings for Hour/DayOfWeek/WeekOfYear/Month; weekend and holiday flags; autoregressive target (Building_Total_kWh).
• Data hygiene: chronological split; scalers fitted only on train; IsolationForest outlier capping derived from train and applied consistently to test (prevents leakage).
• Tuning: Bayesian Optimization (KerasTuner) over patch length, d_model, attention heads, number of encoder blocks, dropout, and learning rate.
• Best configuration (from search): patch_len=2, d_model=128, num_heads=8, num_blocks=1, dropout=0.2, learning_rate=5e-4.
• Reproducibility: seeds set for TensorFlow and NumPy (42).

---

Reproducing the figures

All figures are generated by the notebook:

• Forecast bands: Q50 and 80% PI (Q10–Q90) over a representative month.
• Uncertainty analysis: interval width over time; boxplot of width by hour of day.
• Control case study: highlights when Q90 exceeds the 650 kWh threshold while Q50 does not (critical risk detection).
• Contingency analysis: normalized confusion matrices for Standard vs. Risk‑Aware controllers.

---

Quickstart

1) Clone

git clone https://github.com/mnikoopayan/quantile-patch-transformers.git
cd quantile-patch-transformers

2) Environment (choose one)

Pip

python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Conda

conda env create -f environment.yml
conda activate qr-patchtst

Apple Silicon acceleration (optional)

pip install tensorflow-macos tensorflow-metal

3) Run

jupyter lab   # or: jupyter notebook

Open QR-PatchTST.ipynb and run all cells. The HTML file (QR-PatchTST.html) provides a quick read‑only view.

---

Minimal environments

requirements.txt

numpy
pandas
matplotlib
seaborn
scikit-learn
tensorflow>=2.14
keras-tuner

environment.yml

name: qr-patchtst
channels: [conda-forge]
dependencies:
  - python=3.10
  - numpy
  - pandas
  - matplotlib
  - scikit-learn
  - seaborn
  - pip
  - pip:
      - tensorflow>=2.14
      - keras-tuner

---

How to cite

If you build on this code or ideas, please cite the accompanying work (update venue as appropriate):

Nikoopayan Tak, M. S., Ghosh, A., Leverett, F., Moazami Goodarzi, R., & Feng, Y. (2025).
Risk-Aware Building Control: A Probabilistic Forecasting Framework Using Quantile Patch Transformers.

Also cite CU‑BEMS if you use the dataset.

---

License

This project is released under the MIT License. See LICENSE for details.

---

Acknowledgments

• CU‑BEMS dataset contributors and maintainers.
• PatchTST and the broader time‑series Transformers community.
• Open‑source libraries: NumPy, pandas, Matplotlib, scikit‑learn, TensorFlow, Keras‑Tuner, and Seaborn.

Live Demo

GitHub Pages: https://mnikoopayan.github.io/quantile-patch-transformers/