Calendrical Computations Using `tind` Package

In tind: A Common Representation of Time Indices of Different Types

tind package provides an extensive set of functions for calendrical computations. These include: extraction of time index components, determination of properties of time periods (leap years, number of subperiods within a period), computation of dates of moveable observances, and calendar arithmetic. For applications in business and finance, computations involving business days (using different rolling conventions) and computation of accrual factors are provided.

options(crayon.enabled = TRUE)
knitr::knit_hooks$set(output = function(x, options) {
    paste0(
    '<pre class="r-output"><code>',
    fansi::sgr_to_html(x = htmltools::htmlEscape(x), warn = FALSE),
    '</code></pre>'
    )
})

Before proceeding, let us load the package.

library("tind")

Current Date and Time

Current date and time can be checked using functions today() and now().

today()
now()

By default, the system time zone (as returned by Sys.timezone()) is used. However, we can check the current time in other time zones. Let us do it for Tokyo, Warsaw, London, and New York.

now("Asia/Tokyo")
today("Asia/Tokyo")
now("Europe/Warsaw")
today("Europe/Warsaw")
now("Europe/London")
today("Europe/London")
now("America/New_York")
today("America/New_York")

Time Index Components (Year, Month, Day, ...)

tind package provides a collection of intuitively-named functions for extracting time index components, see examples below.

(nw <- now())
year(nw)
quarter(nw)
month(nw)
month(nw, labels = TRUE)
month(nw, labels = TRUE, abbreviate = FALSE)
week(nw)
day(nw)
day_of_week(nw)
day_of_week(nw, labels = TRUE)
day_of_week(nw, labels = TRUE, abbreviate = FALSE)
day_of_year(nw)
hour(nw)
am(nw)
pm(nw)
minute(nw)
second(nw)

Properties of Time Indices

The inherent irregularity of our calendar is well known. Years are divided into leap and non-leap ones, months have different numbers of days (and so do quarters and years), years have varying number of weeks (52 or 53 in ISO 8601). In many time zones Daylight Saving Time is used, which then leads to some days having more or less than 24 hours. The functions shown below allow to easily check properties of time indices at hand.

(tm <- tind(y = 2023:2024, m = c(10, 2), d = 29, H = 1, tz = "Europe/Warsaw"))
is.leap_year(tm)
days_in_year(tm)
weeks_in_year(tm)
days_in_quarter(tm)
days_in_month(tm)
hours_in_day(tm)
is.dst(tm)

Calendar Arithmetic

Time indices can be shifted using + and - operators and - can be used to compute time differences (returning objects of auxiliary tdiff class).

(x <- today())
x + 0:3
x - 0:3
x - 3:0
x - as.date("2000-01-01")

Operators %+y%, %-y%, %+m%, %-m%, %+d%, %-d%, etc. can be used to shift time indices by multiples of a given time unit. An alternative is to use time differences constructed by as.tdiff method or convenience functions years, qrtrs, mnths, weeks, days, hours, mins, and secs. (The naming was chosen in order to avoid conflicts with base functions months and quarters).

(x <- today())
x %+y% -1:1
x + years(-1:1)
x %+m% -1:1
x + mnths(-1:1)
x %+d% -1:1 # same as x + -1:1
(x <- now())
x %-h% 3:0
x - hours(3:0)
x %-min% 3:0
x - mins(3:0)
x %-s% 3:0 # same as x - 3:0
x - secs(3:0) # same as x - 3:0

Sequences of Time Indices

seq method for tind allows to easily construct series of time indices. The following code creates a sequence of months with a step of two months from November 2023 till April 2025:

seq(as.month("2023-11"), as.month("2025-04"), by = 2)

Consider the following problem: for a given month we need to construct a sequence of dates in that month. Note that the last day in a month is the day before the first day in the following month. The following piece of code does the job:

(m <- as.month("2025-03"))
seq(as.date(m), as.date(m + 1) - 1)

seq method for tind also accepts different types of time indices and automatically converts them. The two lines below create sequences from the beginning of current quarter till today and from today till the end of the quarter:

(td <- today())
seq(as.quarter(td), td)
seq(td, as.quarter(td))

Rounding Time Indices

