dint helps you with working with year-quarter, year-month andyear-isoweek dates. It stores them in an easily human readable integerformat, e.q20141 for the first quarter of 2014 and soforth. If you are already using such integers to represent dates, dintcan make many common operations easier for you.

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

date_xx Vectors

dint provides 4 different S3 classes that inherit fromdate_xx¹.

date_yq for year-quarter dates
date_yw for year-month dates
date_yw for year-isoweek dates. Please note that theyear for isoweeks does not necessarily correspond to the calendar yearwikipedia
date_y for storing years. This class exists forconsistency and provides little advantage over storing years as bareintegers. The main use of this class is in package development when youwant to write your own generics and methods for years.

Creation

date_xx vectors can be created using explicitconstructors…

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 ofDates orintegers

as_date_yq(Sys.Date())#> [1] "2024-Q4"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 coerceDates to anydate_xxsubclass withas_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 convertdate_xx back to RDates

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 resultmight not always be as expected, depending on your local timezone.

as.POSIXct(q)#> [1] "2015-01-01 UTC"as.POSIXct(q,tz ="GMT")#> [1] "2015-01-01 GMT"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

Alldate_xx support addition, subtraction and sequencegeneration.

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 ofdate_xx (e.g the quarter ofadate_yq) with accessor functions. You can also use thesefunctions to convert betweendate_xx vectors.

q<-date_yq(2014,4)get_year(q)#> [1] 2014get_quarter(q)#> [1] 4get_month(q)# defaults to first month of quarter#> [1] 10get_isoweek(q)#> [1] 40m<-date_ym(2014,12)get_year(m)#> [1] 2014get_quarter(m)#> [1] 4get_month(m)#> [1] 12get_isoweek(m)#> [1] 49w<-date_yw(2014,33)get_year(w)#> [1] 2014get_quarter(w)#> [1] 3get_month(w)#> [1] 8get_isoweek(w)#> [1] 33

lubridate Compatibility Accessors

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

suppressPackageStartupMessages(library(lubridate))year(q)#> [1] 2014quarter(q)#> [1] 4month(q)#> [1] 10

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

q<-date_yq(2015,1)first_of_quarter(q)# the same as as.Date(q), but more explicit#> [1] "2015-01-01"last_of_quarter(q)#> [1] "2015-03-31"

These functions work with normal dates

d<-as.Date("2018-05-12")first_of_year(d)#> [1] "2018-01-01"last_of_year(d)#> [1] "2018-12-31"first_of_quarter(d)#> [1] "2018-04-01"last_of_quarter(d)#> [1] "2018-06-30"first_of_month(d)#> [1] "2018-05-01"last_of_month(d)#> [1] "2018-05-31"first_of_isoweek(d)#> [1] "2018-05-07"last_of_isoweek(d)#> [1] "2018-05-13"# Alternativeley you can use these:first_of_yq(2012,2)#> [1] "2012-04-01"last_of_ym(2012,2)#> [1] "2012-02-29"last_of_yw(2011,52)#> [1] "2012-01-01"

Formatting

format() Methods

Formattingdate_xx vectors is easy and uses a subset ofthe placeholders ofbase::strptime() (+%q forquarters).

q<-date_yq(2014,4)format(q,"%Y-Q%q")# iso/default#> [1] "2014-Q4"format(q,"%Y.%q")#> [1] "2014.4"format(q,"%y.%q")#> [1] "14.4"m<-date_ym(2014,12)format(m,"%Y-M%m")# iso/default#> [1] "2014-M12"w<-date_yw(2014,1)format(w,"%Y-W%V")# iso/default#> [1] "2014-W01"

Shorthands

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

format_yq(Sys.Date())#> [1] "2024-Q4"format_yq_short(Sys.Date())#> [1] "2024.4"format_yq_shorter(Sys.Date())#> [1] "24.4"format_ym(Sys.Date())#> [1] "2024-M11"format_yw(Sys.Date())#> [1] "2024-W47"

ggplot2: Axis Labels

library(ggplot2)

Labelling date_xx Vectors

dint implementsscale_date_**() anddate_**_breaks() that provide nicely labeled axes forggplots by default

q<-data.frame(time  =seq(date_yq(2016,1),date_yq(2016,4)),value =rnorm(4))m<-data.frame(time  =seq(date_ym(2016,8),date_ym(2016,11)),value =rnorm(4))w<-data.frame(time  =seq(date_yw(2016,48),date_yw(2017,1)),value =abs(rnorm(6)))w2<-data.frame(time  =seq(date_yw(2016,1),date_yw(2019,1)),value =abs(rnorm(157)))ggplot(q,aes(x = time,y = value))+geom_point()ggplot(m,aes(x = time,y = value))+geom_line()+scale_x_date_ym(labels = format_ym_shorter)ggplot(w,aes(x = time,y = value))+geom_col()+scale_x_date_yw(labels = format_yw_iso)ggplot(w2,aes(x = time,y = value))+geom_smooth()#> `geom_smooth()` using method = 'loess' and formula = 'y ~ x'

Labelling Date Vectors

If you use RDate vectors, you can still use theformatting functions supplied by dint to generate nice axis labels.

x<-data.frame(time  =seq(as.Date("2016-01-01"),as.Date("2016-08-08"),by ="day"),value =rnorm(221))p<-ggplot(  x,aes(x = time,y = value)  )+geom_point()p+ggtitle("iso")+ggtitle("default")p+scale_x_date(labels = format_yq_iso)+ggtitle("date_yq_iso")p+scale_x_date(labels = format_ym_short)+ggtitle("date_ym_short")p+scale_x_date(labels = format_yw_shorter)+ggtitle("date_yw_shorter")

Movatterモバイル変換

Dint: Integer Representations of CalendarPeriods

Stefan Fleck

2024-11-20