manager.exo.calendar.get_holiday_features

manager.exo.calendar.get_holiday_features(
    data,
    start,
    cov_end,
    forecast_horizon,
    tz='UTC',
    freq='h',
    country_code='DE',
    state='NW',
)

Fetch public-holiday indicators and align them to a regular time grid.

Downloads holiday data via :func:~spotforecast2_safe.data.fetch_data.fetch_holiday_data, validates coverage with :func:~spotforecast2_safe.preprocessing.curate_data.curate_holidays, and reindexes the result to a full [start, cov_end] grid with fill_value=0 so that non-holiday timestamps are always zero.

Parameters

Name	Type	Description	Default
data	pd.DataFrame	Reference time series DataFrame used for temporal coverage validation inside :func:~spotforecast2_safe.preprocessing.curate_data.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 (should cover the full forecast horizon). String values are parsed with utc=True.	required
forecast_horizon	int	Number of forecast steps ahead; passed to :func:~spotforecast2_safe.preprocessing.curate_data.curate_holidays.	required
tz	str	Timezone applied to the generated index and passed to :func:~spotforecast2_safe.data.fetch_data.fetch_holiday_data. Defaults to "UTC".	'UTC'
freq	str	Pandas-compatible frequency string for the output index. Defaults to "h" (hourly).	'h'
country_code	str	ISO 3166-1 alpha-2 country code. Defaults to "DE" (Germany).	'DE'
state	str	Sub-national state/region code. Defaults to "NW" (North Rhine-Westphalia).	'NW'

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: DataFrame with a single integer column
	pd.DataFrame	is_holiday. The index is a tz-aware
	pd.DataFrame	class:~pandas.DatetimeIndex with the requested freq.

Examples:

::: {#cc50c981 .cell execution_count=1}
``` {.python .cell-code}
import pandas as pd
from spotforecast2_safe.data.fetch_data import fetch_data, get_package_data_home
from spotforecast2_safe.preprocessing.curate_data import agg_and_resample_data
from spotforecast2_safe.manager.exo.calendar import get_holiday_features

# Minimal reference DataFrame for validation
data = fetch_data(filename=str(get_package_data_home() / "demo10.csv"))
data = agg_and_resample_data(data, verbose=False)

start = pd.Timestamp("2024-01-01", tz="UTC")
cov_end = pd.Timestamp("2024-01-07 23:00", tz="UTC")

holidays = get_holiday_features(
    data=data,
    start=start,
    cov_end=cov_end,
    forecast_horizon=24,
    country_code="DE",
    state="NW",
)
print("shape:", holidays.shape)
print("columns:", holidays.columns.tolist())
# New Year's Day (Jan 1) is a public holiday in Germany
print("Jan 1 value:", holidays.loc["2024-01-01 00:00:00+00:00", "is_holiday"])
```

::: {.cell-output .cell-output-stdout}
```
Holiday dataframe has wrong shape.
shape: (168, 1)
columns: ['is_holiday']
Jan 1 value: 1
```
:::
:::