Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,9 +132,12 @@ The HA token is read from the `HA_TOKEN` environment variable, never from the fi

Two sensors are published (names configurable):

- `sensor.pv_forecast_today`: state = P50 kWh today. Attributes: `p10`, `p25`, `p90`, `detailedForecast` (30-min slots for today and the next two days, Solcast keys `period_start`, `pv_estimate`, `pv_estimate10`, `pv_estimate90`, plus `pv_estimate25`, values in kW), `per_array` (hourly P50 per array, adds up to the total), `models_ok`, `models`, `generated_at`, `level_factor`, `knmi`, and accuracy stats such as `ensemble_wmape_30d`.
- `sensor.pv_forecast_today`: state = P50 kWh today. Attributes: `p10`, `p25`, `p90`, `detailedForecast` (30-min slots for today and the next two days, Solcast keys `period_start`, `pv_estimate`, `pv_estimate10`, `pv_estimate90`, plus `pv_estimate25`, values in kW), `per_array` (hourly P50 per array, adds up to the total), `models_ok`, `models`, `generated_at`, `level_factor`, `knmi`, `band_coverage`, and accuracy stats such as `ensemble_wmape_30d`.

- `sensor.pv_forecast_tomorrow`: state = P50 kWh tomorrow. Attributes: `p10`, `p25`, `p90`, `day_after_tomorrow_p50`, and the common ones (`models_ok`, `models`, `generated_at`, `level_factor`, `knmi` and so on). It has no `detailedForecast`, `per_array` or accuracy stats. Those are only on the today sensor, which covers today plus the next two days.

`band_coverage` says how often the actual fell outside the published day-ahead band over the last 60 days (or `history_days` if shorter): `hours_below_p10_pct`, `hours_above_p90_pct`, `days_below_p10_pct` and `days_above_p90_pct`, with the number of scored `days` and `hours`. It is on both sensors, updated by `learn`, and gives only the counts until 7 days are scored. Hours where the band is clipped flat at the AC limit are not scored. P10 and P90 come from the 5 % and 95 % levels of the daily ratios, so about 5 % of days on each side is the expected result. They are applied to every hour, so expect more hours than days outside the band.

These are state objects written through the REST API. They are not tied to an integration, so they disappear after an HA restart until the next run (at most 15 minutes).

The attributes of `sensor.pv_forecast_today` are about 21 KB with two arrays, above the 16 KB the recorder accepts, so HA logs a warning on every update. Exclude both sensors from the recorder:
Expand Down
45 changes: 44 additions & 1 deletion src/roofcast/engine.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@
# Used until enough clear days exist to learn the spread (cold start). P50 stays the ensemble mean.
DEFAULT_QUANTILES = {'p10': 0.55, 'p25': 0.8, 'p50': 1.0, 'p90': 1.25}
MIN_QUANTILE_DAYS = 5
COVERAGE_DAYS, MIN_COVERAGE_DAYS = 60, 7
BAND_EPS_KWH = 0.01 # a band narrower than this (clipped at the AC limit) is not scored # band coverage: window, and fewer scored days than this = no percentages
NEW_ARRAY_BOUNDS = (0.1, 1.5)
NWP_KEEP_DAYS = 35 # > LEVEL_DAYS + 3 days of margin used by level_day_ahead

Expand Down Expand Up @@ -410,6 +412,10 @@ def learn(self) -> int:
k, raw_k = level_factor(t.y, t.f, [(today.date() - d).days for d in t.index])
cal['level'] = {'k': round(k, 4), 'raw': round(raw_k, 4), 'days': int(len(t)), 'half_life_days': LEVEL_HALF,
'source': 'archived day-ahead members (out of sample)'}
try:
cal['coverage'] = self.band_coverage(c, a)
except Exception as e: # a diagnostic: never block the calibration
log('band coverage failed:', e)
# written next to it, then renamed over it: a run reading it meanwhile, or a crash halfway, never sees half a file
tmp = f'{self.cal_path}.{os.getpid()}.tmp'
try:
Expand Down Expand Up @@ -460,6 +466,42 @@ def level_day_ahead(self, c, a: pd.DataFrame, days: int = LEVEL_DAYS) -> pd.Data
t = pd.DataFrame(rows, columns=['day', 'y', 'f']).set_index('day')
return t[t.f > self.min_day_kwh].tail(days)