floor_t and ceiling_t round time indices down or up given time unit or multiple of a unit. round_t returns the result of one of these two functions, whichever is closer.

(x <- tind(y = 2025, m = 3, d = 30))
floor_t(x, "w")
ceiling_t(x, "w")
round_t(x, "w")
floor_t(x, "m")
ceiling_t(x, "m")
round_t(x, "m")
floor_t(x, "2m")
ceiling_t(x, "2m")
round_t(x, "2m")
floor_t(x, "q")
ceiling_t(x, "q")
round_t(x, "q")
floor_t(x, "y")
ceiling_t(x, "y")
round_t(x, "y")

trunc_t truncates time indices changing type when possible.

(x <- date_time(x, H = "13:13:13.13"))
trunc_t(x, "s")
trunc_t(x, "min")
trunc_t(x, "h")
trunc_t(x, "d")
trunc_t(x, "w")
trunc_t(x, "m")
trunc_t(x, "q")
trunc_t(x, "y")

Determining Dates of Movable Observances / Calendar Events

It is common to define dates of movable holidays or observances as the first, second, third, fourth, or last occurrence of a particular day of week in a given month. In order to determine dates of such observances two functions can be used: nth_dw_in_month() and last_dw_in_month(). Days of week are numbered 1--7 with 1 denoting Monday and 7 Sunday (as in ISO 8601).

Thanksgiving in the US is observed on the fourth Thursday of November, which in 2019 was on:

nth_dw_in_month(4, 4, 201911)

Black Friday is the day after Thanksgiving:

nth_dw_in_month(4, 4, 201911) + 1

Daylight Saving Time in the EU begins (at least for now) on the last Sunday in March and ends on the last Sunday of October. In 2019 the two dates were:

last_dw_in_month(7, 201903)
last_dw_in_month(7, 201910)

During change to DST, the day is one hour shorter and during change back one hour longer:

hours_in_day(last_dw_in_month(7, 201903), "Europe/Warsaw")
hours_in_day(last_dw_in_month(7, 201910), "Europe/Warsaw")

In the Christian world, Easter is a very important feast and other many observances are set relative to it. Easter date in a given year can be determined using easter() function.

easter(2020:2025)

Creating and Working with Custom Calendars

The functions shown above can be used to create custom calendar functions, which can later be used for pretty printing calendars or calculations involving business days.

It is expected that a calendar function:

• takes vector of dates
• returns one of the three:
  • a logical vector of the same length as argument indicating business days,
  • a list of two logical vectors of the same length as argument indicating business days and holidays,
  • a list of three logical vectors of the same length as argument indicating business days, holidays, and other observances.

If a calendar function returns a list and second or third logical vector is named, the names are used by function calendar() when pretty printing calendar.

Two examples of calendar functions are provided below and can be used as templates for creating calendar functions for any country, area, or specific applications like trading days or shopping days.

An Example - Business Days and (Federal) Holidays in the US

Public holidays in the US have either fixed dates or are on nth or last day of week in a month.

The calendar function below returns a two-element list (business days and holidays). A programming trick (marked in the code) is used to name holidays.

calendar_US <- function(dd)
{
    dd <- as.tind(dd)
    y <- year(dd)
    m <- month(dd)
    d <- day(dd)
    newyear <- (m == 1) & (d == 1)
    martinlking <- (y >= 2000) & (m == 1) & (dd == nth_dw_in_month(3, 1, dd))
    presidentsday <- (m == 2) & (dd == nth_dw_in_month(3, 1, dd))
    memorialday <- (m == 5) & (dd == last_dw_in_month(1, dd))
    juneteenth <- (y >= 2021) & (m == 6) & (d == 19)
    independence <- (m == 7) & (d == 4)
    labor <- (m == 9) & (dd == nth_dw_in_month(1, 1, dd))
    columbus <- (m == 10) & (dd == nth_dw_in_month(2, 1, dd))
    veterans <- (m == 11) & (d == 11)
    thanksgiving <- (m == 11) & (dd == nth_dw_in_month(4, 4, dd))
    christmas <- (m == 12) & (d == 25)
    holiday <- newyear | martinlking | presidentsday |
               memorialday | juneteenth | independence |
               labor | columbus | veterans | thanksgiving |
               christmas
    # holiday names - a programming trick
    # names of holnms should be the same as names of logical vectors above
    names(holiday) <- rep("", length(holiday))
    holnms <- c(newyear = "New Year's Day",
                martinlking = "Birthday of Martin Luther King, Jr.",
                presidentsday = "Washington's Birthday",
                memorialday = "Memorial Day",
                juneteenth = "Juneteenth National Independence Day",
                independence = "Independence Day",
                labor = "Labor Day",
                columbus = "Columbus Day",
                veterans = "Veterans Day",
                thanksgiving = "Thanksgiving Day",
                christmas = "Christmas Day")
    lapply(names(holnms), function(nm) names(holiday)[get(nm)] <<- holnms[nm])
    # business days
    business <- !holiday & (day_of_week(dd) %in% 1:5)
    return (list(business = business, holiday = holiday))
}

