calendar.holiday.get_school_holiday_features

calendar.holiday.get_school_holiday_features(
    data,
    start,
    cov_end,
    forecast_horizon,
    tz='UTC',
    freq='h',
    country_code='DE',
    state='NW',
)

Build per-Bundesland school-holiday indicators and align them to a forecast grid.

Generates the is_school_holiday binary indicator via create_school_holiday_df(), validates temporal coverage with curate_holidays(), and reindexes onto the full [start, cov_end] grid with fill_value=0.

The requested span [start, cov_end] must lie entirely within the dataset validity range 2022-01-01 to 2027-12-31. If either edge falls outside this range a ValueError is raised immediately — there is no fill or extrapolation.

Only country_code="DE" is supported; passing any other value raises ValueError.

Parameters

Name	Type	Description	Default
data	pd.DataFrame	Reference time series DataFrame used for temporal coverage validation inside `curate_holidays()`.	required
start	Union[str, pd.Timestamp]	Start timestamp. String values are parsed with `utc=True`.	required
cov_end	Union[str, pd.Timestamp]	Inclusive end timestamp covering the full forecast horizon. String values are parsed with `utc=True`.	required
forecast_horizon	int	Number of forecast steps ahead; passed to `curate_holidays()`.	required
tz	str	Timezone applied to the generated index. Defaults to `"UTC"`.	`'UTC'`
freq	str	Pandas-compatible frequency string. Defaults to `"h"`.	`'h'`
country_code	str	Must be `"DE"`. Any other value raises `ValueError`.	`'DE'`
state	str	ISO 3166-2 subdivision short code for the Bundesland. Defaults to `"NW"` (North Rhine-Westphalia).	`'NW'`

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Single integer column `is_school_holiday` (values in
	pd.DataFrame	`{0, 1}`; no NaNs). The index is a tz-aware `DatetimeIndex` with
	pd.DataFrame	the requested freq and shape `(len(data) + forecast_horizon, 1)`.

Raises

Name	Type	Description
	ValueError	If country_code is not `"DE"`, or if the requested span extends beyond the dataset validity range `[2022-01-01, 2027-12-31]`.

Examples

import pandas as pd
from spotforecast2_safe.calendar import get_school_holiday_features

forecast_horizon = 24
n_data = 48
data = pd.DataFrame(
    {"load": range(n_data)},
    index=pd.date_range("2024-07-06", periods=n_data, freq="h", tz="UTC"),
)
start = data.index[0]
cov_end = start + pd.Timedelta(hours=(n_data + forecast_horizon - 1))

feats = get_school_holiday_features(
    data=data,
    start=start,
    cov_end=cov_end,
    forecast_horizon=forecast_horizon,
    state="NW",
)
print("shape:", feats.shape)
print("columns:", feats.columns.tolist())
# NW Sommerferien 2024: 2024-07-08 is a school holiday (is_school_holiday=1).
print("2024-07-07 00:00 UTC:", feats.loc["2024-07-07 00:00:00+00:00", "is_school_holiday"])
print("2024-07-08 00:00 UTC:", feats.loc["2024-07-08 00:00:00+00:00", "is_school_holiday"])
assert feats.shape == (n_data + forecast_horizon, 1)
assert feats.loc["2024-07-07 00:00:00+00:00", "is_school_holiday"] == 0
assert feats.loc["2024-07-08 00:00:00+00:00", "is_school_holiday"] == 1

shape: (72, 1)
columns: ['is_school_holiday']
2024-07-07 00:00 UTC: 0
2024-07-08 00:00 UTC: 1