---
title: "Calendrical Computations Using `tind` Package"
author: "Grzegorz Klima"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Calendrical Computations Using `tind` Package}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

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


```{r echo=FALSE}
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.
```{r color}
library("tind")
```


## Current Date and Time

Current date and time can be checked using functions `today()`
and `now()`.
```{r}
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.
```{r}
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.

```{r}
(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.

```{r}
(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).
```{r}
(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`).
```{r}
(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:
```{r}
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:
```{r}
(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:
```{r}
(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.
```{r}
(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.
```{r}
(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:
```{r}
nth_dw_in_month(4, 4, 201911)
```
Black Friday is the day after Thanksgiving:
```{r}
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:
```{r}
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:
```{r}
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.
```{r}
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.

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


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


```{r}
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))
}
```


```{r}
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):
```{r}
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.
```{r}
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.
```{r}
(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:
```{r}
(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")
```