holiday-rlag 1.0.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)
• 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 the distance in days to the nearest upcoming holiday. 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
	},
	...
]

License

MIT License. See LICENSE file.