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

[Copilot]

Description

Annotations (e.g. public holidays, school holidays, custom schedules) can now serve as binary future covariates in the forecasting pipeline, so forecasts learn e.g. that holiday mornings behave like weekend mornings. Holiday import is consolidated into a single CLI command backed by either workalendar or the holidays package, and holiday annotations are now stored at local midnight instead of showing a UTC offset in charts.

• Add annotation-regressors to the forecasting pipeline config schema: matching annotations become binary future covariates.
• Support account, asset and sensor annotation sources with annotation-type filtering, validated through ID fields at load time.
• Add a repeatable --annotation-regressors option to flexmeasures add forecasts (inline JSON or file).
• Merge add_holidays_by_package into flexmeasures add holidays behind a --package option, auto-switching to the holidays package when --subdiv or --category is given.
• Add --calendar-class / --calendar-kwargs to select any specific workalendar calendar (e.g. NetherlandsWithSchoolHolidays with '{"region": "north"}').
• Store holiday annotations at local midnight via --timezone, defaulting to FLEXMEASURES_TIMEZONE (with a warning); replace pytz with stdlib zoneinfo.
• Abort with a clear message when the selected calendar has no data for the requested year; --year is now required.
• Stamp annotation regressor values with the forecast vantage point as belief time.
• Keep annotation regressors intact through --as-job queue serialization and across DST transitions.
• Give an explicit --train-start precedence over the default 30-day train-period; warn when both are set.
• Fail with explicit errors on invalid forecaster configs and annotation regressor sources instead of silently dropping them.
• Update annotations and forecasting documentation, OpenAPI specifications, and changelog.

Look & Feel

Holiday annotations now align with local midnight in sensor charts (previously offset to 1–2 AM).

Example annotation regressor spec in a forecaster config:

{
  "annotation-regressors": [
    {
      "name": "nl_holidays",
      "asset": 8,
      "annotation-type": "holiday"
    }
  ]
}

How to test

• pytest:

uv run pytest \
  flexmeasures/cli/tests/test_data_add.py \
  flexmeasures/cli/tests/test_data_add_fresh_db.py \
  flexmeasures/data/schemas/tests/test_forecasting.py \
  flexmeasures/data/tests/test_forecasting_pipeline.py

• Manual CLI check:

Import holidays and use them as a regressor on a price forecast covering Ascension Day 2026 (the scenario from #2181):

flexmeasures add holidays --year 2026 --country NL --asset <asset-id> --timezone Europe/Amsterdam

flexmeasures add forecasts --sensor <price-sensor-id> --sensor-to-save <output-sensor-id> \
  --start 2026-05-11T00:00:00+02:00 --end 2026-05-18T00:00:00+02:00 \
  --train-start 2026-03-01T00:00:00+01:00 \
  --annotation-regressors '{"name": "nl_holidays", "asset": <asset-id>, "annotation-type": "holiday"}'

Expected behavior: holiday annotations are stored at local midnight; the forecast on Ascension Day (May 14) shifts downward relative to a run without the regressor while non-holiday days are unaffected (in our test run, holiday MAE improved from 16.2 to 14.4 EUR/MWh). Passing both --train-start and --train-period logs a warning that the period is ignored; an unsupported calendar year (e.g. --calendar-class workalendar.europe.netherlands.NetherlandsWithSchoolHolidays --year 2031) aborts with a clear message. The same command with --as-job produces identical behavior via the forecasting queue.

Related Items

• Closes Add annotation-regressors to forecaster config #2181

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures

[Copilot]

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)

[Flix6x]

Found this old review I hadn't posted.

[Flix6x]

I prefer to pick a belief time equal to the actual vantage point.

[BelhsanHmida]

Agreed, changed. annotation regressors are now stamped with the forecast vantage point (predict_start) instead of the epoch.

One deliberate exception I want to flag: the training window filters future regressors on belief_time > event_start (realized-only), which would hide vantage-point-stamped annotation values from training. So in split_data_all_beliefs the duplicated training-window rows get belief_time = event_start + resolution instead. There's a code comment explaining this, happy to take a different approach if you'd rather.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33656225 | 📁 Comparing 6762c40 against latest (a5c4396)

  🔍 Preview build  

24 files changed · ± 22 modified · - 2 deleted

± Modified

• changelog.html
• genindex.html
• py-modindex.html
• _autodoc/SOC_MAXIMA.html
• _autodoc/SOC_MINIMA.html
• _autodoc/SOC_TARGETS.html
• _autosummary/flexmeasures.cli.utils.html
• _autosummary/flexmeasures.data.models.forecasting.pipelines.base.html
• _autosummary/flexmeasures.data.models.forecasting.pipelines.predict.html
• _autosummary/flexmeasures.data.models.forecasting.pipelines.train.html
• and 12 more...

- Deleted

• _autosummary/flexmeasures.data.models.planning.soc_projection.html
• _autosummary/flexmeasures.data.schemas.scheduling.utils.html

[BelhsanHmida]

Manual validation on the #2181 scenario

I tested this branch against the exact case that motivated the issue: day-ahead prices over Ascension Thursday (May 14, 2026), using a local copy of the production price sensor and NL holiday annotations imported with the new flexmeasures add holidays (stored at local midnight via --timezone Europe/Amsterdam).

Setup: two forecast runs with identical configs (train from March 1 → predict May 11–18, retrain every 2 days) — the only difference is the annotation-regressors entry:

{"name": "nl_holidays", "asset": 8, "annotation-type": "holiday"}

With the holiday regressor (forecast in blue, actuals in orange):

For reference, the production forecast that motivated #2181. The Thursday midday dip is largely missed there. Not an apples-to-apples comparison with the run above (production uses its own training window/config), just the real-world illustration:

Also verified the same config through the RQ forecasting queue (--as-job): the annotation regressor survives job serialization (the stored data-source config records it with the asset serialized to its ID) and produces the same holiday behavior.