Metadata-Version: 2.4
Name: holiday-rlag
Version: 0.1.6
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: holidays>=0.91
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 lagged indicators for holidays (e.g., is a holiday coming up in the next N days?)
- Flags for Easter, Christmas, and bank holidays

## Installation

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

## Requirements
- Python 3.12+
- [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)
```

## 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 lagged columns

**Returns:**
- `list[dict]`: List of dictionaries with holiday and lagged indicator flags

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

## Example Output

```json
[
	{
		"date": "2023-04-09",
		"is_easter": 1,
		"is_christmas": 0,
		"is_bank_holiday": 1,
		"is_easter_in_next_1_days": 1,
		...
	},
	...
]
```

## License

MIT License. See LICENSE file.