def band_coverage(self, c, a: pd.DataFrame, days: int = COVERAGE_DAYS) -> dict:
"""How often the actual fell outside the published day-ahead band (table out, last issue before 21:00 the day
before, at most 6 h older), per daylight hour and per day, on the ok hours of the last `days` days. It reads
what was published, so it describes the band and changes nothing in it."""
days = min(days, self.cfg.history_days)
ok = a[a.ok & a.total.notna()]
loc = ok.index.tz_convert(self.tz)
today = self.now().tz_convert(self.tz).normalize()
since = int((today - pd.DateOffset(days=days + 2)).timestamp())
iss = pd.read_sql('select distinct issue from out where issue >= ?', c, params=(since,)).issue
hours, per_day = [], []
for d, yh in ok.total.groupby(loc.normalize()):
cut = (d - pd.Timedelta(hours=3)).timestamp()
I = iss[iss <= cut]
if d >= today or d < today - pd.DateOffset(days=days) or I.empty or cut - I.max() > 6 * 3600:
continue
o = pd.read_sql(f"select target, p10, p50, p90 from out where issue = ? and target in ({','.join('?' * len(yh))})",
c, params=(int(I.max()), *[int(t.timestamp()) for t in yh.index]))
o['y'] = o.target.map({int(t.timestamp()): v for t, v in yh.items()})
o = o[o.p50 > self.dead_hour_kwh] # daylight hours only: at night everything is 0
day = o[['p10', 'p90', 'y']].sum()
if o.p50.sum() <= self.min_day_kwh or day.p90 - day.p10 <= BAND_EPS_KWH:
continue
hours.append(o[o.p90 - o.p10 > BAND_EPS_KWH]) # clipped hours: P10 = P90 = limit, nothing to score
per_day.append(day)
res = {'window_days': days, 'days': len(per_day), 'hours': int(sum(len(h) for h in hours))}
if len(per_day) < MIN_COVERAGE_DAYS:
return res
H, D = pd.concat(hours), pd.DataFrame(per_day)

def pct(m):
return round(float(m.mean() * 100), 1)
res.update({'hours_below_p10_pct': pct(H.y < H.p10), 'hours_above_p90_pct': pct(H.y > H.p90),
'days_below_p10_pct': pct(D.y < D.p10), 'days_above_p90_pct': pct(D.y > D.p90)})
return res

# ------------------------------------------------------------ quality tracking
def quality(self, c) -> None:
"""Day-ahead (last issue before 21:00 the day before) forecast vs actual, per provider."""
Expand Down Expand Up @@ -618,7 +660,8 @@ def dsum(d, k):
common = {'unit_of_measurement': 'kWh', 'device_class': 'energy', 'icon': 'mdi:solar-power-variant',
'generated_at': now.isoformat(), 'models_ok': sum(1 for v in status.values() if v == 'ok'), 'models': status,
'calibration': cal.get('generated'), 'calibration_hours': cal.get('n_hours', 0),
'level_factor': cal.get('level') or {'k': 1.0}, 'quantiles_fallback': bool(q.get('fallback')), 'knmi': knmi}
'level_factor': cal.get('level') or {'k': 1.0}, 'quantiles_fallback': bool(q.get('fallback')), 'knmi': knmi,
'band_coverage': cal.get('coverage') or {}}
self.ha.set_state(cfg.sensor_today, dsum(d0, 'p50'), {
**common, 'friendly_name': 'PV forecast today (P50)', 'p10': dsum(d0, 'p10'), 'p25': dsum(d0, 'p25'),
'p90': dsum(d0, 'p90'), 'detailedForecast': detailed, **({'per_array': per} if per else {}), **qs})
Expand Down
80 changes: 80 additions & 0 deletions tests/test_coverage.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
"""Issue #6, step 4: coverage of the published day-ahead band, measured on table out. Describes the band only."""
import json

