Dint: Integer Representations of Calendar Periods

Stefan Fleck

2020-01-07

library(dint)

dint helps you with working with year-quarter, year-month and year-isoweek dates. It stores them in an easily human readable integer format, e.q 20141 for the first quarter of 2014 and so forth. If you are already using such integers to represent dates, dint can make many common operations easier for you.

dint is implemented in base R and comes with zero external dependencies. Even if you don’t work with such special dates directly, dint can still help you at formatting dates, labelling plot axes, or getting first / last days of calendar periods (quarters, months, isoweeks).

date_xx Vectors

dint provides 4 different S3 classes that inherit from date_xx1.

Creation

date_xx vectors can be created using explicit constructors…

date_yq(2015, 1)
#> [1] "2015-Q1"
date_ym(c(2015, 2016), c(1, 2))
#> [1] "2015-M01" "2016-M02"
date_yw(c(2008, 2009), 1)
#> [1] "2008-W01" "2009-W01"

..or through coercion of Dates or integers

as_date_yq(Sys.Date())
#> [1] "2020-Q1"
as_date_yq(20141)   # the last digit is interpreted as quarter
#> [1] "2014-Q1"
as_date_ym(201412)  # the last two digits are interpreted as month
#> [1] "2014-M12"
as_date_yw("2018-01-01")  # anything else that can be parsed by as.Date() works
#> [1] "2018-W01"

Coercion

You can coerce Dates to any date_xx subclass with as_date_**()

d <- as.Date("2018-05-12")
as_date_yq(d)
#> [1] "2018-Q2"
as_date_ym(d)
#> [1] "2018-M05"
as_date_yw(d)
#> [1] "2018-W19"
as_date_y(d)
#> [1] "2018"

Conversely, you can convert date_xx back to R Dates

q <- date_yq(2015, 1)
as.Date(q)
#> [1] "2015-01-01"
as.POSIXlt(q)
#> [1] "2015-01-01 UTC"

as.POSIXct() creates datetimes in UTC/GMT, so the result might not always be as expected, depending on your local timezone.

as.POSIXct(q)
#> [1] "2015-01-01 01:00:00 CET"
as.POSIXct(q, tz = "GMT")
#> [1] "2015-01-01 01:00:00 CET"
print(as.POSIXct(q), tz = "GMT")
#> [1] "2015-01-01 GMT"
print(as.POSIXct(q), tz = "CET")
#> [1] "2015-01-01 01:00:00 CET"

Arithmetic and Sequences

All date_xx support addition, subtraction and sequence generation.

q <- date_yq(2014, 4)
q + 1
#> [1] "2015-Q1"
q - 1
#> [1] "2014-Q3"
seq(q - 2, q + 2)
#> [1] "2014-Q2" "2014-Q3" "2014-Q4" "2015-Q1" "2015-Q2"

m <- date_ym(2014, 12)
m + 1
#> [1] "2015-M01"
m - 1
#> [1] "2014-M11"
seq(m - 2, m + 2)
#> [1] "2014-M10" "2014-M11" "2014-M12" "2015-M01" "2015-M02"

w <- date_yw(2017, 33)
w + 1
#> [1] "2017-W34"
w - 1
#> [1] "2017-W32"
seq(w - 2, w + 2)
#> [1] "2017-W31" "2017-W32" "2017-W33" "2017-W34" "2017-W35"

Accessors

date_xx Components

You can access components of date_xx (e.g the quarter of a date_yq) with accessor functions. You can also use these functions to convert between date_xx vectors.

lubridate Compatibility Accessors

If you use lubridate, you can just use the slightly less verbose lubridate accessors

You can get the first and last days of calendar periods with dint

These functions work with normal dates

Formatting

format() Methods

Formatting date_xx vectors is easy and uses a subset of the placeholders of base::strptime() (+ %q for quarters).

Shorthands

dint also provides all-in-one functions for common tasks

ggplot2: Axis Labels

library(ggplot2)

Labelling date_xx Vectors

dint implements scale_date_**() and date_**_breaks() that provide nicely labeled axes for ggplots by default

Labelling Date Vectors

If you use R Date vectors, you can still use the formatting functions supplied by dint to generate nice axis labels.


  1. date_xx is just a superclass for all dint date classes, you do not need to use it directly