Grouped dates

Introduction

The goal of grates is to make it easy to group dates across a range of different time intervals. It defines a collection of classes and associated methods that, together, formalise the concept of grouped dates and are intuitive to use. Currently there are classes implemented for year-week, year-month, year-quarter and yearly groupings as well as for more flexible groupings across days and months.

To illustrate are examples we use data on a simulated outbreak of Ebola Virus Disease from the outbreaks package. For our purposes we are not concerned with analysing the data, instead we simply use the date_of_infection to help illustrate grates functionality. To start, let us first look at the daily data.

library(grates)
library(outbreaks)
library(ggplot2)

# Pull out the date of infection
x <- ebola_sim_clean$linelist$date_of_infection

# Calculate the daily incidence totals (ignoring missing values)
daily <- aggregate(list(cases = x), by = list(date = x), FUN = length)

# Add explicit zeros for days which aren't present
range <- seq.Date(min(daily$date), max(daily$date), by  = "day")
daily <- merge(data.frame(date = range), daily, by = "date", all.x = TRUE)
daily <- within(daily, cases[is.na(cases)] <- 0)

# plot the resulting output
ggplot(daily, aes(date, cases)) + geom_col(width = 1) + theme_bw()

#> 16148:16552
#> c(1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 0, 0, 1, 4, 3, 2, 3, 4, 2, 2, 0, 1, 0, 0, 1, 2, 2, 4, 2, 1, 2, 0, 3, 4, 2, 3, 1, 1, 3, 1, 1, 2, 2, 2, 2, 3, 3, 4, 2, 2, 2, 2, 1, 4, 2, 6, 2, 2, 6, 4, 0, 7, 1, 1, 3, 3, 1, 2, 2, 3, 6, 0, 2, 3, 4, 4, 5, 9, 6, 2, 5, 3, 2, 11, 2, 4, 8, 5, 7, 12, 5, 3, 4, 8, 5, 10, 9, 10, 8, 2, 5, 13, 7, 6, 14, 9, 11, 15, 9, 13, 13, 6, 6, 10, 18, 11, 18, 11, 10, 21, 21, 21, 13, 19, 16, 21, 19, 
#> 14, 26, 20, 15, 7, 13, 27, 28, 24, 31, 15, 23, 42, 30, 20, 31, 20, 32, 18, 23, 29, 41, 31, 33, 22, 21, 30, 33, 36, 25, 24, 18, 29, 31, 25, 24, 24, 31, 23, 28, 22, 17, 21, 22, 22, 43, 28, 24, 23, 25, 21, 19, 29, 23, 18, 22, 20, 22, 27, 27, 34, 14, 21, 15, 17, 24, 9, 28, 24, 26, 12, 21, 15, 13, 20, 13, 9, 17, 20, 17, 14, 9, 9, 14, 14, 10, 13, 13, 23, 11, 21, 21, 8, 17, 10, 11, 12, 11, 11, 4, 12, 11, 14, 11, 11, 10, 8, 10, 11, 10, 11, 8, 9, 11, 10, 11, 8, 8, 11, 12, 9, 6, 10, 8, 14, 12, 9, 7, 10, 9, 
#> 9, 7, 10, 11, 5, 6, 8, 11, 4, 11, 11, 11, 15, 8, 15, 6, 7, 8, 9, 3, 6, 9, 7, 3, 6, 9, 3, 8, 7, 9, 4, 7, 5, 8, 8, 2, 4, 2, 6, 6, 8, 7, 10, 6, 7, 10, 8, 9, 13, 13, 9, 9, 5, 7, 5, 8, 7, 6, 8, 4, 6, 7, 3, 5, 4, 5, 2, 4, 2, 5, 7, 6, 6, 6, 6, 1, 4, 9, 8, 3, 3, 3, 5, 6, 5, 3, 10, 2, 4, 6, 5, 5, 1, 4, 3, 2, 0, 9, 1, 2, 0, 4, 5, 3, 2, 3, 2, 3, 3, 2, 3, 1, 1, 1, 0, 2)
#> <environment>
#> <environment>
#> <environment>
#> ~date
#> ~cases
#> list(colour = "black", linewidth = 0.5, linetype = 1, lineend = "butt", arrow = FALSE, inherit.blank = TRUE)
#> list(fill = "white", colour = "black", linewidth = 0.5, linetype = 1, inherit.blank = TRUE)
#> list(family = "", face = "plain", colour = "black", size = 11, hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 0.9, margin = c(0, 0, 0, 0), debug = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.75, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.75, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = 90, lineheight = NULL, margin = c(0, 2.75, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = -90, lineheight = NULL, margin = c(0, 0, 0, 2.75), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = "grey30", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.2, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.2, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 0, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0.5, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> list(colour = "grey20", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 2.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list()
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list(fill = NULL, colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> c(5.5, 5.5, 5.5, 5.5)
#> 11
#> NULL
#> NULL
#> NULL
#> 1.2
#> NULL
#> NULL
#> 5.5
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.2
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> right
#> NULL
#> NULL
#> NULL
#> center
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> c(0, 0, 0, 0)
#> list()
#> 11
#> list(fill = "white", colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(fill = NA, colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> 5.5
#> NULL
#> NULL
#> list(colour = "grey92", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> list(colour = NULL, linewidth = 0.5, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> FALSE
#> list(fill = NULL, colour = "white", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = 1, vjust = 1, angle = NULL, lineheight = NULL, margin = c(5.5, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0.5, vjust = 0.5, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> topleft
#> NULL
#> c(5.5, 5.5, 5.5, 5.5)
#> list(fill = "grey85", colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> inherit
#> inside
#> list(family = NULL, face = NULL, colour = "grey10", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(4.4, 4.4, 4.4, 4.4), debug = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = -90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = 90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> 2.75
#> 2.75
#> <environment>
#> <environment>
#> <environment>
#> <environment>
#> date
#> cases

Bar chart of daily incidence (by date of infection) covering 2014-03-19 to 2015-04-27 inclusive. The graph peaks somewhere between September and November 2014. The “descent” from the peak tapers off slower than the initial “ascent”.

Week groupings

One of the more common date groupings is to a weekly level and grates defines three classes for users to work with, <grates_isoweek>, <grates_epiweek> and the <grates_yearweek>.

The most general of these is the <grates_yearweek> class. When creating a general yearweek object, users must specify an associated firstday of the week. This is a value from 1 to 7 representing Monday through Sunday. These objects can be constructed directly via the yearweek() or with the coercion function, as_yearweek().

Internally, yearweek objects are stored as the number of weeks (starting at 0) from the date of the firstday nearest the Unix Epoch (1970-01-01). Put more simply, the number of seven day periods from:

1969-12-29 for firstday equal to 1 (Monday)
1969-12-30 for firstday equal to 2 (Tuesday)
1969-12-31 for firstday equal to 3 (Wednesday)
1970-01-01 for firstday equal to 4 (Thursday)
1970-01-02 for firstday equal to 5 (Friday)
1970-01-03 for firstday equal to 6 (Saturday)
1970-01-04 for firstday equal to 7 (Sunday)

We use this anchoring around the Unix Epoch as it allows for very efficient conversion to, and from, date objects in which themselves anchor on 1970-01-01.

That said, most users should not need to consider this internal representation and should be able to use grates blissfully unaware.

<grates_isoweek> objects are used to represent ISO week dates as defined in ISO 8601. To expand further, it is easiest to quote from Wikipedia¹

ISO weeks start with Monday and end on Sunday. Each week’s year is the Gregorian year in which the Thursday falls. The first week of the year, hence, always contains 4 January. ISO week year numbering therefore usually deviates by 1 from the Gregorian for some days close to 1 January.

Functionally, a <grates_isoweek> is equivalent to a <grates_yearweek> object with an associated firstday value of 1 (Monday).

<grates_epiweek> objects are similar but instead of starting on a Monday, they start on a Sunday. They have been commonly used by the CDC in America and are sometimes called CDC weeks. Functionally they are equivalent to a <grates_yearweek> object with an associated firstday value of 7 (Sunday).

Continuing with the Ebola data from earlier we can now calculate weekly case counts:

# calculate the total number for across each week
week_dat <- with(daily,
    aggregate(
        list(cases = cases),
        by = list(week = as_isoweek(date)),
        FUN = sum
    )
)

head(week_dat)

#> 2307
#> 2308
#> 2309
#> 2310
#> 2311
#> 2312
#> 1
#> 0
#> 0
#> 1
#> 1
#> 4

# plot the output
(week_plot <-
    ggplot(week_dat, aes(week, cases)) +
    geom_col(width = 1, colour = "white") +
    theme_bw())

#> 2307:2365
#> c(1, 0, 0, 1, 1, 4, 8, 14, 11, 15, 11, 18, 19, 21, 20, 27, 31, 44, 54, 56, 73, 99, 130, 122, 193, 173, 211, 188, 169, 183, 157, 165, 143, 103, 100, 105, 90, 74, 68, 68, 71, 61, 56, 73, 45, 46, 36, 50, 71, 46, 34, 32, 37, 35, 27, 17, 22, 11, 2)
#> <environment>
#> <environment>
#> <environment>
#> ~week
#> ~cases
#> list(colour = "black", linewidth = 0.5, linetype = 1, lineend = "butt", arrow = FALSE, inherit.blank = TRUE)
#> list(fill = "white", colour = "black", linewidth = 0.5, linetype = 1, inherit.blank = TRUE)
#> list(family = "", face = "plain", colour = "black", size = 11, hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 0.9, margin = c(0, 0, 0, 0), debug = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.75, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.75, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = 90, lineheight = NULL, margin = c(0, 2.75, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = -90, lineheight = NULL, margin = c(0, 0, 0, 2.75), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = "grey30", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.2, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.2, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 0, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0.5, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> list(colour = "grey20", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 2.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list()
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list(fill = NULL, colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> c(5.5, 5.5, 5.5, 5.5)
#> 11
#> NULL
#> NULL
#> NULL
#> 1.2
#> NULL
#> NULL
#> 5.5
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.2
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> right
#> NULL
#> NULL
#> NULL
#> center
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> c(0, 0, 0, 0)
#> list()
#> 11
#> list(fill = "white", colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(fill = NA, colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> 5.5
#> NULL
#> NULL
#> list(colour = "grey92", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> list(colour = NULL, linewidth = 0.5, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> FALSE
#> list(fill = NULL, colour = "white", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = 1, vjust = 1, angle = NULL, lineheight = NULL, margin = c(5.5, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0.5, vjust = 0.5, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> topleft
#> NULL
#> c(5.5, 5.5, 5.5, 5.5)
#> list(fill = "grey85", colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> inherit
#> inside
#> list(family = NULL, face = NULL, colour = "grey10", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(4.4, 4.4, 4.4, 4.4), debug = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = -90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = 90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> 2.75
#> 2.75
#> <environment>
#> <environment>
#> <environment>
#> <environment>
#> week
#> cases

Bar chart of incidence (by the ISO week of infection) covering 2014-W12 to 2015-W18 inclusive. The graph peaks at 2014-W38. The “descent” from the peak tapers off slower than the initial “ascent”. Six labels of the form ‘year-week’ are evenly spread along the x-axis and centred on the corresponding bars.

To assist in formatting plots of grates objects we also provides x-axis scales that can be to extend the output from ggplot2 output. For example, if we prefer non-centralised Date labels we can pass an explicit format argument to the associated scale

week_plot + scale_x_grates_epiweek(format = "%Y-%m-%d")

#> attempt to apply non-function

Period grouping

<grates_period> objects represent groupings of n consecutive days calculated relative to an offset. It is useful for when you wish to group an arbitrary number of dates together (e.g. 10 days).

Internally <grates_period> objects are stored as the integer number, starting at 0, of periods since the Unix Epoch (1970-01-01) and a specified offset. Here periods are taken to mean groupings of n consecutive days. For storage and calculation purposes, offset is scaled relative to n, that is offset <- offset %% n and values of stored relative to this scaled offset.

Like yearweek objects, a period object is easily created with the as_period() coercion function. as_period() takes 3 arguments; x, the vector (normally a Date or POSIXt) you wish to group, n, the integer number of days you wish to group, and offset, the value you wish to start counting groups from relative to the Unix Epoch. For convenience, offset can be given as a date you want periods to be relative to (internally this date is converted to integer).

In the example below we aggregate by 14 day periods offset from the earliest case:

period_dat <- with(daily,
    aggregate(
        list(cases = cases),
        by = list(period = as_period(date, n = 14, offset = min(date))),
        FUN = sum
    )
)

head(period_dat)

#> 1153
#> 1154
#> 1155
#> 1156
#> 1157
#> 1158
#> 1
#> 1
#> 5
#> 22
#> 28
#> 31

ggplot(period_dat, aes(period, cases)) +
    geom_col(width = 1, colour = "white") +
    theme_bw() +
    theme(axis.text.x = element_text(angle = 45, hjust = 1)) +
    xlab("")

#> 1153:1181
#> c(1, 1, 5, 22, 28, 31, 42, 49, 79, 124, 188, 262, 386, 375, 350, 308, 251, 197, 153, 139, 127, 130, 86, 92, 109, 68, 66, 47, 26)
#> <environment>
#> <environment>
#> <environment>
#> ~period
#> ~cases
#> list(colour = "black", linewidth = 0.5, linetype = 1, lineend = "butt", arrow = FALSE, inherit.blank = TRUE)
#> list(fill = "white", colour = "black", linewidth = 0.5, linetype = 1, inherit.blank = TRUE)
#> list(family = "", face = "plain", colour = "black", size = 11, hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 0.9, margin = c(0, 0, 0, 0), debug = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.75, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.75, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = 90, lineheight = NULL, margin = c(0, 2.75, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = -90, lineheight = NULL, margin = c(0, 0, 0, 2.75), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = "grey30", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = 1, angle = 45, lineheight = NULL, margin = c(2.2, 0, 0, 0), debug = NULL, inherit.blank = FALSE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.2, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 0, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0.5, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> list(colour = "grey20", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 2.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list()
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list(fill = NULL, colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> c(5.5, 5.5, 5.5, 5.5)
#> 11
#> NULL
#> NULL
#> NULL
#> 1.2
#> NULL
#> NULL
#> 5.5
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.2
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> right
#> NULL
#> NULL
#> NULL
#> center
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> c(0, 0, 0, 0)
#> list()
#> 11
#> list(fill = "white", colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(fill = NA, colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> 5.5
#> NULL
#> NULL
#> list(colour = "grey92", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> list(colour = NULL, linewidth = 0.5, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> FALSE
#> list(fill = NULL, colour = "white", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = 1, vjust = 1, angle = NULL, lineheight = NULL, margin = c(5.5, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0.5, vjust = 0.5, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> topleft
#> NULL
#> c(5.5, 5.5, 5.5, 5.5)
#> list(fill = "grey85", colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> inherit
#> inside
#> list(family = NULL, face = NULL, colour = "grey10", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(4.4, 4.4, 4.4, 4.4), debug = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = -90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = 90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> 2.75
#> 2.75
#> <environment>
#> <environment>
#> <environment>
#> <environment>
#> 
#> cases

Bar chart of incidence (by period of infection) covering the time from March 2014 to April 2015 inclusive. The graph peaks around September 2014. The “descent” from the peak tapers off slower than the initial “ascent”. Six labels of the form ‘year-month-day’ are evenly spread along the x-axis and aligned at the start of the corresponding bars.

yearmonth, yearquarter and year

Unsurprisingly, <grates_yearmonth>, <grates_yearquarter> and <grates_year> represent Year-month, year-quarter and year groupings. Little more needs to be said so let’s jump straight to some examples.

These objects are stored as the integer number of months/quarters/years (starting at 0) since the Unix Epoch (1970-01-01). To convert efficiently between dates and months relative to the UNIX Epoch we used an algorithm based on the approach of Davis Vaughan in the unreleased datea package.

(month_dat <- with(daily,
    aggregate(
        list(cases = cases),
        by = list(month = as_yearmonth(date)),
        FUN = sum
    )
))

#> 530
#> 531
#> 532
#> 533
#> 534
#> 535
#> 536
#> 537
#> 538
#> 539
#> 540
#> 541
#> 542
#> 543
#> 1
#> 6
#> 57
#> 80
#> 183
#> 453
#> 813
#> 719
#> 448
#> 307
#> 251
#> 199
#> 152
#> 73

(month_plot <-
    ggplot(month_dat, aes(month, cases)) +
    geom_col(width = 1, colour = "white") +
    theme_bw() +
    theme(axis.text.x = element_text(angle = 45, hjust = 1)) +
    xlab(""))

#> 530:543
#> c(1, 6, 57, 80, 183, 453, 813, 719, 448, 307, 251, 199, 152, 73)
#> <environment>
#> <environment>
#> <environment>
#> ~month
#> ~cases
#> list(colour = "black", linewidth = 0.5, linetype = 1, lineend = "butt", arrow = FALSE, inherit.blank = TRUE)
#> list(fill = "white", colour = "black", linewidth = 0.5, linetype = 1, inherit.blank = TRUE)
#> list(family = "", face = "plain", colour = "black", size = 11, hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 0.9, margin = c(0, 0, 0, 0), debug = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.75, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.75, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = 90, lineheight = NULL, margin = c(0, 2.75, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = -90, lineheight = NULL, margin = c(0, 0, 0, 2.75), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = "grey30", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = 1, angle = 45, lineheight = NULL, margin = c(2.2, 0, 0, 0), debug = NULL, inherit.blank = FALSE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.2, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 0, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0.5, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> list(colour = "grey20", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 2.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list()
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list(fill = NULL, colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> c(5.5, 5.5, 5.5, 5.5)
#> 11
#> NULL
#> NULL
#> NULL
#> 1.2
#> NULL
#> NULL
#> 5.5
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.2
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> right
#> NULL
#> NULL
#> NULL
#> center
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> c(0, 0, 0, 0)
#> list()
#> 11
#> list(fill = "white", colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(fill = NA, colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> 5.5
#> NULL
#> NULL
#> list(colour = "grey92", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> list(colour = NULL, linewidth = 0.5, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> FALSE
#> list(fill = NULL, colour = "white", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = 1, vjust = 1, angle = NULL, lineheight = NULL, margin = c(5.5, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0.5, vjust = 0.5, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> topleft
#> NULL
#> c(5.5, 5.5, 5.5, 5.5)
#> list(fill = "grey85", colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> inherit
#> inside
#> list(family = NULL, face = NULL, colour = "grey10", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(4.4, 4.4, 4.4, 4.4), debug = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = -90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = 90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> 2.75
#> 2.75
#> <environment>
#> <environment>
#> <environment>
#> <environment>
#> 
#> cases

Bar chart of monthly incidence (by date of infection) covering the time from March 2014 to April 2015 inclusive. The graph peaks around September 2014. The “descent” from the peak tapers off slower than the initial “ascent”. Labels of the form ‘year-month’ are evenly spread along the x-axis and aligned at the centred of the corresponding bars.

Again we can have non-centred date labels by applying the associated scale with the desired format.

month_plot + scale_x_grates_yearmonth(format = "%Y-%m-%d")

#> attempt to apply non-function

yearquarter works similarly

(quarter_dat <- with(daily,
    aggregate(
        list(cases = cases),
        by = list(quarter = as_yearquarter(date)),
        FUN = sum
    )
))

#> 176
#> 177
#> 178
#> 179
#> 180
#> 181
#> 1
#> 143
#> 1449
#> 1474
#> 602
#> 73

ggplot(quarter_dat, aes(quarter, cases)) +
    geom_col(width = 1, colour = "white") +
    theme_bw() +
    theme(axis.text.x = element_text(angle = 45, hjust = 1)) +
    xlab("")

#> 176:181
#> c(1, 143, 1449, 1474, 602, 73)
#> <environment>
#> <environment>
#> <environment>
#> ~quarter
#> ~cases
#> list(colour = "black", linewidth = 0.5, linetype = 1, lineend = "butt", arrow = FALSE, inherit.blank = TRUE)
#> list(fill = "white", colour = "black", linewidth = 0.5, linetype = 1, inherit.blank = TRUE)
#> list(family = "", face = "plain", colour = "black", size = 11, hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 0.9, margin = c(0, 0, 0, 0), debug = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.75, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.75, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = 90, lineheight = NULL, margin = c(0, 2.75, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = -90, lineheight = NULL, margin = c(0, 0, 0, 2.75), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = "grey30", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = 1, angle = 45, lineheight = NULL, margin = c(2.2, 0, 0, 0), debug = NULL, inherit.blank = FALSE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.2, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 0, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0.5, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> list(colour = "grey20", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 2.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list()
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list(fill = NULL, colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> c(5.5, 5.5, 5.5, 5.5)
#> 11
#> NULL
#> NULL
#> NULL
#> 1.2
#> NULL
#> NULL
#> 5.5
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.2
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> right
#> NULL
#> NULL
#> NULL
#> center
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> c(0, 0, 0, 0)
#> list()
#> 11
#> list(fill = "white", colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(fill = NA, colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> 5.5
#> NULL
#> NULL
#> list(colour = "grey92", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> list(colour = NULL, linewidth = 0.5, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> FALSE
#> list(fill = NULL, colour = "white", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = 1, vjust = 1, angle = NULL, lineheight = NULL, margin = c(5.5, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0.5, vjust = 0.5, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> topleft
#> NULL
#> c(5.5, 5.5, 5.5, 5.5)
#> list(fill = "grey85", colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> inherit
#> inside
#> list(family = NULL, face = NULL, colour = "grey10", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(4.4, 4.4, 4.4, 4.4), debug = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = -90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = 90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> 2.75
#> 2.75
#> <environment>
#> <environment>
#> <environment>
#> <environment>
#> 
#> cases

Bar chart of quarterly incidence (by date of infection) covering the time from 2014-Q1 to 2015-Q2 inclusive. The graph peaks over quarters 3 and 4 in 2014. Labels on the x-axis and of the form ‘year-quarter’ are centred on the corresponding bars.

As does year

(year_dat <- with(daily,
    aggregate(
        list(cases = cases),
        by = list(year = as_year(date)),
        FUN = sum
    )
))

#> 2014
#> 2015
#> 3067
#> 675

ggplot(year_dat, aes(year, cases)) +
    geom_col(width = 1, colour = "white") +
    theme_bw() +
    theme(axis.text.x = element_text(angle = 45, hjust = 1)) +
    xlab("")

#> 2014:2015
#> c(3067, 675)
#> <environment>
#> <environment>
#> <environment>
#> ~year
#> ~cases
#> list(colour = "black", linewidth = 0.5, linetype = 1, lineend = "butt", arrow = FALSE, inherit.blank = TRUE)
#> list(fill = "white", colour = "black", linewidth = 0.5, linetype = 1, inherit.blank = TRUE)
#> list(family = "", face = "plain", colour = "black", size = 11, hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 0.9, margin = c(0, 0, 0, 0), debug = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.75, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.75, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = 90, lineheight = NULL, margin = c(0, 2.75, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = -90, lineheight = NULL, margin = c(0, 0, 0, 2.75), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = "grey30", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = 1, angle = 45, lineheight = NULL, margin = c(2.2, 0, 0, 0), debug = NULL, inherit.blank = FALSE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.2, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 0, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0.5, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> list(colour = "grey20", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 2.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list()
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list(fill = NULL, colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> c(5.5, 5.5, 5.5, 5.5)
#> 11
#> NULL
#> NULL
#> NULL
#> 1.2
#> NULL
#> NULL
#> 5.5
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.2
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> right
#> NULL
#> NULL
#> NULL
#> center
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> c(0, 0, 0, 0)
#> list()
#> 11
#> list(fill = "white", colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(fill = NA, colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> 5.5
#> NULL
#> NULL
#> list(colour = "grey92", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> list(colour = NULL, linewidth = 0.5, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> FALSE
#> list(fill = NULL, colour = "white", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = 1, vjust = 1, angle = NULL, lineheight = NULL, margin = c(5.5, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0.5, vjust = 0.5, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> topleft
#> NULL
#> c(5.5, 5.5, 5.5, 5.5)
#> list(fill = "grey85", colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> inherit
#> inside
#> list(family = NULL, face = NULL, colour = "grey10", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(4.4, 4.4, 4.4, 4.4), debug = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = -90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = 90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> 2.75
#> 2.75
#> <environment>
#> <environment>
#> <environment>
#> <environment>
#> 
#> cases

Bar chart of yearly incidence (by date of infection) for 2014 and 2015. There were lots more cases in 2014 compared to 2015 (Roughly speaking 3000 v 700).

month

Month objects are groupings of ‘n consecutive months’ stored relative to the Unix Epoch. More precisely, grates_month objects are stored as the integer number (starting at 0), of n-month groups since the Unix Epoch (1970-01-01). This fixed anchoring does make them a little unwieldy but I find they can be useful for bimonthly data.

# calculate the bimonthly number of cases
(bimonth_dat <- with(daily,
    aggregate(
        list(cases = cases),
        by = list(group = as_month(date, n = 2)),
        FUN = sum
    )
))

#> 265
#> 266
#> 267
#> 268
#> 269
#> 270
#> 271
#> 7
#> 137
#> 636
#> 1532
#> 755
#> 450
#> 225

# by default lower date bounds are used for the x axis
(bimonth_plot <-
    ggplot(bimonth_dat, aes(group, cases)) +
    geom_col(width = 1, colour = "white") +
    theme_bw() +
    theme(axis.text.x = element_text(angle = 45, hjust = 1)) +
    xlab(""))

#> 265:271
#> c(7, 137, 636, 1532, 755, 450, 225)
#> <environment>
#> <environment>
#> <environment>
#> ~group
#> ~cases
#> list(colour = "black", linewidth = 0.5, linetype = 1, lineend = "butt", arrow = FALSE, inherit.blank = TRUE)
#> list(fill = "white", colour = "black", linewidth = 0.5, linetype = 1, inherit.blank = TRUE)
#> list(family = "", face = "plain", colour = "black", size = 11, hjust = 0.5, vjust = 0.5, angle = 0, lineheight = 0.9, margin = c(0, 0, 0, 0), debug = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = NULL, lineheight = NULL, margin = c(2.75, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.75, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = 90, lineheight = NULL, margin = c(0, 2.75, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 1, angle = -90, lineheight = NULL, margin = c(0, 0, 0, 2.75), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = "grey30", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = 1, angle = 45, lineheight = NULL, margin = c(2.2, 0, 0, 0), debug = NULL, inherit.blank = FALSE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = 0, angle = NULL, lineheight = NULL, margin = c(0, 0, 2.2, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 1, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 0), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 0, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0.5, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(0, 2.2, 0, 2.2), debug = NULL, inherit.blank = TRUE)
#> list(colour = "grey20", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 2.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.75
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list()
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> list(fill = NULL, colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> c(5.5, 5.5, 5.5, 5.5)
#> 11
#> NULL
#> NULL
#> NULL
#> 1.2
#> NULL
#> NULL
#> 5.5
#> NULL
#> NULL
#> NULL
#> NULL
#> 0.2
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = NULL, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> right
#> NULL
#> NULL
#> NULL
#> center
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> NULL
#> c(0, 0, 0, 0)
#> list()
#> 11
#> list(fill = "white", colour = NA, linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(fill = NA, colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> 5.5
#> NULL
#> NULL
#> list(colour = "grey92", linewidth = NULL, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> list(colour = NULL, linewidth = 0.5, linetype = NULL, lineend = NULL, arrow = FALSE, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> NULL
#> FALSE
#> list(fill = NULL, colour = "white", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = 0, vjust = 1, angle = NULL, lineheight = NULL, margin = c(0, 0, 5.5, 0), debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = 0.8, hjust = 1, vjust = 1, angle = NULL, lineheight = NULL, margin = c(5.5, 0, 0, 0), debug = NULL, inherit.blank = TRUE)
#> panel
#> list(family = NULL, face = NULL, colour = NULL, size = 1.2, hjust = 0.5, vjust = 0.5, angle = NULL, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> topleft
#> NULL
#> c(5.5, 5.5, 5.5, 5.5)
#> list(fill = "grey85", colour = "grey20", linewidth = NULL, linetype = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> inherit
#> inside
#> list(family = NULL, face = NULL, colour = "grey10", size = 0.8, hjust = NULL, vjust = NULL, angle = NULL, lineheight = NULL, margin = c(4.4, 4.4, 4.4, 4.4), debug = NULL, inherit.blank = TRUE)
#> NULL
#> NULL
#> NULL
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = -90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> list(family = NULL, face = NULL, colour = NULL, size = NULL, hjust = NULL, vjust = NULL, angle = 90, lineheight = NULL, margin = NULL, debug = NULL, inherit.blank = TRUE)
#> NULL
#> 2.75
#> 2.75
#> <environment>
#> <environment>
#> <environment>
#> <environment>
#> 
#> cases

Bar chart of bimonthly incidence (by date of infection) covering the time from March 2014 to April 2015 inclusive. The graph peaks around September/October 2014. Labels of the form ‘year-month-day’ are evenly spread along the x-axis aligned to the start of the corresponding bars.

Note that the default plotting behaviour of non-centred date labels is different to that of the yearweek, yearmonth, yearquarter and year scales where labels are centred by default. To obtain centred labels you must explicitly set the format to NULL in the scale:

bimonth_plot + scale_x_grates_month(format = NULL, n = 2L)

#> attempt to apply non-function

Methods and other functionality

For all grates objects we have added many methods and operations to ensure logical and consistent behaviour.

# Choose some dates spread across a few weeks
first <- as.Date("2024-12-18")
dates <- seq.Date(from = first, by = "5 days", length.out = 7)

# add the corresponding ISO week (see later)
dat <- data.frame(date = dates, isoweek = as_isoweek(dates))

Some times it is useful to access both the starting dates covered by grates objects as well as the end dates. To this end we provide functions date_start() and date_end():

with(dat, {
    weeks <- unique(isoweek)
    data.frame(
        isoweek = weeks,
        start = date_start(weeks),
        end = date_end(weeks)
    )
})

#> 2868
#> 2869
#> 2870
#> 2871
#> 2872
#> 20073
#> 20080
#> 20087
#> 20094
#> 20101
#> 20079
#> 20086
#> 20093
#> 20100
#> 20107

Note that the conversion of grate objects back to dates is analogous to date_start().

with(dat, identical(as.Date(isoweek), date_start(isoweek)))

#> TRUE

To find out whether a grate object spans a particular date we provide a %during% function:

with(dat, {
    data.frame(
        original_date = date,
        isoweek,
        contains.2025.01.10 = as.Date("2025-01-10") %during% isoweek
    )
})

#> 20075
#> 20080
#> 20085
#> 20090
#> 20095
#> 20100
#> 20105
#> 2868
#> 2869
#> 2869
#> 2870
#> 2871
#> 2871
#> 2872
#> 0
#> 0
#> 0
#> 0
#> 1
#> 1
#> 0

min(), max(), range() and seq() all work as you would expect

weeks <- dat$isoweek

(minw <- min(weeks))

#> 2868

(maxw <- max(weeks))

#> 2872

(rangew <- range(weeks))

#> 2868
#> 2872

# seq method works if both `from` and `to` are epiweeks
seq(from = minw, to = maxw, by = 6L)

#> 2868

# but will error informatively if `to` is a different class
seq(from = minw, to = 999, by = 6L)

#> `to` must be a <grates_isoweek> object of length 1.

Addition (subtraction) of whole numbers will add (subtract) the corresponding number of weeks to (from) the object

(dat <- transform(dat, plus4 = isoweek + 4L, minus4 = isoweek - 4L))

#> 20075
#> 20080
#> 20085
#> 20090
#> 20095
#> 20100
#> 20105
#> 2868
#> 2869
#> 2869
#> 2870
#> 2871
#> 2871
#> 2872
#> 2872
#> 2873
#> 2873
#> 2874
#> 2875
#> 2875
#> 2876
#> 2864
#> 2865
#> 2865
#> 2866
#> 2867
#> 2867
#> 2868

Addition of two yearweek objects will error as the intention is unclear.

transform(dat, willerror = isoweek + isoweek)

#> Cannot add <grates_isoweek> objects to each other.

Subtraction of two yearweek objects gives the difference in weeks between them

transform(dat, difference = plus4 - minus4)

#> 20075
#> 20080
#> 20085
#> 20090
#> 20095
#> 20100
#> 20105
#> 2868
#> 2869
#> 2869
#> 2870
#> 2871
#> 2871
#> 2872
#> 2872
#> 2873
#> 2873
#> 2874
#> 2875
#> 2875
#> 2876
#> 2864
#> 2865
#> 2865
#> 2866
#> 2867
#> 2867
#> 2868
#> 8
#> 8
#> 8
#> 8
#> 8
#> 8
#> 8

epiweek objects can be combined with themselves but not other classes (assuming an epiweek object is the first entry).

c(minw, maxw)

#> 2868
#> 2872

identical(c(minw, maxw), rangew)

#> TRUE

c(minw, 1L)

#> Unable to combine <grates_isoweek> objects with other classes.

Acknowledgements

The underlying implementation for these objects build upon ideas of Davis Vaughan and the unreleased datea package as well as those of Zhian Kamvar and the aweek package.

Wikipedia contributors. (2025, January 15). ISO week date. In Wikipedia, The Free Encyclopedia. Retrieved 12:47, March 6, 2025, from https://en.wikipedia.org/w/index.php?title=ISO_week_date&oldid=1269568343: ↩