Metadata-Version: 2.4
Name: holiday-rlag
Version: 1.1.0
Summary: Fetches holiday information from https://github.com/vacanza/holidays and applies reverse lagging (that is, future indicators) for time series training.
Author-email: Sven Flake <sflake@paiqo.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: build>=1.4.3
Requires-Dist: holidays>=0.91
Requires-Dist: pytest>=9.0.3
Requires-Dist: twine>=6.2.0
Dynamic: license-file

# holiday-rlag

Fetches holiday information using the [holidays](https://github.com/vacanza/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

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

## Requirements
- Python 3.11+
- [holidays](https://pypi.org/project/holidays/)

## Usage

```python
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

```json
[
	{
		"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.
