This vignette is designed to introduce some of the common terminology used in almanac to get you up to speed on how to use the package. Along the way, we will see example usage of a number of the building blocks that will allow you to construct more complex recurrence objects.
A recurrence rule is a structured object that determines if a date should be counted as an event or not. At the most basic level, the job of a recurrence rule is to search through a pre-specified range of dates and flag any event dates in that range.
To build a recurrence rule, you start with a base recurrence frequency. There are 4 frequencies to choose from:
daily()
weekly()
monthly()
yearly()
Take the yearly() frequency, for example. By default, this will declare that 1 value per year is an event.
The return value of yearly() is a rrule object, short for “recurrence rule”. This base object is all you need to start doing something useful. For example, you can pass this rrule to alma_search() along with a from and to date, and it will return all of the events in that date range.
alma_search(from = "1990-01-01", to = "1995-12-31", on_yearly)
#> [1] "1990-01-01" "1991-01-01" "1992-01-01" "1993-01-01" "1994-01-01"
#> [6] "1995-01-01"What if we want a yearly value, but we want it on January 5th every year, rather than on the 1st? yearly() has an important argument called since that controls two things: the start date of the recurrence rule, and information such as the month, or the day of the month to use if no other conditions have been specified to override those.
The default of since is set to 1900-01-01, but this is arbitrary. It is because of this default that in the above example with alma_search() we get values on January 1st. Let’s change that.
on_yearly_jan_5 <- yearly(since = "1990-01-05")
alma_search("1990-01-01", "1995-12-31", on_yearly_jan_5)
#> [1] "1990-01-05" "1991-01-05" "1992-01-05" "1993-01-05" "1994-01-05"
#> [6] "1995-01-05"Now that the since date has been set to 1990, if we try and find yearly dates before 1990, they will not be included.
# Same result as above, because the 1988 and 1989 dates are not included.
alma_search("1988-01-01", "1995-12-31", on_yearly_jan_5)
#> [1] "1990-01-05" "1991-01-05" "1992-01-05" "1993-01-05" "1994-01-05"
#> [6] "1995-01-05"There is also an until argument to yearly() that controls the upper bound of the range to look in. This is arbitrarily set to 2100-01-01, but can be expanded or contracted as required.
I mentioned earlier that the job of a recurrence rule is to flag dates in a pre-specified range to be events or not. The dates that are flagged as events are known as the event set.
In the previous example, we used alma_search() to extract a subset of dates from the event set that were between from and to. You can get the entire event set with alma_events(). Notice that this is bounded by our custom since date, and the default until upper bound. Otherwise we’d have an infinite event set, which is nice in theory but bad in practice.
alma_events(on_yearly_jan_5)
#> [1] "1990-01-05" "1991-01-05" "1992-01-05" "1993-01-05" "1994-01-05"
#> [6] "1995-01-05" "1996-01-05" "1997-01-05" "1998-01-05" "1999-01-05"
#> [11] "2000-01-05" "2001-01-05" "2002-01-05" "2003-01-05" "2004-01-05"
#> [16] "2005-01-05" "2006-01-05" "2007-01-05" "2008-01-05" "2009-01-05"
#> [21] "2010-01-05" "2011-01-05" "2012-01-05" "2013-01-05" "2014-01-05"
#> [26] "2015-01-05" "2016-01-05" "2017-01-05" "2018-01-05" "2019-01-05"
#> [31] "2020-01-05" "2021-01-05" "2022-01-05" "2023-01-05" "2024-01-05"
#> [36] "2025-01-05" "2026-01-05" "2027-01-05" "2028-01-05" "2029-01-05"
#> [41] "2030-01-05" "2031-01-05" "2032-01-05" "2033-01-05" "2034-01-05"
#> [46] "2035-01-05" "2036-01-05" "2037-01-05" "2038-01-05" "2039-01-05"
#> [51] "2040-01-05" "2041-01-05" "2042-01-05" "2043-01-05" "2044-01-05"
#> [56] "2045-01-05" "2046-01-05" "2047-01-05" "2048-01-05" "2049-01-05"
#> [61] "2050-01-05" "2051-01-05" "2052-01-05" "2053-01-05" "2054-01-05"
#> [66] "2055-01-05" "2056-01-05" "2057-01-05" "2058-01-05" "2059-01-05"
#> [71] "2060-01-05" "2061-01-05" "2062-01-05" "2063-01-05" "2064-01-05"
#> [76] "2065-01-05" "2066-01-05" "2067-01-05" "2068-01-05" "2069-01-05"
#> [81] "2070-01-05" "2071-01-05" "2072-01-05" "2073-01-05" "2074-01-05"
#> [86] "2075-01-05" "2076-01-05" "2077-01-05" "2078-01-05" "2079-01-05"
#> [91] "2080-01-05" "2081-01-05" "2082-01-05" "2083-01-05" "2084-01-05"
#> [96] "2085-01-05" "2086-01-05" "2087-01-05" "2088-01-05" "2089-01-05"
#> [101] "2090-01-05" "2091-01-05" "2092-01-05" "2093-01-05" "2094-01-05"
#> [106] "2095-01-05" "2096-01-05" "2097-01-05" "2098-01-05" "2099-01-05"You can also check if an existing date is included in a recurrence rule’s event set with alma_in().
# Uses the 10th of the month, pulled from `since`
on_monthly <- monthly(since = "1990-01-10")
x <- as.Date("2000-01-08") + 0:5
x
#> [1] "2000-01-08" "2000-01-09" "2000-01-10" "2000-01-11" "2000-01-12"
#> [6] "2000-01-13"
x_in_set <- alma_in(x, on_monthly)
x_in_set
#> [1] FALSE FALSE TRUE FALSE FALSE FALSE
x[x_in_set]
#> [1] "2000-01-10"almanac attempts to be smart by caching the event set of a recurrence rule the first time that it is queried. This means that the first usage of a recurrence rule is generally slower than repeated uses.
since <- "1990-01-01"
on_weekly <- weekly(since = since)
# The first time is "slow"
system.time(alma_search(since, "2000-01-01", on_weekly))
#> user system elapsed
#> 0.073 0.003 0.056
# Repeated access is fast
system.time(alma_search(since, "2000-01-01", on_weekly))
#> user system elapsed
#> 0.000 0.000 0.001
# The entire event set is cached, so even if you change the arguments,
# the operation is still fast.
system.time(alma_search(since, "1990-05-01", on_weekly))
#> user system elapsed
#> 0.001 0.000 0.000So far we have worked with the base recurrence rules. Things get much more interesting when we start adding extra conditions to these rules. Conditions are ways to limit or expand a given recurrence rule to hone in on recurring dates that you are particularly interested in. All condition functions in almanac start with recur_*(). For example, let’s take a monthly rule, which defaults to give us 1 day per month, and expand it to give us every 4th and 16th day of the month.
on_4th_and_16th <- monthly(since = "2000-01-01") %>%
recur_on_mday(c(4, 16))
alma_search("2000-01-01", "2000-06-01", on_4th_and_16th)
#> [1] "2000-01-04" "2000-01-16" "2000-02-04" "2000-02-16" "2000-03-04"
#> [6] "2000-03-16" "2000-04-04" "2000-04-16" "2000-05-04" "2000-05-16"An important thing to note here is that even though our since date is on the first of the month, we are “overriding” that with the recurrence condition, so that information is not used.
Recurrence rules can continually be added to further refine your rule. When you add a condition to a rule, you get another rule back. Let’s try creating a rule for the recurring holiday, Labor Day. This recurs on the first Monday of September, yearly. To do this, we will:
Use a yearly() base since this happens 1 time per year.
Use recur_on_ymonth() to hone in on September.
Use recur_on_wday() to hone in on the first Monday of the month.
on_labor_day <- yearly() %>%
recur_on_ymonth("Sep") %>%
recur_on_wday("Monday", nth = 1)
alma_search("2000-01-01", "2005-01-01", on_labor_day)
#> [1] "2000-09-04" "2001-09-03" "2002-09-02" "2003-09-01" "2004-09-06"The nth argument of recur_on_wday() is especially useful for selecting from the end of the month. If we wanted the last Monday in September instead, we could do:
Recurrence rules are powerful tools on their own, but they aren’t enough to solve every task. Say you want to construct a rule that includes both Christmas and Labor Day as events. It would be impossible to construct this kind of event set using a single rule, but if you could bundle multiple rules together, one for Christmas and one for Labor Day, then it would be possible.
An rbundle is a bundle of recurrence schedules. A recurrence schedule, or rschedule, is an overarching term for both rrules and rbundles. There are three types of rbundles in almanac. Each create their event set by performing some kind of set operation on the event sets of the underlying rschedules that you added to the bundle.
runion() takes the union.
rintersect() takes the intersection.
rsetdiff() takes the set difference.
rbundles can also contain specialized dates that you want to forcibly include in the event set, called rdates, and ones that you want to forcibly exclude, called exdates.
The most useful rbundle is runion, as this allows you construct an event set that, for example, falls on multiple holidays and all weekends. The following creates an runion from rrules based on Christmas and Labor Day.
on_christmas <- yearly() %>%
recur_on_ymonth("Dec") %>%
recur_on_mday(25)
christmas_or_labor_day <- runion() %>%
add_rschedule(on_christmas) %>%
add_rschedule(on_labor_day)
alma_search("2000-01-01", "2002-01-01", christmas_or_labor_day)
#> [1] "2000-09-04" "2000-12-25" "2001-09-03" "2001-12-25"
christmas_or_labor_day_except_2000_labor_day <- christmas_or_labor_day %>%
add_exdates("2000-09-04")
alma_search("2000-01-01", "2002-01-01", christmas_or_labor_day_except_2000_labor_day)
#> [1] "2000-12-25" "2001-09-03" "2001-12-25"A recurrence bundle is a critical data structure in almanac. It serves as a general container to dump all of your company’s holiday and weekend recurrence rules.