Add annotation regressors to forecaster config, merged holidays command, and timezone fix by Copilot · Pull Request #2178 · FlexMeasures/flexmeasures

Copilot · 2026-05-15T12:33:03Z

This PR adds annotation regressors (e.g. holidays, custom schedules) as binary future covariates in the forecasting pipeline, consolidates holiday import into a single CLI command backed by either workalendar or the holidays package, and fixes a timezone offset bug in holiday annotations.

Changes Made

CLI (`flexmeasures add holidays`)

Merged add_holidays_by_package into add_holidays — a single flexmeasures add holidays command now supports both backends via --package workalendar|holidays; automatically switches to the holidays package when --subdiv or --category is provided
Added --calendar-class and --calendar-kwargs options so users can select any specific workalendar class (e.g. workalendar.europe.netherlands.NetherlandsWithSchoolHolidays) and pass constructor arguments as JSON (e.g. '{"region": "north"}')
Added --timezone option; defaults to the FLEXMEASURES_TIMEZONE config setting (with a warning) instead of UTC, fixing holiday annotations appearing at 1 AM or 2 AM in charts
Replaced pytz with stdlib zoneinfo.ZoneInfo for timezone validation
Extracted helper functions (_make_holiday_annotation, _holidays_from_workalendar_class, _holidays_from_package, _holidays_from_workalendar_registry) to keep cyclomatic complexity within limits
--year is now required (previously optional but broken without it)

Forecasting pipeline schema

Added AnnotationRegressorSchema (proper fields.Nested) in TrainPredictPipelineConfigSchema
Schema field is annotation-regressors (was future-annotation-regressors); data keys are account, asset, sensor, and annotation-type
Added sensor as a supported annotation source alongside account and asset

Pipeline & queries

Extended BasePipeline with _AnnotationRegressorProxy, _load_annotation_regressor_df, and updated load_data_all_beliefs / split_data_all_beliefs
Extended TrainPipeline, PredictPipeline, TrainPredictPipeline to pass annotation regressors through
Added query_account_annotations, query_sensor_annotations to flexmeasures/data/queries/annotations.py
Added holidays>=0.57 as a direct dependency in pyproject.toml

Tests

test_add_holidays_with_workalendar_school_holidays invokes the CLI with --calendar-class workalendar.europe.netherlands.NetherlandsWithSchoolHolidays --calendar-kwargs '{"region": "north"}'
test_add_holidays_by_package_german_school uses the merged add_holidays command with --subdiv BY --category school
test_add_holidays_with_timezone verifies annotations are stored at local midnight
test_annotation_regressors_loaded_in_pipeline verifies binary regressor loading for a factory logistics schedule

Documentation

documentation/concepts/annotations.rst: sphinx-tabs for workalendar (public), workalendar (specific class), and holidays-package (school) examples; clarified school holiday support is for selected countries
documentation/features/forecasting.rst: updated to reflect annotation-regressors key and account/asset/sensor/annotation-type data keys
Changelog updated with breaking change note (--year now required, holidays-by-package merged, field renamed)

… command; add future-annotation-regressors to pipeline schema Context: - add_holidays stored UTC midnight timestamps, causing holidays to appear at wrong local time (e.g. 1AM in Amsterdam) in the UI - No support for the 'holidays' Python package which covers more countries and school holidays not in workalendar - No way to pass annotation-based binary regressors to the forecasting pipeline Change: - Add --timezone option to 'flexmeasures add holidays'; holidays are now localized to the given timezone (UTC when omitted, with a warning) - Add new 'flexmeasures add holidays-by-package' command backed by the 'holidays' package; supports --country, --subdiv, --category, --timezone - Add 'holidays>=0.57' to pyproject.toml direct dependencies - Add future_annotation_regressors field (data_key: future-annotation-regressors) to TrainPredictPipelineConfigSchema for annotation-based binary regressors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…lidays-by-package Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - TrainPredictPipelineConfigSchema already supports future_annotation_regressors - Need to wire this config field through the pipeline execution Change: - Add query_account_annotations() to data/queries/annotations.py - Add _AnnotationRegressorProxy class to base pipeline for reuse in detect_and_fill_missing_values - Add annotation_regressors parameter to BasePipeline.__init__ with proxy/name construction - Add _load_annotation_regressor_df() to build binary 0/1 time series from DB annotations - Extend load_data_all_beliefs() to left-join annotation regressors onto the main DataFrame - Extend split_data_all_beliefs() to include annotation regressor columns as future covariates - Update autoregressive-only check to account for annotation_regressors - Pass annotation_regressors to TrainPipeline and PredictPipeline from run_cycle Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