import pandas as pd
import pytest

from conftest import FakeHA, clear_sky_weather
from test_run import NOW, eng # noqa: F401 (fixture)


def _archive(eng, ys, p10=0.8, p50=1.0, p90=1.2, issue_hour=20, hourly=None):
"""One published day-ahead band per day (9 daylight hours), and the actual of each day as a flat hourly value."""
tz = eng.tz
c = eng.db()
rows, act = [], {}
for i, y in enumerate(ys, start=1):
day = NOW.tz_convert(tz).normalize() - pd.DateOffset(days=i)
issue = int((day - pd.Timedelta(hours=24 - issue_hour)).timestamp())
for h in range(8, 17):
t = (day + pd.Timedelta(hours=h)).tz_convert('UTC')
rows.append((issue, int(t.timestamp()), p10, (p10 + p50) / 2, p50, p90, 3))
act[t] = hourly(i, h) if hourly else y
c.executemany('insert into out values(?,?,?,?,?,?,?)', rows)
c.commit()
a = pd.Series(act).sort_index()
return c, pd.DataFrame({'total': a, 'ok': True})


def test_counts_days_and_hours_outside_the_band(eng):
ys = [0.5, 0.5, 1.5] + [1.0] * 7 # 2 days below P10, 1 above P90, out of 10
c, a = _archive(eng, ys)
r = eng.band_coverage(c, a)
assert r['days'] == 10 and r['hours'] == 90 and r['window_days'] == 60
assert r['days_below_p10_pct'] == pytest.approx(20.0) and r['days_above_p90_pct'] == pytest.approx(10.0)
assert r['hours_below_p10_pct'] == pytest.approx(20.0) and r['hours_above_p90_pct'] == pytest.approx(10.0)


def test_hours_not_ok_are_left_out(eng):
c, a = _archive(eng, [0.5] * 10)
a.loc[a.index[:9], 'ok'] = False # the most recent day is curtailed: not scored
assert eng.band_coverage(c, a)['days'] == 9


def test_too_few_days_gives_counts_only(eng):
c, a = _archive(eng, [1.0] * 5)
r = eng.band_coverage(c, a)
assert r == {'window_days': 60, 'days': 5, 'hours': 45}


def test_issue_after_21h_is_not_day_ahead(eng):
c, a = _archive(eng, [1.0] * 10, issue_hour=23) # issued at 23:00 the evening before: too late
assert eng.band_coverage(c, a)['days'] == 0


def test_learn_stores_and_run_publishes_coverage(eng, monkeypatch):
cfg = eng.cfg
cfg.history_days = 30
w = clear_sky_weather(cfg, (NOW - pd.Timedelta(days=31)).floor('D'), 32 * 24)
F = eng.pv(w)
eng._ha = FakeHA({x.entities[0]: F[x.name] * 900 for x in cfg.arrays})
monkeypatch.setattr(eng, 'fetch_prev_runs', lambda m, lead, s, e: w)
assert eng.learn() == 0
cal = json.load(open(eng.cal_path))
assert cal['coverage']['days'] == 0 # nothing published yet: counts only
eng._ha = FakeHA()
eng.run()
assert eng.ha.states['sensor.pv_forecast_today'][1]['band_coverage'] == cal['coverage']


def test_hours_out_while_the_day_is_in(eng):
"""Hours alternate 0.5 / 1.5 around a P50 of 1.0: every hour is outside the band, every day total inside."""
c, a = _archive(eng, [1.0] * 10, hourly=lambda i, h: 0.5 if h % 2 else 1.5)
r = eng.band_coverage(c, a)
assert r['days_below_p10_pct'] == 0 and r['days_above_p90_pct'] == 0
assert r['hours_below_p10_pct'] + r['hours_above_p90_pct'] == pytest.approx(100.0)


def test_band_clipped_flat_is_not_scored(eng):
c, a = _archive(eng, [1.02] * 10, p10=1.0, p50=1.0, p90=1.0) # P10 = P90 = the AC limit
assert eng.band_coverage(c, a) == {'window_days': 60, 'days': 0, 'hours': 0}
Loading