WindLens

Day-ahead wind forecast clarity and accuracy

Live app: https://windlens-dayahead.vercel.app

WindLens is decision support for GB day-ahead wind power buying. It pairs the national wind forecast available at decision time (Elexon WINDFOR) with reported wind outturn (Elexon FUELHH) for the January 2026 decision month, measures how far and how often the forecast misses, and translates the results into plain language for a buying team.

Decision view	Accuracy view

What it does

1. See the decision clearly. Pick a delivery day and a decision cutoff; WindLens shows the exact forecast edition that was available at that moment, when it was published, and how every earlier edition had evolved. No actuals leak into this view.
2. Quantify the error. Compare forecast against outturn over the whole month: MAE, RMSE, bias, percentiles, error by hour of day, by lead time, and the full distribution, plus a one-sided overforecast buffer you can reason about when buying.
3. Read it in plain language. A buying notes view turns the metrics into sentences, with the limitations stated honestly.

Quick start

Docker (recommended):

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000 (health at /health, docs at /docs)
• The frontend proxies /api and /health to the backend, so the browser stays same origin.

Without Docker:

Tests, lint, and maintenance:

Repository guide

Architecture

Two requirements files, on purpose:

• Root requirements.txt lists fastapi and pydantic only. Vercel's Python runtime serves the ASGI app itself, so uvicorn is not deployed.
• backend/requirements.txt lists fastapi, starlette, and uvicorn for the Docker runtime image, which runs its own ASGI server. Development dependencies live in backend/requirements-dev.txt.

Key decisions and assumptions

Findings: January 2026

Across the 744 scored decision hours (09:00 cutoff): mean actual 11,283.6 MW, MAE 2,038.91 MW, RMSE 2,504.76 MW, signed bias +1,747.89 MW, relative bias +15.49%, nMAE 18.07%.

• The forecast averaged about 1.75 GW above reported output. The gap is already present at short lead (+1,454.93 MW, 12.76% of mean actual, at 0 to 4 h) and grows slowly with lead, about 9.8 MW per additional hour, to +1,942.49 MW (17.55%) at 44 to 48 h.
• 27 of 31 delivery days have a positive mean error; the P90 and P95 overforecast buffers are 4,097.9 MW and 5,283.35 MW (29.8% and 41.9% of forecast).
• This is evidence, not proof, of a cause. These datasets do not report curtailment or unconstrained wind availability, so the gap cannot be attributed. It is one month, in sample. A temporal alignment sensitivity (MAE minimum at a -2 h actual window shift, worth only 4.1% MAE) remains an open validation item with a data owner.

Full analysis: docs/DESIGN.md. Reproduce the tables with PYTHONPATH=. .venv/bin/python scripts/bias_diagnostic.py.

Metrics

API

Base path /api in production and Docker. Dates are YYYY-MM-DD; cutoff is HH:MM Europe/London. Errors return {"detail": "..."} with HTTP 422 or 503.

Testing and CI

• Backend: 20 pytest tests, including metric edge cases and the golden worked example (Jan 2, 00:00 UTC: forecast 18,781 MW vs actual mean 15,366.5 MW, error +3,414.5 MW). Metrics module coverage: 100%.
• Frontend: 29 Vitest and Testing Library tests covering formatting, derivations, the buying notes builder (including a negative bias case), the cutoff control, and loading, error, and empty states. ESLint and Prettier configured.
• CI runs backend, frontend, and docker jobs on every push and pull request; the docker job builds both images, waits for healthy containers, and asserts the smoke values above.

Limitations and next steps

• One month of data, fully in sample. Results describe January 2026, not the future.
• FUELHH reports generation by fuel type; WINDFOR covers farms visible to the system operator. The populations may differ, which caps how tightly error can be interpreted.
• No curtailment or unconstrained availability field exists in these datasets; the positive bias is measured, not explained.
• The WINDFOR hourly interval boundary is unconfirmed with a data owner (the empirical -2 h alignment minimum remains open).
• The 09:00 cutoff is an assumption based on auction gate times.
• Next steps: more months, an availability feed, bias adjusted forecast display by default, and per region breakdowns if Elexon exposes them.

AI tools disclosure

Claude (chat) and an AI coding agent were used for domain research, design, implementation, tests, documentation, and deployment tooling for this project. The author reviewed, verified, and takes responsibility for all of it: every metric in this README is reproducible from the committed snapshot with the scripts in scripts/, and every claim is traceable to docs/DESIGN.md.