- Include col_name in annotation regressor skip warning for clarity - Remove redundant list() wrapping (self.future is already list[Sensor]) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…lidays, holidays-by-package, and annotation pipeline regressors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…g and annotations docs Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…, pipeline config isolation patterns Context: - PR #2176 introduced _AnnotationRegressorProxy for reusing sensor-based pipeline utilities with non-sensor (annotation) data, and added query_account_annotations mirroring query_asset_annotations Change: - Added lesson on duck-type proxy validity check (only proxy what's actually accessed) - Added annotation query parity rule (account + asset variants must stay consistent) - Added pipeline config schema isolation guidance (pipeline vs search vs reporter schemas) - Added _clean_parameters retention decision rule for new config keys Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

… pipeline conventions Context: - PR #2176 added --timezone option to holiday CLI commands and implements annotation-to-pipeline loading that must match load_data_all_beliefs UTC-naive convention Change: - Added lesson on --timezone recommendation for holiday CLI commands - Added UTC-naive convention for annotation timestamp loading into pipeline - Added DST boundary risk note for full-day annotations spanning spring-forward Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…ta_key as API surface Context: - PR #2176 added future-annotation-regressors as an optional pipeline config field using load_default=[] and data_key kebab-case pattern Change: - Added lesson on load_default=[] as backward compatibility pattern for new optional fields - Added lesson on _clean_parameters not being a regression risk for new config keys - Added lesson that data_key kebab-case is the API surface (not Python attribute name) Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…e review Context: - Post-session governance review of annotation regressors feature branch - Single-agent execution (recurring delegation failure), but high code quality Change: - Documented delegation observation (all commits by copilot-swe-agent) - Documented new patterns added to 3 specialist agents - Noted open question: missing account_id/asset_id spec causes silent degradation (could be a schema-level validation error in future) - Noted storage growth concern for future_annotation_regressors in DataSource attrs Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/5a54d4cf-b1e6-4400-8808-8fe704b3fd84 Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Flix6x · 2026-05-15T13:48:05Z



-**Holiday import command:**
+**Holiday import (workalendar):**


Let's use tabs to switch between workalendar and holidays examples.

Done in dc6a627 — the holiday import section now uses three tabs: "workalendar (public holidays)", "workalendar (specific calendar class)", and "holidays package (school holidays)".

Flix6x · 2026-05-15T14:12:32Z

+        )
+    )
+    # NetherlandsWithSchoolHolidays returns public + school holiday days; the primary
+    # assertion is an exact match, and the lower bound confirms the calendar is non-trivial.


non-trivial?

The > 90 lower-bound assertion is intentional — it confirms the calendar produces a non-trivial number of days (it also serves as readable documentation of the expected magnitude). The exact-match assertion count == expected_count already catches regressions, while > 90 prevents a scenario where both the calendar and DB return zero or a trivially small count.

…sor support, zoneinfo, tabs in docs Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/533db2b6-51ae-425f-be65-5fbce46a06be Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…fallback Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/533db2b6-51ae-425f-be65-5fbce46a06be Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Copilot · 2026-05-15T14:49:57Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

