R: Add many holiday features to the data

tk_augment_holiday {timetk} | R Documentation

## Add many holiday features to the data

### Description

Quickly add the "holiday signature" - sets of holiday features that correspond to calendar dates. Works with `dplyr` groups too.

### Usage

    tk_augment_holiday_signature(
      .data,
      .date_var = NULL,
      .holiday_pattern = ".",
      .locale_set = c("all", "none", "World", "US", "CA", "GB", "FR", "IT", "JP", "CH",
        "DE"),
      .exchange_set = c("all", "none", "NYSE", "LONDON", "NERC", "TSX", "ZURICH")
    )

### Arguments

`.data` | A time-based tibble or time-series object.
`.date_var` | A column containing either date or date-time values. If `NULL`, the time-based column will interpret from the object (tibble).
`.holiday_pattern` | A regular expression pattern to search the "Holiday Set".
`.locale_set` | Return binary holidays based on locale. One of: "all", "none", "World", "US", "CA", "GB", "FR", "IT", "JP", "CH", "DE".
`.exchange_set` | Return binary holidays based on Stock Exchange Calendars. One of: "all", "none", "NYSE", "LONDON", "NERC", "TSX", "ZURICH".

### Details

`tk_augment_holiday_signature` adds the holiday signature features. See `tk_get_holiday_signature()` (powers the augment function) for a full description and examples for how to use.

1. Individual Holidays

These are single holiday features that can be filtered using a pattern. This helps in identifying which holidays are important to a machine learning model. This can be useful for example in e-commerce initiatives (e.g. sales during Christmas and Thanskgiving).

2. Locale-Based Summary Sets

Locale-based holdiay sets are useful for e-commerce initiatives (e.g. sales during Christmas and Thanskgiving). Filter on a locale to identify all holidays in that locale.

3. Stock Exchange Calendar Summary Sets

Exchange-based holdiay sets are useful for identifying non-working days. Filter on an index to identify all holidays that are commonly non-working.

### Value

Returns a `tibble` object describing the holiday timeseries.

### See Also

Augment Operations:

- `tk_augment_timeseries_signature()` - Group-wise augmentation of timestamp features

- `tk_augment_holiday_signature()` - Group-wise augmentation of holiday features

- `tk_augment_slidify()` - Group-wise augmentation of rolling functions

- `tk_augment_lags()` - Group-wise augmentation of lagged data

- `tk_augment_differences()` - Group-wise augmentation of differenced data

- `tk_augment_fourier()` - Group-wise augmentation of fourier series

Underlying Function:

- `tk_get_holiday_signature()` - Underlying function that powers holiday feature generation

### Examples

    library(dplyr)
    library(timetk)

    dates_in_2017_tbl <- tibble(index = tk_make_timeseries("2017-01-01", "2017-12-31", by = "day"))

    # Non-working days in US due to Holidays using NYSE stock exchange calendar
    dates_in_2017_tbl %>%
        tk_augment_holiday_signature(
            index,
            .holiday_pattern = "^$",   # Returns nothing on purpose
            .locale_set      = "none",
            .exchange_set    = "NYSE")

    # All holidays in US
    dates_in_2017_tbl %>%
        tk_augment_holiday_signature(
            index,
            .holiday_pattern = "US_",
            .locale_set      = "US",
            .exchange_set    = "none")

    # All holidays for World and Italy-specific Holidays
    # - Note that Italy celebrates specific holidays in addition to many World Holidays
    dates_in_2017_tbl %>%
        tk_augment_holiday_signature(
            index,
            .holiday_pattern = "(World)|(IT_)",
            .locale_set      = c("World", "IT"),
            .exchange_set    = "none")

[Package timetk version 2.6.1 Index]