SchoolHolidayFeatureAdder#

class openstef_models.transforms.time_domain.school_holiday_features_adder.SchoolHolidayFeatureAdder(*, country_code: CountryAlpha2, subdivision_code: str | None = None, years_ahead: int = 2, feature_name: str = 'is_school_holiday', one_hot_by_name: bool = False, regional_groups: bool = False, csv_path: Path | None = None, client: OpenHolidaysClient = <factory>)[source]

Bases: BaseConfig, TimeSeriesTransform

Transform that adds a school holiday indicator to time series data.

The feature added is:

  • is_school_holiday: 1 if the day falls within a school holiday for the configured country (and subdivision), 0 otherwise.

With one_hot_by_name=True, one more column is added per holiday name, for example is_school_holiday_may_holidays, with 1 on days of that holiday and 0 otherwise. The names are taken from the holidays known at fit time and stored with the model, sorted by name. The columns therefore stay the same for any data passed to transform, even when no holiday falls in it. A holiday name that was not present at fit time gets no column.

Holidays are fetched in fit for the training period plus years_ahead years, so that forecasts can use holiday information for future dates. Dates outside the covered range are logged as a warning, because their holiday status is unknown and is reported as 0. Set csv_path to a file written by export_csv to read the holidays from that file in fit instead.

Subdivision: for countries with regional school holidays (such as the Netherlands), set subdivision_code (for example ‘NL-NH’). The API returns holidays that apply to that subdivision. Without it, the API returns holidays for all regions combined.

Regional groups: set regional_groups=True to add one column per regional holiday group instead of the single feature, for example is_school_holiday_0 and is_school_holiday_1. Holidays are fetched for all subdivisions, so the model can pick the schedule that fits a location without knowing its province. A group is the set of subdivisions that share exactly the same holidays. Groups are numbered from 0 in the order of their sorted subdivision codes, and holidays without subdivisions form a group too. The membership of each group is kept in the transform, and in the CSV export’s subdivisions column. Requires subdivision_code to be None.

Example

>>> import pandas as pd
>>> from datetime import date, timedelta
>>> from openstef_core.datasets import TimeSeriesDataset
>>> from openstef_models.transforms.time_domain import SchoolHolidayFeatureAdder
>>> from openstef_models.transforms.time_domain.school_holiday_features_adder import (
...     OpenHolidaysClient,
...     SchoolHolidayPeriod,
... )
>>>
>>> # Stub client so the example runs without network access
>>> class StubClient(OpenHolidaysClient):
...     def get_school_holidays(self, request):
...         christmas = SchoolHolidayPeriod(
...             start_date=date(2025, 12, 24), end_date=date(2025, 12, 26), name="Christmas"
...         )
...         return [christmas]
>>> transform = SchoolHolidayFeatureAdder(country_code="NL", subdivision_code="NL-NH", client=StubClient())
>>> data = pd.DataFrame({
...     'load': [100] * 5
... }, index=pd.date_range('2025-12-24', periods=5, freq='D'))
>>> dataset = TimeSeriesDataset(data, sample_interval=timedelta(days=1))
>>> transform.fit(dataset)
>>> transform.transform(dataset).data["is_school_holiday"].tolist()
[1, 1, 1, 0, 0]
Parameters:
  • country_code (CountryAlpha2)

  • subdivision_code (str | None)

  • years_ahead (int)

  • feature_name (str)

  • one_hot_by_name (bool)

  • regional_groups (bool)

  • csv_path (Path | None)

  • client (OpenHolidaysClient)

country_code: CountryAlpha2
subdivision_code: str | None
years_ahead: int
feature_name: str
one_hot_by_name: bool
regional_groups: bool
csv_path: Path | None
client: OpenHolidaysClient
property covered_from: date | None

First date covered by the holidays, or None when a CSV without holidays was loaded.

property covered_until: date | None

Last date covered by the holidays, or None when a CSV without holidays was loaded.

property holidays: list[SchoolHolidayPeriod]

School holiday periods known to the transform.

property is_fitted: bool

Check if the transform has been fitted.

Overrides:

TimeSeriesTransform.is_fitted

fit(data: TimeSeriesDataset) → None[source]

Fetch school holidays for the training period and years_ahead years after it.

If csv_path is set, the holidays and their coverage dates are read from that file instead, and the API is not contacted. Otherwise makes exactly one request to the OpenHolidays API.

Parameters:

data (TimeSeriesDataset) – Time series dataset whose index defines the training period.

Raises:
  • SchoolHolidayFetchError – If the holidays cannot be retrieved.

  • ConfigurationError – If csv_path was exported for a different country or subdivision.

Return type:

None

Overrides:

TimeSeriesTransform.fit

transform(data: TimeSeriesDataset) → TimeSeriesDataset[source]

Add the school holiday indicator. Does not contact the API.

Parameters:

data (TimeSeriesDataset) – Input time series dataset.

Return type:

TimeSeriesDataset

Returns:

Transformed dataset with the school holiday feature added.

Raises:

NotFittedError – If the transform has neither been fitted nor loaded from CSV.

Overrides:

Transform.transform

features_added() → list[str][source]

List of feature names added by this transform.

Return type:

list[str]

Returns:

A list of strings representing the names of features added to the dataset by this transform. Default is an empty list.

Overrides:

TimeSeriesTransform.features_added

export_csv(path: Path, start: date, end: date) → None[source]

Fetch school holidays for a date range and write them to a CSV file.

Makes exactly one request to the OpenHolidays API. The file can be loaded later with from_csv, which needs no network access. Export a range that covers the period you intend to use, because dates outside the exported range are not flagged as holidays.

A range without any holidays writes a single row with the coverage dates and empty holiday fields, so the file still loads with from_csv.

Parameters:
  • path (Path) – Destination CSV file. An existing file is overwritten.

  • start (date) – First date to export.

  • end (date) – Last date to export.

Raises:
  • ValueError – If end is before start.

  • SchoolHolidayFetchError – If the holidays cannot be retrieved.

Return type:

None

classmethod from_csv(path: Path, country_code: CountryAlpha2, subdivision_code: str | None = None, *, one_hot_by_name: bool = False, regional_groups: bool = False) → Self[source]

Create a transform from a CSV file written by export_csv.

Makes no network requests, so the transform does not need to be trained. A file without any rows (a header only, or no content at all) means no holidays are known. The returned transform is fitted, adds 0 for every date, and has no coverage range to check dates against. Such a file cannot state its country or subdivision, so those are not checked.

Parameters:
  • path (Path) – CSV file written by export_csv.

  • country_code (CountryAlpha2) – Country the file must have been exported for.

  • subdivision_code (str | None) – Subdivision the file must have been exported for, or None.

  • one_hot_by_name (bool) – Also add one 0/1 column per holiday name. See the class docstring.

  • regional_groups (bool) – Add one column per regional group. The file must have been exported with subdivision_code None and must contain group codes. See the class docstring.

Return type:

Self

Returns:

A transform covering the date range of the file, with the holidays in the file.

Raises:

ConfigurationError – If the file is malformed, was exported for a different country or subdivision, or lacks group codes when regional_groups is set.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:
  • self (BaseModel) – The BaseModel instance.

  • context (Any) – The context.

Return type:

None