
<!-- README.md is generated from README.Rmd. Please edit that file -->

# holideh <img src="man/figures/logo.png" align="right"/>

<!-- badges: start -->

[![CRAN
status](https://www.r-pkg.org/badges/version/holideh)](https://CRAN.R-project.org/package=holideh)
![Downloads](https://cranlogs.r-pkg.org/badges/holideh?color=lightgrey)
<!-- badges: end -->

**holideh** (pronounced “holiday”, but Canadian, eh?) provides tools for
working with business days and Canadian holidays, including wrappers for
the [Canada Holidays API](https://canada-holidays.ca).

## Installation

You can install the package using:

``` r
install.packages("holideh")
```

The development version can be installed using

``` r
# install.packages("pak")
pak::pak("adamoshen/holideh")
```

or

``` r
# install.packages("remotes")
remotes::install_github("adamoshen/holideh")
```

## Basic usage

``` r
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](https://canada-holidays.ca) as a tibble:

``` r
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](https://canada-holidays.ca) by providing the two-letter
abbreviation for the province/territory:

``` r
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.

``` r
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).

  ``` r
  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.

  ``` r
  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:

  ``` r
  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](https://adamoshen.github.io/holideh/articles/holideh.html).
