actuaryr-vignette

You can load actuaryr package with:

library(actuaryr)

Date reference functions

First and last days of months, quarters and years are of special meaning for business reporting.

The business reports are usually created for the last day of some period, like a month or a year. They enclose data for the first day of this period up to the last. If you create your report in the middle of the period, you may need to quickly refer to these dates.

The dref_ prefix stands for date reference functions. The functions with the dref_ prefix return a reference date to the base date.

Reference dates within a time period

The functions work within three types of periods:

  • a month
  • a quarter
  • an year

The functions return one of the four types of reference dates:

  • the first day
  • the first working day
  • the last day
  • the last working day

The names of functions combine the dref_ prefix and the first letters of the chosen reference date.

For example, dref_fdoy() returns the first day of an year.

The table summarizes all date reference functions.

of month of quarter of year
first day dref_fdom() dref_fdoq() dref_fdoy()
first working day dref_fwdom() dref_fwdoq() dref_fwdoy()
last day dref_ldom() dref_ldoq() dref_ldoy()
last working day dref_lwdom() dref_lwdoq() dref_lwdoy()

All functions take the argument date, which is the base date. The functions return the result in reference to the base date. The functions always work within a specific period: a month, a quarter or an year.

Monthly periods

The reference dates in the image below can be retrieved with the following functions:

  • dref_fdom() - dark blue
  • dref_fwdom() - light blue
  • dref_ldom() - light green
  • dref_lwdom() - dark green

The base date has been marked with orange.

dref_fdom("2020-02-14")
#> [1] "2020-02-01"
dref_fwdom("2020-02-14")
#> [1] "2020-02-03"
dref_ldom("2020-02-14")
#> [1] "2020-02-29"
dref_lwdom("2020-02-14")
#> [1] "2020-02-28"

Quarterly periods

The reference dates in the image below can be retrieved with the following functions:

  • dref_fdoq() - dark blue
  • dref_fwdoq() - light blue
  • dref_ldoq() - light green
  • dref_lwdoq() - dark green

The base date has been marked with orange.

Watch out! The first day in this time period is the same as the first working day in this time period. The last day of this time period is the same as the last working day of this time period. Hence, the same day is marked with two colors (darker and lighter).

dref_fdoq("2020-05-24")
#> [1] "2020-04-01"
dref_fwdoq("2020-05-24")
#> [1] "2020-04-01"
dref_ldoq("2020-05-24")
#> [1] "2020-06-30"
dref_lwdoq("2020-05-24")
#> [1] "2020-06-30"

Yearly periods

The reference dates in the image below can be retrieved with the following functions:

  • dref_fdoy() - dark blue
  • dref_fwdoy() - light blue
  • dref_ldoy() - light green
  • dref_lwdoy() - dark green

The base date has been marked with orange.

Watch out! The first day in this time period is the same as the first working day in this time period. The last day of this time period is the same as the last working day of this time period. Hence, the same day is marked with two colors (darker and lighter).

dref_fdoy("2020-09-21")
#> [1] "2020-01-01"
dref_fwdoy("2020-09-21")
#> [1] "2020-01-01"
dref_ldoy("2020-09-21")
#> [1] "2020-12-31"
dref_lwdoy("2020-09-21")
#> [1] "2020-12-31"

Reference dates from the previous period

The functions return the last day of the previous month, quarter or year. These functions might be of use if you are preparing, for example, the results for the first quarter of 2020 (Q1 2020) and want to compare them against the year-end results (YE 2019).

The functions are:

  • dref_mtd() - returns month-to-date
  • dref_qtd() - returns quarter-to-date
  • dref_ytd() - returns year-to-date

There is no distinction between days and working days. dref_mtd(), dref_qtd() and dref_ytd() always return the last day of the preceding time period.

In the images below, the base dates have been marked with orange and the reference dates have been marked with green.

Month-to-date

dref_mtd("2020-02-14")

Quarter-to-date

dref_qtd("2020-05-24")

Year-to-date

dref_ytd("2020-09-21")

Compare

A big chunk of actuarial life consists of comparing things.

After preparing assumptions tables and policy data for valuation models, it’s useful to check how they change over a reporting period to understand the magnitude of movements.

Also during the model development, it’s important to understand the impact of the development on the results. The regression analysis helps to understand the impact of each step.

The following approach is used within compare():

  • Only common columns are compared; the rest of the columns are ignored.
  • Only common rows are compared; if one data frame has more rows, the extra rows are removed.
  • If the same columns have different types, the weaker type gets coerced to the stronger type (where: logical < integer < double < character).
  • The comparison’s result depends on the type:
    • for numericals the absolute difference is returned,
    • for characters either the_same or different is returned.
x <- data.frame(
  v1 = c(1, 2, 3),
  v2 = c(1, 2, 3),
  v3 = c(1, 2, 3)
  )
y <- data.frame(
  v1 = c("1", "2", "3", "4"),
  v3 = rep(4, 4),
  stringsAsFactors = FALSE
  )
compare(x, y)