calendar.holiday.get_holiday_adjacency_features

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

Build holiday-adjacency indicators and align them to a regular time grid.

Generates is_brueckentag, is_before_holiday, and is_after_holiday indicators via create_holiday_adjacency_df(), validates temporal coverage with curate_holidays(), and reindexes the result to a full [start, cov_end] grid with fill_value=0 so that non-flagged timestamps are always zero.

All three columns are disjoint from is_holiday: a public holiday itself never receives a non-zero value in any of the three adjacency columns.

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 (should cover 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 and passed to create_holiday_adjacency_df(). 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 three integer columns
	pd.DataFrame	is_brueckentag, is_before_holiday, is_after_holiday.
	pd.DataFrame	The index is a tz-aware DatetimeIndex with the requested freq.
	pd.DataFrame	All values are in {0, 1}; no NaNs.

Examples

import pandas as pd
from spotforecast2_safe.calendar import get_holiday_adjacency_features

# Build a minimal synthetic reference DataFrame.
# curate_holidays requires:
#   adjacency_df.shape[0] == data.shape[0] + forecast_horizon.
# With n_data=48 rows and forecast_horizon=24, we need 72 hourly
# steps total, so cov_end = start + 71 h (inclusive date_range).
forecast_horizon = 24
n_data = 48
data = pd.DataFrame(
    {"load": range(n_data)},
    index=pd.date_range("2024-01-01", periods=n_data, freq="h", tz="UTC"),
)
start = data.index[0]
cov_end = start + pd.Timedelta(hours=(n_data + forecast_horizon - 1))

adj = get_holiday_adjacency_features(
    data=data,
    start=start,
    cov_end=cov_end,
    forecast_horizon=forecast_horizon,
    country_code="DE",
    state="NW",
)
print("shape:", adj.shape)
print("columns:", adj.columns.tolist())
assert adj.shape == (n_data + forecast_horizon, 3)
assert list(adj.columns) == [
    "is_brueckentag", "is_before_holiday", "is_after_holiday"
]

shape: (72, 3)
columns: ['is_brueckentag', 'is_before_holiday', 'is_after_holiday']