Now we can use our function to print the calendar. Note that to obtain coloured output you have to have package crayon installed.

calendar(2020, calendar_US)
calendar(as.year(today()), calendar_US)
calendar("2020-01", calendar_US)
calendar(calendar = calendar_US)

An example - Business Days, Holidays, and Other Observances in Poland

Public holidays in Poland have either fixed dates or are placed relative to Easter.

The calendar function below returns a three-element list (business days, holidays, and other observances). The same programming trick as before is used to name holidays and other observances.

calendar_PL <- function(dd)
{
    dd <- as.tind(dd)
    y <- year(dd)
    m <- month(dd)
    d <- day(dd)
    # public holidays
    newyear <- (m == 1L) & (d == 1L)
    epiphany <- (y >= 2011L) & (m == 1L) & (d == 6L)
    easterd <- easter(dd) == dd
    eastermon <- easter(dd) + 1L == dd
    labour <- (m == 5L) & (d == 1L)
    constitution <- (m == 5L) & (d == 3L)
    pentecost <- easter(dd) + 49L == dd
    corpuschristi <- easter(dd) + 60L == dd
    assumption <- (m == 8L) & (d == 15L)
    allsaints <- (m == 11L) & (d == 1L)
    independence <- (m == 11L) & (d == 11L)
    christmaseve <- (m == 12L) & (d == 24L) & (y >= 2025)
    christmas <- (m == 12L) & (d == 25L)
    christmas2 <- (m == 12L) & (d == 26L)
    holiday <- newyear | epiphany |
               easterd | eastermon |
               labour | constitution |
               pentecost | corpuschristi |
               assumption |
               allsaints | independence |
               christmaseve | christmas | christmas2
    # holiday names
    names(holiday) <- rep("", length(holiday))
    holnms <- c(newyear = "New Year", epiphany = "Epiphany",
                easterd = "Easter", eastermon = "Easter Monday",
                labour = "Labour Day", constitution = "Constitution Day",
                pentecost = "Pentecost", corpuschristi = "Corpus Christi",
                assumption = "Assumption of Mary",
                allsaints = "All Saints Day", independence = "Independence Day",
                christmaseve = "Christmas Eve",
                christmas = "Christmas", christmas2 = "Christmas (2nd day)")
    lapply(names(holnms), function(nm) names(holiday)[get(nm)] <<- holnms[nm])
    # working/business days
    work <- !holiday & (day_of_week(dd) <= 5L)
    # other observances
    fatthursday <- easter(dd) - 52L == dd
    shrovetuesday <- easter(dd) - 47L == dd
    ashwednesday <- easter(dd) - 46L == dd
    goodfriday <- easter(dd) - 2L == dd
    primaaprilis <- (m == 4L) & (d == 1L)
    flagday <- (m == 5L) & (d == 2L)
    mothersday <- (m == 5L) & (d == 26L)
    childrensday <- (m == 6L) & (d == 1L)
    saintjohnseve <- (m == 6L) & (d == 23L)
    allsoulsday <- (m == 11L) & (d == 2L)
    saintandrewseve <- (m == 11L) & (d == 29L)
    saintnicholasday <- (m == 12L) & (d == 6L)
    christmaseve <- (m == 12L) & (d == 24L) & (y < 2025)
    newyeareve <- (m == 12L) & (d == 31L)
    other <- fatthursday | shrovetuesday | ashwednesday |
             goodfriday |
             primaaprilis |
             flagday |
             mothersday | childrensday | saintjohnseve |
             allsoulsday |
             saintandrewseve |
             saintnicholasday | christmaseve |
             newyeareve
    names(other) <- rep("", length(other))
    othernms <- c(fatthursday = "Fat Thursday",
                  shrovetuesday = "Shrove Tuesday",
                  ashwednesday = "Ash Wednesday",
                  goodfriday = "Good Friday",
                  primaaprilis = "All Fool's Day",
                  flagday = "Flag Day",
                  mothersday = "Mother's Day",
                  childrensday = "Children's Day",
                  saintjohnseve = "Saint John's Eve",
                  allsoulsday = "All Souls' Day",
                  saintandrewseve = "Saint Andrew's Eve",
                  saintnicholasday = "Saint Nicholas Day",
                  christmaseve = "Christmas Eve",
                  newyeareve = "New Year's Eve")
    lapply(names(othernms), function(nm) names(other)[get(nm)] <<- othernms[nm])

    return (list(work = work, holiday = holiday, other = other))
}

