calendar.holiday.create_holiday_adjacency_df

calendar.holiday.create_holiday_adjacency_df(
    start,
    end,
    tz='UTC',
    freq='h',
    country_code='DE',
    state='NW',
)

Create a DataFrame with binary adjacency indicators for public holidays.

Returns three int columns, all disjoint from is_holiday:

A day may be flagged by more than one column simultaneously; for example, 2024-12-27 (Friday after Christmas/Boxing Day, before a long weekend) is both is_after_holiday and is_brueckentag.

Weekend membership is determined by dayofweek >= 5; the holidays library knows nothing about weekends, so this rule is applied explicitly.

Boundary rule: the first day of the requested range needs to know the holiday/weekend status of the day before start, and the last day needs the status of the day after end. Neighbour-day look-ups (d ± 1d) are performed directly against the holiday calendar object, which resolves any date on demand, so edge rows are never incorrectly zeroed.

Parameters

Name Type Description Default
start str | pd.Timestamp Start date/datetime. required
end str | pd.Timestamp End date/datetime. required
tz str Timezone to use if not inferred from start/end. 'UTC'
freq str Frequency of the resulting DataFrame. 'h'
country_code str Country code for holidays (e.g. "DE", "US"). 'DE'
state str State code for holidays (e.g. "NW", "CA"). 'NW'

Returns

Name Type Description
pd.DataFrame pd.DataFrame: DataFrame with index covering [start, end] at freq
pd.DataFrame and three integer columns in order: is_brueckentag,
pd.DataFrame is_before_holiday, is_after_holiday. All values are in
pd.DataFrame {0, 1}; no NaNs.

Examples

import pandas as pd
from spotforecast2_safe.calendar import create_holiday_adjacency_df

# Unity Day 2024 (Thu 2024-10-03) is a public holiday in Germany.
# 2024-10-04 (Fri) is therefore sandwiched between the holiday and the
# weekend (Sat 2024-10-05, Sun 2024-10-06) → Brückentag.
df = create_holiday_adjacency_df(
    "2024-10-02", "2024-10-06", freq="D", country_code="DE", state="NW"
)
print(df)
assert df.loc["2024-10-04", "is_brueckentag"] == 1
assert df.loc["2024-10-03", "is_brueckentag"] == 0  # is_holiday, not Brückentag
assert df.loc["2024-10-02", "is_before_holiday"] == 1  # day before Unity Day
assert df.loc["2024-10-04", "is_after_holiday"] == 1   # day after Unity Day
                           is_brueckentag  is_before_holiday  is_after_holiday
2024-10-02 00:00:00+00:00               0                  1                 0
2024-10-03 00:00:00+00:00               0                  0                 0
2024-10-04 00:00:00+00:00               1                  0                 1
2024-10-05 00:00:00+00:00               0                  0                 0
2024-10-06 00:00:00+00:00               0                  0                 0