diff --git a/README.md b/README.md index 051756f..52a1ebf 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/src/roofcast/engine.py b/src/roofcast/engine.py index 94a35f2..77568ae 100644 --- a/src/roofcast/engine.py +++ b/src/roofcast/engine.py @@ -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 @@ -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: @@ -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.""" @@ -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}) diff --git a/tests/test_coverage.py b/tests/test_coverage.py new file mode 100644 index 0000000..552c0ac --- /dev/null +++ b/tests/test_coverage.py @@ -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}