> 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/events_countdown.md).

# events\_countdown

Computes previous and next occurrence of special events.

## Usage

{% hint style="info" %}
Compute previous and next occurrence of events.

Given a date\_col and its format date\_format generate two columns per event:

* number of days before next event occurrence
* number of day since last event occurrence

The events are defined as the following: -epiphanie -chandeleur -saint\_valentin -mardi\_gras -paques -pentecote -fete\_meres -fete\_musique -halloween -black\_friday -cyber\_monday -noel -nouvel\_an -nouvel\_an\_chinois -aid -ramadan -roch\_ha\_chanah -yom\_kippour -soukkot -hannoukkah -pourim -pessah -chavouot.

It will compute those columns for all the events at the same time.
{% endhint %}

This calculator can be used with the following method:

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

Examples:

* Compute the number of days between until or since new year.
* Compute the number of days between until the black friday, the chinese new year and christmas.

***

## 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: The list of columns that will be used to fill the output column.
* <mark style="color:blue;">output\_columns\_prefix</mark> \
  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;">countdown\_type</mark>* \[optionnal] *(in, ago)* \
  List of columns to create, among in and ago countdowns. By default, both will be added.
* *<mark style="color:blue;">date\_format</mark>* \[optionnal] \
  Format of the date provided, by default, will use %Y-%m-%d.

***

## Examples

1. Given a dataset with daily sales data with the sales date information (`receipt_date` ), the user want to get the number of day until special date like Christmas or the black friday.

   ```yaml
   calculated_cols:
   	special_event:
   	    method: events_countdown
   	    params:
   	      countdown_type:
   	        - in
   	    input_columns:
   	      - receipt_date
   	    output_columns_prefix: event
   ```

   **Output :**

   | receipt\_date | event\_black\_friday\_in | event\_noel\_in |
   | ------------- | ------------------------ | --------------- |
   | 2023-11-20    | 9                        | 34              |
   | 2023-11-25    | 4                        | 29              |
   | 2023-12-01    | 364                      | 23              |
2. Same context but now the user want the number of day since those special date.

   ```yaml
   calculated_cols:
   	special_event:
   	    method: events_countdown
   	    params:
   	      countdown_type:
   	        - ago
   	    input_columns:
   	      - receipt_date
   	    output_columns_prefix: event
   ```

   **Output :**

   | receipt\_date | event\_black\_friday\_ago | event\_noel\_ago |
   | ------------- | ------------------------- | ---------------- |
   | 2023-11-20    | 356                       | 331              |
   | 2023-11-25    | 361                       | 336              |
   | 2023-12-01    | 2                         | 342              |
3. In another case if the user want the number of day until and since in the same calculator.

   ```yaml
   calculated_cols:
   	special_event:
   	    method: events_countdown
   	    params:
   	    input_columns:
   	      - receipt_date
   	    output_columns_prefix: event
   ```