# 105. Electricity demand planning

**Owner: Djellon Pllana.** Independently built portfolio case study using historical public observations. No employment by, or partnership with, the source organizations is claimed.

## Business question

How reliably can a household energy planner forecast the next day while preserving missing meter readings and uncertainty?

## Executive result

Across 7,608 complete test hours, MAE is 0.451 kWh, only 1.2% below the selected baseline. The nominal 90% interval covers 87.9% of test hours.

The day-bootstrap interval for the MAE advantage crosses zero. These results do not establish that the more complex model is preferable to the simple baseline.

![Computed analysis](outputs/chart.png)

## Scope and architecture

2,075,259 original observations. Original files → hashed source manifest → typed transformations and SQL marts → chronological experiments → executed notebook → aggregate interactive dashboard.

1. Ingest the original minute observations and record source provenance.
2. Convert minute-average kW to kWh; accept hourly targets only with all 60 readings.
3. Create features from prior days available before each forecast midnight.
4. Train in 2007–2008, select in early 2009, calibrate in late 2009, and test in 2010.
5. Report error, missing-hour coverage and interval coverage separately; expose tariff assumptions.

## Data contract

One source row is a minute clock observation. An observed minute contributes Global_active_power / 60 kWh. Hourly energy is a valid target only if 60 readings exist; partial sums remain separately identified observed energy. The complete source calendar contains missing measurements. At midnight the model forecasts all hours of the coming day from finalized prior-day readings; no contemporaneous meter or weather measurement enters the predictors.

## Model and evaluation

A fixed gradient-boosting regressor is compared to previous-day, previous-week and prior-seven-day same-hour baselines. January–June 2009 MAE selects the baseline and model size. July–December 2009 absolute residuals calibrate a nominal 90% interval with a finite-sample quantile; the lower bound is clipped at zero. January–November 2010 remains untouched for testing. All target hours need complete measurements. Coverage is empirical, not a guarantee. The bootstrap uses calendar-day clusters, not independent hours.

See [evaluation.json](outputs/evaluation.json), [results.csv](outputs/results.csv) and [quality.json](outputs/quality.json). Test observations are not used to choose configurations. Results are from the current historical evaluation; additional tuning requires a new evaluation period.

## Recommended next decision

Retain the simple baseline unless a new evaluation establishes a useful operational gain. Investigate missing readings and seasonal interval coverage before a monitored forecasting pilot. Use tariff scenarios only with explicitly supplied rates.

## Limitations

This is one historical household, not a utility fleet or current tariff study. Local timestamps lack DST/UTC disambiguation. Incomplete hours are unknown and excluded from scoring. Time dependence undermines exchangeability assumptions behind residual bands. The paired day bootstrap does not preserve dependence between adjacent days. Illustrative tariff comparisons are arithmetic scenarios and show no demand-shifting savings.

## Reproduce

From the full project-collection root, use Python 3.12 and install `capstones/requirements.txt`. Run `python projects/105-electricity-demand-planning/analysis.py` or execute this project's notebook. Raw files are fetched from the original publisher, hashed and cached in `data/raw/capstones`. The full NYC run reads over 200 MB of compressed source data and needs several GB of working memory and disk. The website carries aggregated results rather than raw trip logs or trained model binaries.

The project Python file exposes the full study code. Shared helpers live in `capstones/common.py`; source downloads are declared in `capstones/fetch.py`; the native NYC Power BI companion is generated with `python -m capstones.bi`.

## Source and attribution

[Individual household electric power consumption](https://archive.ics.uci.edu/dataset/235/individual+household+electric+power+consumption) — Georges Hebrail and Alice Berard; UCI dataset 235. [Reuse information](https://creativecommons.org/licenses/by/4.0/). Data were transformed and aggregated for this study; see `data/source_manifest.json` for exact source files and hashes.