GridWatch CA

GridWatch CA is an AI audit system for CAISO's publicly submitted day-ahead demand forecasts in DOE/EIA hourly grid data. Instead of presenting another generic load forecaster, it asks: when does the official forecast fail, how large is the operational risk, and what grid context appears around the miss?

The project learns a residual correction model for actual_demand_mw - official_forecast_mw, but the correction is one part of a broader reliability audit. The dashboard separates forecast misses from likely source-data anomalies and connects major misses to demand regimes, fuel mix, interchange, and ramp context.

What It Shows

• Official forecast versus actual CAISO demand.
• Audit-model corrected forecast.
• Forecast error before and after correction.
• Underprediction rate, worst 1% underprediction, peak-hour error, and consecutive underforecast runs.
• Monthly, hourly, weekday/weekend, and peak-demand performance breakdowns.
• Ranked anomaly candidates with quality flags and surrounding-event charts.

Setup

Register for an EIA API key at https://www.eia.gov/opendata/register.php, then install the project:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
export EIA_API_KEY="your-key"

Commands

The Makefile uses .venv/bin/python automatically when the virtualenv exists.

make test
make lint
make data START=2023-01-01T00 END=2026-06-30T00
make fix-libomp
make pipeline
make run-dashboard

make pipeline runs process, baselines, train, report, and anomalies after raw EIA parquet files exist.

Repository Structure

• src/data/: EIA ingestion, validation, and raw-to-processed parquet assembly.
• src/features/: leakage-aware calendar, lag, and rolling features.
• src/models/: baselines, residual model training, and reliability reports.
• src/anomalies/: residual anomaly detection, quality flags, and structured context.
• app/: FastAPI service and Streamlit dashboard.
• tests/: pytest coverage for ingestion, processing, features, metrics, API, and anomalies.
• DEMO_NOTES.md: current full-range result, demo sequence, and caveats.

Current Result

On the chronological test period beginning 2025-07-01, the current local run reports:

• Official forecast MAE: 2,337 MW
• Corrected forecast MAE: 853 MW
• MAE improvement: 63.5%
• Official forecast bias: 2,094 MW
• Corrected forecast bias: 525 MW

The correction improves every monthly test slice in reports/performance_breakdowns.json. The largest anomaly is flagged as a possible demand data discontinuity, which is why the project treats anomaly review as audit evidence rather than proof of a grid failure.

Caveats

• Generated data, model artifacts, and reports are intentionally ignored by git.
• On macOS, make fix-libomp can repair XGBoost linkage by reusing the libomp bundled with scikit-learn in the virtualenv.
• Same-hour observed generation is not used as a forecast input; it is only used for post-hour event context.
• Anomaly candidates are not outage claims.