holideh (pronounced “holiday”, but Canadian, eh?) provides tools for working with business days and Canadian holidays, including wrappers for the Canada Holidays API.
Installation
You can install the package using:
install.packages("holideh")The development version can be installed using
# install.packages("pak")
pak::pak("adamoshen/holideh")or
# install.packages("remotes")
remotes::install_github("adamoshen/holideh")Basic usage
library(magrittr)
library(tibble)
library(purrr)
#>
#> Attaching package: 'purrr'
#> The following object is masked from 'package:magrittr':
#>
#> set_names
library(lubridate)
#>
#> Attaching package: 'lubridate'
#> The following objects are masked from 'package:base':
#>
#> date, intersect, setdiff, union
library(holideh)Retrieving federal holidays
Federal holidays can be retrieved from the Canada Holidays API as a tibble:
get_holidays(2027, federal = TRUE)
#> # A tibble: 12 × 7
#> date observed_date name_en name_fr federal holiday_id provinces
#> <date> <date> <chr> <chr> <lgl> <int> <list>
#> 1 2027-01-01 2027-01-01 New Year's Day Jour d… TRUE 1 <tibble>
#> 2 2027-03-26 2027-03-26 Good Friday Vendre… TRUE 8 <tibble>
#> 3 2027-03-29 2027-03-29 Easter Monday Lundi … TRUE 9 <tibble>
#> 4 2027-05-24 2027-05-24 Victoria Day Fête d… TRUE 12 <tibble>
#> 5 2027-07-01 2027-07-01 Canada Day Fête d… TRUE 16 <tibble>
#> 6 2027-08-02 2027-08-02 Civic Holiday Congé … TRUE 19 <tibble>
#> 7 2027-09-06 2027-09-06 Labour Day Fête d… TRUE 27 <tibble>
#> 8 2027-09-30 2027-09-30 National Day f… Journé… TRUE 29 <tibble>
#> 9 2027-10-11 2027-10-11 Thanksgiving Action… TRUE 31 <tibble>
#> 10 2027-11-11 2027-11-11 Remembrance Day Jour d… TRUE 32 <tibble>
#> 11 2027-12-25 2027-12-27 Christmas Day Noël TRUE 33 <tibble>
#> 12 2027-12-26 2027-12-28 Boxing Day Lendem… TRUE 34 <tibble>The date column is the official calendar date of the holiday, while the observed_date column is the date when the holiday is observed (celebrated). For example, in the Canadian federal public service, if New Year’s Day was a Sunday, it would be observed on the Monday, meaning there would be no work on Monday. Obviously, how holidays are observed will depend on your employer.
Retrieving holidays by province/territory
Holidays celebrated by a single province/territory can also be retrieved, as a tibble, from the Canada Holidays API by providing the two-letter abbreviation for the province/territory:
get_province("ON", 2027)
#> # A tibble: 9 × 10
#> date observed_date name_en name_fr federal holiday_id province_id
#> <date> <date> <chr> <chr> <lgl> <int> <chr>
#> 1 2027-01-01 2027-01-01 New Year's Day Jour d… TRUE 1 ON
#> 2 2027-02-15 2027-02-15 Family Day Fête d… FALSE 5 ON
#> 3 2027-03-26 2027-03-26 Good Friday Vendre… TRUE 8 ON
#> 4 2027-05-24 2027-05-24 Victoria Day Fête d… TRUE 12 ON
#> 5 2027-07-01 2027-07-01 Canada Day Fête d… TRUE 16 ON
#> 6 2027-09-06 2027-09-06 Labour Day Fête d… TRUE 27 ON
#> 7 2027-10-11 2027-10-11 Thanksgiving Action… TRUE 31 ON
#> 8 2027-12-25 2027-12-27 Christmas Day Noël TRUE 33 ON
#> 9 2027-12-26 2027-12-28 Boxing Day Lendem… TRUE 34 ON
#> # ℹ 3 more variables: province_name_en <chr>, province_name_fr <chr>,
#> # source_info <list>Additional helpers
Consider the following setup:
- In 2027, Christmas (December 25) and Boxing Day (December 26) fall on Saturday and Sunday, respectively.
- Therefore, they will be observed on Monday December 27 and Tuesday December 28, respectively.
holiday_date <- ymd(c("2027-12-25", "2027-12-26"))
observed_date <- ymd(c("2027-12-27", "2027-12-28"))
calendar <- seq(from = ymd("2027-12-24"), to = ymd("2027-12-30"), by = "1 day")holideh contains additional helpers for other operations:
-
is_weekend(): Given a vector of dates, detects whether the supplied dates are a weekend (typically Saturday or Sunday, but can be modified).set_names(is_weekend(calendar), calendar) #> 2027-12-24 2027-12-25 2027-12-26 2027-12-27 2027-12-28 2027-12-29 2027-12-30 #> FALSE TRUE TRUE FALSE FALSE FALSE FALSE -
is_holiday(): Given a vector of dates and a vector of holiday dates, detects whether the supplied dates are a holiday. Here, it is important to consider whether your analysis requires official holiday dates or observed holiday dates.set_names(is_holiday(calendar, holiday_date), calendar) #> 2027-12-24 2027-12-25 2027-12-26 2027-12-27 2027-12-28 2027-12-29 2027-12-30 #> FALSE TRUE TRUE FALSE FALSE FALSE FALSE set_names(is_holiday(calendar, observed_date), calendar) #> 2027-12-24 2027-12-25 2027-12-26 2027-12-27 2027-12-28 2027-12-29 2027-12-30 #> FALSE FALSE FALSE TRUE TRUE FALSE FALSE -
is_bizday(): Given a vector of dates and a vector of holiday dates (and optionally, a vector of what is considered a “weekend”), detects whether the supplied dates are a business day:set_names(is_bizday(calendar, holiday_date), calendar) #> 2027-12-24 2027-12-25 2027-12-26 2027-12-27 2027-12-28 2027-12-29 2027-12-30 #> TRUE FALSE FALSE TRUE TRUE TRUE TRUE set_names(is_bizday(calendar, observed_date), calendar) #> 2027-12-24 2027-12-25 2027-12-26 2027-12-27 2027-12-28 2027-12-29 2027-12-30 #> TRUE FALSE FALSE FALSE FALSE TRUE TRUE
As is_weekend(), is_holiday(), and is_bizday() are predicate functions (functions that return either TRUE or FALSE), they can be used in conjunction with purrr::keep() and purrr::discard().
For more detailed usages, see the Get Started vignette.