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,TimeSeriesTransformTransform 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
- years_ahead: int
- feature_name: str
- one_hot_by_name: bool
- regional_groups: bool
- 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:
- 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:
- 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
- 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:
- Raises:
ValueError – If end is before start.
SchoolHolidayFetchError – If the holidays cannot be retrieved.
- Return type:
- 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:
- 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].