tk_augment_holiday: Add many holiday features to the data

In business-science/timekit: A Tool Kit for Working with Time Series

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)

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")

business-science/timekit documentation built on Feb. 2, 2024, 2:51 a.m.