calendar(2020, calendar_PL)
calendar(as.year(today()), calendar_PL)
calendar("2020-06", calendar_PL)
calendar(calendar = calendar_PL)

Business Days

Calendar functions described above can be used for business day computations. tind provides the following functions that can be used in this context:

• bizday() for finding the closest business day (using different date rolling conventions) if the given day is not a one,
• bizday_diff() for computing number of business days between two dates,
• functions determining the first and the last business day in a given period: first_bizday_in_month(), last_bizday_in_month(), first_bizday_in_quarter(), last_bizday_in_quarter(),
• functions determining the number of business days in a given period: bizdays_in_month(), bizdays_in_quarter(), bizdays_in_year().

Some examples using bizday() and calendar functions presented earlier are provided below (January 16, 2023 was a public holiday in the US and August 15, 2023 in Poland):

calendar("2023-01", calendar = calendar_US)
bizday("2023-01-15", "p", calendar_US)
bizday("2023-01-15", "f", calendar_US)
bizday("2023-01-15", "mf2", calendar_US)
calendar("2023-08", calendar = calendar_PL)
bizday("2023-08-15", "p", calendar_PL)
bizday("2023-08-15", "f", calendar_PL)
bizday("2023-08-15", "mf2", calendar_PL)

The code below creates a table summarising the number of business days in months in 2023 in Poland and the US.

m <- as.month("2023-01") + 0:11
data.frame(month = m, PL = bizdays_in_month(m, calendar_PL),
                      US = bizdays_in_month(m, calendar_US))

Year Fractions and Accrual Factors

year_frac function returns time indices as year fractions in the form year + year fraction, where fraction is the number of periods (quarters, months, weeks, days, seconds) since the beginning of the year over total number of periods in the year.

(d <- as.date("2024-05-05"))
year_frac(d)
year(d) + (day_of_year(d) - 1) / days_in_year(d)
as.quarter(d)
year_frac(as.quarter(d))
year(d) + (quarter(d) - 1) / 4
as.month(d)
year_frac(as.month(d))
year(d) + (month(d) - 1) / 12
as.week(d)
year_frac(as.week(d))
year(d) + (week(d) - 1) / weeks_in_year(d)

daycount_frac allows to compute accrual factor using different day count conventions. Below we create a sequence of 5 consecutive International Money Market days and compute accrual factors between the first and the following four using different conventions:

(imm <- nth_dw_in_month(3, 3, tind(y = 2025, m = 12) + 3 * (0:4)))
daycount_frac(imm[1L], imm[-1L], "30/360")
daycount_frac(imm[1L], imm[-1L], "30E/360")
daycount_frac(imm[1L], imm[-1L], "ACT/ACT")
daycount_frac(imm[1L], imm[-1L], "ACT/365F")
daycount_frac(imm[1L], imm[-1L], "ACT/360")

tind documentation built on Dec. 28, 2025, 1:06 a.m.