> For the complete documentation index, see [llms.txt](https://doc.verteego.com/verteego-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.verteego.com/verteego-doc/pipelines/forecasting-pipelines/calculators/temporal/bank_holidays_countdown.md).

# bank\_holidays\_countdown

Compute previous and next occurrence of bank holidays in different countries.

## Usage

{% hint style="info" %}
Compute previous and next occurrence of each bank holiday.

Given a **date\_col**, its format **date\_format**, and a country, it will generate two columns per bank holiday:

* number of days before next bank holiday occurrence
* number of day since last bank holiday occurrence

The bank holidays are the official bank holidays of the given country. They **will be anglicised**, such that it will be the same feature for Christmas in all countries, for instance.\
\
**`Actual dates` vs `Observed dates`:**

In some countries, we get observed bank holidays:

* the date when the **holiday is observed** from a civil standpoint *(shops closed, administrations closed),* which **can be the next day if the holiday falls on a sunday for instance**.
* In some countries, we **might get two events** in a year for a given holiday: the **event itself and its observed date**. In other countries or situations, we might only get one date per year for a holiday, sometimes observed and sometimes not.

<mark style="color:red;">**This calculator will not have any events qualified as**</mark><mark style="color:red;">**&#x20;**</mark><mark style="color:red;">**`observed`**</mark><mark style="color:red;">.</mark>

In cases where:

* **we get two events for a given holiday, within a 10 day distance ⇒** we will only **keep** the **original event**, **and discard the `observed` one**.
* **we only have an `observed` event ⇒** we will remove the notion of `observed` in its label, and keep the date as if it were the actual event.

**Exemple:**

For instance, in the UK, if we get *<mark style="color:green;">“Boxing Day”</mark>* on dec 25 and *<mark style="color:green;">“Boxing Day (Observed)”</mark>* on dec 26, we will keep the dec 25 event and discard the dec 26 one.

But in Columbia, where one year we might get an *<mark style="color:green;">“Epiphany”</mark>* event, and the next year an *<mark style="color:green;">“Epiphany (Observed)”</mark>* event, we will produce only “Epiphany” events.

This means that in countries where bank holidays are observed on other days when they fall on a Sunday, this calculator will not quite capture the closure of services.
{% endhint %}

This calculator can be used with the following method:

<mark style="color:red;">**`bank_holidays_countdown`**</mark>

Examples:

* get specific holidays for every country according to country code.

***

## Main Parameters

{% hint style="success" %}
**The bold options** represent the default values when the parameters are optional.
{% endhint %}

* *<mark style="color:blue;">input\_columns</mark>* \
  list of columns used as input of the calculators: only one column containing the date.
* *<mark style="color:blue;">output\_columns\_prefix</mark>*\
  prefix of the columns added when the output columns cannot be listed: prefix to use for the output columns, as this calculator adds several.
* *<mark style="color:blue;">global</mark>* *(true, **false)*** \
  Should this calculator be performed before data splitting during training for cross-validation
* *<mark style="color:blue;">steps</mark>* \[optionnal] *(**training, prediction**, postprocessing*)\
  List of steps in a pipeline where columns from this calculator are added to the data. Note that when the training option is listed, the calculator is actually added during preprocessing.
* *<mark style="color:blue;">store\_in\_model</mark>* \[optionnal] *(true, **false)*** \
  Please indicate whether the "calculated" columns by the calculator should be stored in the model or not to avoid recalculating them during prediction. This is only relevant if the calculated columns are added to both training and prediction. Without this parameter, the values will not be stored in the model. The following parameters only make sense if this parameter is set to *true*.
* *<mark style="color:blue;">stored\_columns</mark>* \[required if *<mark style="color:blue;">store\_in\_model</mark> is true*] \
  List indicating the columns to be stored among the *<mark style="color:blue;">output\_columns</mark>*.
* *<mark style="color:blue;">stored\_keys</mark>* \[required if *<mark style="color:blue;">store\_in\_model</mark> is true*] \
  List indicating the columns to use for identifying the correct values to join on the data for prediction among the stored values (logically, they are to be chosen from the *<mark style="color:blue;">input\_columns</mark>*).

***

## Specific Parameters

* *<mark style="color:blue;">country\_code:</mark>* \
  A column name for the column containing the country code, or a country code. The country code must be a two-letter code, as described here: <https://github.com/dr-prodigy/python-holidays> (ISO 3166-1 alpha-2).
* *<mark style="color:blue;">countdown\_type</mark>* \[optionnal]\
  List of columns to create, among `in` and `ago` countdowns. By default, both will be added.
* *<mark style="color:blue;">date\_format</mark>* \[optional]

  Format of the date provided, by default, will use *%Y-%m-%d*

***

## Examples

1. Here, we want to obtain holidays for two different countries: the US and the United Kingdom. Christmas and New Year are holidays in common for both countries. Thanksgiving is only for the US. It is better to use either  `in` or `ago` for the `countdown_type`, but not both at the same time, as otherwise features will become colinear. If the holiday does not exist for the country, you will obtain NULL.

```yaml
calculated_cols:
  bank_hols_cntdwn:
      method: bank_holidays_countdown
      input_columns:
      - receipt_date
      output_columns_prefix: 'bnk_hols_'
      params:
        country_code: country_code
        countdown_type:
        - in
```

<table><thead><tr><th width="152">receipt_date</th><th width="146">country_code</th><th width="236">bnk_hols__Thanksgiving_in</th><th width="256">bnk_hols__Christmas_Day_in</th><th>bnk_hols__New_Year_s_Day_in</th></tr></thead><tbody><tr><td>2021-01-01</td><td>US</td><td>328</td><td>358</td><td>0</td></tr><tr><td>2021-11-25</td><td>US</td><td>0</td><td>30</td><td>37</td></tr><tr><td>2021-12-25</td><td>US</td><td>334</td><td>0</td><td>7</td></tr><tr><td>2022-01-01</td><td>US</td><td>327</td><td>358</td><td>0</td></tr><tr><td>2022-11-24</td><td>US</td><td>0</td><td>31</td><td>38</td></tr><tr><td>2022-12-25</td><td>UK</td><td>null</td><td>0</td><td>7</td></tr><tr><td>2022-12-25</td><td>US</td><td>333</td><td>0</td><td>7</td></tr><tr><td>2023-01-01</td><td>UK</td><td>null</td><td>358</td><td>0</td></tr><tr><td>2023-01-01</td><td>US</td><td>326</td><td>358</td><td>0</td></tr></tbody></table>