In jameslairdsmith/gs: A grammar of recurring calendar events

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(gs)
library(magrittr)

In this brief vignette I will give some examples to demonstrate how a set of national holidays can be put together using the gs grammar.

Using the grammar this way means that we can avoid the hassle of ennumerating all the possible dates for national holidays and can rather rely on the pre-scripted logic to produce the apppriate dates for us when we request them.

In the future I plan to release a package that will catalogue this holiday logic for a wide set of countries. The purpose of this vignette is only to provide some illustrative examples.

If you haven't heard of the gs package before or you are unsure what the grammar is, I recommend looking at the introductory vignette included in the package.

General

There are certain holidays which are common in many countries. One advantage of the gs grammar is that the schedule objects only need to be created once and can be re-used as necessary when they are required.

These common holidays are as follows:

on_new_years_day <- on_yday(1)
on_christmas_day <- only_occur(on_mday(25), in_month("Dec"))
on_boxing_day <- only_occur(on_mday(26), in_month("Dec"))

Easter

The date of Easter is notoriously tricky to calculate. For this reason there is a shortcut function provided for it in gs called on_easter_sunday(). This shortcut relies on the algorithm provided in the timeDate package.

schedule_days(on_easter_sunday(), from = 2010, to = 2020)

There are also equivalent shortcut functions for on_good_friday() and on_easter_monday() etc.

United States Federal Holidays

In this next example we will build a schedule of the federal holidays in the United States using the gs grammar. Each chunk of code below encodes the rule of the holiday.

The gs grammer is designed to be readable, so you should be able to see what the syntax is doing just by reading it. For example in the first chunk below we are creating a schedule of Martin Luther King Jr. Days, which in the US occur on the third Monday of January every year. To do this we find the intersection (using only_occur()) of all days which are the third (using on_third()) Monday (using on_wday("Mon")) of every month with the schedule of days occuring in Janurary (using in_month("Jan")). The other holidays can be read similarly.

on_mlk_day <- 
  on_third(on_wday("Mon"), within_given = "month") %>% 
  only_occur(in_month("Jan"))

on_presidents_day <- 
  on_third(on_wday("Mon"), within_given = "month") %>% 
  only_occur(in_month("Feb"))

on_memorial_day <-
  on_last(on_wday("Mon"), within_given = "month") %>% 
  only_occur(in_month("May"))

on_us_independence_day <- only_occur(on_mday(4), in_month("July"))

on_labor_day <-
  on_first(on_wday("Mon"), within_given = "month") %>% 
  only_occur(in_month("Sep"))

on_columbus_day <-
  on_second(on_wday("Mon"), within_given = "month") %>% 
  only_occur(in_month("Oct"))

on_veterans_day <- only_occur(on_mday(11), in_month("Nov"))

on_us_thanksgiving <- 
  on_fourth(on_wday("Thu"), within_given = "month") %>% 
  only_occur(in_month("Nov"))

To make these holidays into a single schedule, we combine them using the also_occur() function, which finds the union of two schedules. With the help of the pipe (%>%) operator, this forms a neat chain of operations.

on_us_federal_holidays <-
  on_new_years_day %>% 
  also_occur(on_mlk_day) %>% 
  also_occur(on_presidents_day) %>% 
  also_occur(on_memorial_day) %>% 
  also_occur(on_us_independence_day) %>% 
  also_occur(on_labor_day) %>% 
  also_occur(on_columbus_day) %>% 
  also_occur(on_veterans_day) %>% 
  also_occur(on_us_thanksgiving) %>% 
  also_occur(on_christmas_day)

This schedule is then available for use. For example we can use the schedule_days() function to retrieve for us the occurances of US federal holidays in 2019 and 2020.

schedule_days(on_us_federal_holidays, from = 2019, to = 2020)

jameslairdsmith/gs documentation built on July 19, 2023, 12:49 a.m.