Skip to content
The Grammar of Schedules
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
R Document `until` Oct 3, 2019
inst/js Explore rrule.js implementation Sep 26, 2019
man Document `until` Oct 3, 2019
vignettes Finish icalendar vignette. Closes #8. Oct 4, 2019
.Rbuildignore Try appveyor to test on Windows Oct 3, 2019
.gitignore Start on intro vignette Oct 2, 2019
.travis.yml How about now Oct 3, 2019
DESCRIPTION Start on intro vignette Oct 2, 2019
LICENSE Rework to use `almanac` Sep 30, 2019 Rework to use `almanac` Sep 30, 2019
README.Rmd Add link to iCalendar vignette Oct 4, 2019 Add link to iCalendar vignette Oct 4, 2019
_pkgdown.yml Organize pkgdown reference Oct 2, 2019
almanac.Rproj Rename to official `almanac` version Sep 30, 2019
appveyor.yml Try appveyor to test on Windows Oct 3, 2019
codecov.yml Travis and codecov Sep 30, 2019


Travis build status Codecov test coverage Lifecycle: experimental AppVeyor build status


almanac implements a grammar of schedules, providing the fundamental building blocks to construct recurrence rules that identify “events” such as weekends or holidays. Constructing recurrence rules looks a little like this:

# Thanksgiving = "The fourth Thursday in November"
on_thanksgiving <- yearly() %>% 
  recur_on_ymonth("November") %>%
  recur_on_wday("Thursday", nth = 4)

After constructing a recurrence rule, it can be used to generate dates that are in the “recurrence set”.

sch_seq("2000-01-01", "2006-01-01", on_thanksgiving)
#> [1] "2000-11-23" "2001-11-22" "2002-11-28" "2003-11-27" "2004-11-25"
#> [6] "2005-11-24"

Or determine if a particular date is a part of the recurrence set.

sch_in(c("2000-01-01", "2000-11-23"), on_thanksgiving)
#> [1] FALSE  TRUE

It also allows you to shift an existing sequence of dates, “stepping over” dates that are in the recurrence set.

wednesday_before_thanksgiving <- "2000-11-22"

# Step forward 2 non-event days, stepping over thanksgiving
sch_step(wednesday_before_thanksgiving, n = 2, on_thanksgiving)
#> [1] "2000-11-25"

By combining multiple recurrence rules together, you can create larger “schedules” that form a collection of holidays, or events such as weekends. almanac comes with a prebuilt calendar_usa_federal() schedule that includes recurrence rules for the US holidays. Combining this with a recurrence rule of “on weekends” constructs a business calendar, which we can use to shift dates by, for example, “2 business days”.

on_weekends <- weekly() %>% 

on_us_holidays_and_weekends <- calendar_usa_federal() %>%

thursday_and_friday_before_labor_day <- c("2019-08-29", "2019-08-30")

# Steps over Saturday, Sunday, and Labor Day to the following Tuesday
# and Wednesday, aka "two business days" from now!
two_business_days_forward <- sch_step(
  n = 2,
  schedule = on_us_holidays_and_weekends

#> [1] "2019-09-03" "2019-09-04"

lubridate::wday(two_business_days_forward, label = TRUE)
#> [1] Tue Wed
#> Levels: Sun < Mon < Tue < Wed < Thu < Fri < Sat

Learning More

View the vignettes on the website to learn more about how to use almanac.

  • vignette("almanac")

  • vignette("adjust-and-shift")

  • vignette("quarterly")

  • vignette("icalendar")


You can NOT install the released version of almanac from CRAN with:

# NO! install.packages("almanac")

And the development version from GitHub with:

# install.packages("devtools")

Mac (OS-X) and Windows users should not have any problems installing almanac. Linux users need libv8 to install the dependency R package, V8. See the V8 installation instructions for more information. almanac uses ES5 JavaScript, so it does not require any “modern” JavaScript features and should work with the “old” V8 engine provided by Ubuntu versions before 19.04.


almanac has developed as a composite of ideas from multiple different libraries.

First off, it directly embeds the amazing JavaScript library rrule for the core recurrence set calculations. To do this, it uses the equally awesome R package, V8, from Jeroen Ooms.

The date shifting / adjusting functions are modeled after similar functions in QuantLib.

The author of gs, James Laird-Smith, has been a great collaborator as we have bounced ideas off of each other. gs attempts to solve a similar problem, but with a slightly different implementation. The hope is that gs and almanac will merge, as they currently overlap a large amount.

You can’t perform that action at this time.