holiday-rlag 1.1.0

Fetches holiday information from https://github.com/vacanza/holidays and applies reverse lagging (that is, future indicators) for time series training.

holiday-rlag

Fetches holiday information using the holidays library and applies reverse lagging (future indicators) for time series training.

Features

• Fetches holidays for a given date range and country
• Adds reverse lag markers for holidays using one column per holiday type
• Flags for Easter, Christmas, and bank holidays

Installation

pip install holiday-rlag
# or, if using uv:
uv pip install .

Requirements

• Python 3.11+
• holidays

Usage

from holiday_rlag.laggedholidays import fetch_holidays
import datetime

date_start = datetime.date(2023, 1, 1)
date_end = datetime.date(2023, 12, 31)
holidays = fetch_holidays(date_start, date_end, country_code="DE", reverse_lag=7)

df = pd.DataFrame(holidays)

API

fetch_holidays(...)

Fetches holidays for a given date range and country, with optional reverse lagging.

Parameters:

• date_start (datetime.date): Start date
• date_end (datetime.date): End date
• country_code (str): Country code (default: "DE")
• reverse_lag (int): Number of days to look back for reverse lagging (default: 7)
• lag_peak_on_holiday (bool): If True, the holiday date gets the maximum marker; otherwise the day before does (default: False)
• col_is_easter, col_is_christmas, col_is_bank_holiday: Column names for flags
• col_lag_prefix, col_lag_suffix: Prefix/suffix for lag marker columns

Returns:

• list[dict]: List of dictionaries with holiday flags and lag marker values

Note: The result is not a complete date list. Fill all dates you need and apply fillna(0) if converting to a DataFrame.

For each holiday type, the reverse lag output uses a single column such as is_easter_in_next_days. If a matching holiday occurs within the configured lag window, the column contains an approach counter that increases toward the holiday. By default, the highest value is on the day before the holiday. Set lag_peak_on_holiday=True if the holiday date itself should receive the maximum value. Otherwise it stays empty and can be filled with 0 after conversion to a DataFrame.

Example Output

[
	{
		"date": "2023-04-07",
		"is_easter": 0,
		"is_christmas": 0,
		"is_bank_holiday": 1,
		"is_easter_in_next_days": 2,
		"is_bank_holiday_in_next_days": 2
	},
	{
		"date": "2023-04-09",
		"is_easter": 1,
		"is_christmas": 0,
		"is_bank_holiday": 1
	},
	...
]

License

MIT License. See LICENSE file.