publicsuffix.org
- Triggering command: /home/REDACTED/work/flexmeasures/flexmeasures/.venv/bin/pytest pytest exec --process /tmp/runc-process4263968116 9350.pid --pid-file /run/containerd/io.containerd.runtime.v2.task/moby/294a1c6d6c8ea297a1d514309a4f0f22e5df96434fb393c3f1949e96fd58fca4/29d7dc61af1f624e99ef9da8ada77896e812f904d38beff4456083ac74c4e846.pid 294a1c6d6c8ea297a1d514309a4f0f22e5df96434fb393c3f1949e96fd58fca4 297a1d514309a4f0/usr/lib/postgresql/17/bin/pg_isready f22e5df96434fb393c3f1949e96fd58fca4/98ccd0592dfaf4eb74ec7c37ef925a5feaa5962ccb04b150�� f1949e96fd58fca4flexmeasures_test bash 10d4�� runtime-runc/mob/run/containerd/io.containerd.runtime.v2.task/moby/f01f526ebd9c0da8ed49b88d11a39bash /var/run/docker/f01f526ebd9c0da8ed49b88d11a390453312861de954b1609193d89bb9a364a0 bash io.containerd.rubash 297a1d514309a4f0/usr/bin/runc (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Signed-off-by: F.N. Claessen <claessen@seita.nl>

…essorSchema Context: - JSONOrFile lacked the required click.ParamType.name attribute, causing AttributeError when --help was invoked on commands that use it. - AnnotationRegressorSchema.remove_none_values was already added in an earlier commit but the post_dump decorator import was missing from pipeline.py. Change: - Add name = 'JSON_OR_FILE' to JSONOrFile click.ParamType subclass. - Import post_dump in pipeline.py (already used by AnnotationRegressorSchema).

Context: - Running add forecasts with --train-start in CET (+01) and --start in CEST (+02) caused a TypeError from pd.date_range: 'Start and end cannot both be tz-aware with different timezones'. - The start/end passed to _load_annotation_regressor_df come from event_starts_after and event_ends_before which can carry different UTC offsets across DST boundaries. Change: - Convert start and end to UTC before constructing the time index. - Strip timezone info afterwards to match the tz-naive convention used in load_data_all_beliefs.

Context: - train_start with explicit --train-start was being overridden by the default 30-day train_period, producing a narrower training window than intended. Change: - When train_start is explicit, period is ignored. - When only train_period is explicit, use it (capped to max_training_period). - When neither is set, use the full max_training_period window.

Context: - Part 3 of test_annotation_regressors_loaded_in_pipeline asserted a 5 MW forecast gap which is not reliably produced by LGBM with default parameters. - test_add_holidays_by_package_german_school used DE/BY/school which is no longer supported by the installed version of the holidays package. Change: - Replace the unreliable 5 MW quality assertion with a structural check: verify that 96 forecast beliefs were persisted for the 4-day window. - Switch holidays test to IL (Israel) which reliably supports the school category and has ~19 entries in 2024.

Copilot AI and others added 11 commits May 15, 2026 11:59

cli/data_add: improve error message for invalid subdiv/category in ho…

b8896f4

…lidays-by-package Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

tests: add CLI tests for add_holidays timezone, workalendar school ho…

fd0e678

…lidays, holidays-by-package, and annotation pipeline regressors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

tests: tighten assertion bounds based on code review feedback

e73d54e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

docs: add annotation regressors and holidays-by-package to forecastin…

5951c79

…g and annotations docs Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Copilot AI assigned Copilot and Flix6x May 15, 2026

docs: update changelog PR number from #2176 to #2178

cbb7870

Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/5a54d4cf-b1e6-4400-8808-8fe704b3fd84 Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Copilot created this pull request from a session on behalf of Flix6x May 15, 2026 12:36 View session

Copilot finished work on behalf of Flix6x May 15, 2026 12:36

Copilot AI requested a review from Flix6x May 15, 2026 12:36

Flix6x added Forecasting AI Infra labels May 15, 2026

Flix6x requested changes May 15, 2026

View reviewed changes

Copilot started work on behalf of Flix6x May 15, 2026 14:23 View session

Copilot AI and others added 2 commits May 15, 2026 14:45

refactor: merge add_holidays commands, AnnotationRegressorSchema, sen…

dc6a627

…sor support, zoneinfo, tabs in docs Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/533db2b6-51ae-425f-be65-5fbce46a06be Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

docs: update changelog entries and add comment for empty-string name …

a161cf7

…fallback Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/533db2b6-51ae-425f-be65-5fbce46a06be Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Copilot AI changed the title ~~Add annotation regressors to forecaster config, holidays-by-package command, and timezone fix~~ Add annotation regressors to forecaster config, merged holidays command, and timezone fix May 15, 2026

Copilot finished work on behalf of Flix6x May 15, 2026 14:50

Copilot AI requested a review from Flix6x May 15, 2026 14:50

Flix6x added 3 commits May 16, 2026 22:47

feat: add --annotation-regressors CLI option

b9faeb0

Signed-off-by: F.N. Claessen <claessen@seita.nl>

feat: add test coverage and fix CLI option

7b2bebf

Signed-off-by: F.N. Claessen <claessen@seita.nl>

fix: time series loading across DST transitions

d41e3b1

Signed-off-by: F.N. Claessen <claessen@seita.nl>

refactor: move JSON decoding logic to click.ParamType subclass

2977fc0

Signed-off-by: F.N. Claessen <claessen@seita.nl>

Flix6x linked an issue May 18, 2026 that may be closed by this pull request

Add annotation-regressors to forecaster config #2181

Open

Flix6x added 6 commits May 18, 2026 12:02

fix: remove None values from data generator config

5d2e377

Signed-off-by: F.N. Claessen <claessen@seita.nl>

chore: regenerate OpenAPI specs after AnnotationRegressorSchema changes

472108e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add annotation regressors to forecaster config, merged holidays command, and timezone fix#2178

Add annotation regressors to forecaster config, merged holidays command, and timezone fix#2178
Copilot wants to merge 24 commits into
mainfrom
copilot/add-annotation-regressors-forecaster-config

Copilot AI commented May 15, 2026 •

edited

Loading

Uh oh!

Uh oh!

Flix6x May 15, 2026

Uh oh!

Copilot AI May 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Flix6x May 15, 2026

Uh oh!

Copilot AI May 15, 2026

Uh oh!

Uh oh!

Copilot AI commented May 15, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants



		Holiday import command:
		Holiday import (workalendar):

Conversation

Copilot AI commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

CLI (flexmeasures add holidays)

Forecasting pipeline schema

Pipeline & queries

Tests

Documentation

Uh oh!

Uh oh!

Flix6x May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Flix6x May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI commented May 15, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented May 15, 2026 •

edited

Loading

CLI (`flexmeasures add holidays`)