aweek-class: The aweek class

In aweek: Convert Dates to Arbitrary Week Definitions

The aweek class

Description

The aweek class is a character or factor in the format YYYY-Www(-d) with a "week_start" attribute containing an integer specifying which day of the ISO 8601 week each week should begin.

Usage

## S3 method for class 'aweek'
print(x, ...)

## S3 method for class 'aweek'
x[i]

## S3 method for class 'aweek'
x[[i]]

## S3 replacement method for class 'aweek'
x[i] <- value

## S3 method for class 'aweek'
as.list(x, ...)

## S3 method for class 'aweek'
trunc(x, ...)

## S3 method for class 'aweek'
rep(x, ...)

## S3 method for class 'aweek'
c(..., recursive = FALSE, use.names = TRUE)

Arguments

x	an object of class aweek
...	a series of aweek objects, characters, or Dates, (unused in print.aweek())
i	index for subsetting an aweek object.
value	a value to add or replace in an aweek object
recursive, use.names	parameters passed on to unlist()

Details

Weeks differ in their start dates depending on context. The ISO 8601 standard specifies that Monday starts the week (https://en.wikipedia.org/wiki/ISO_week_date) while the US CDC uses Sunday as the start of the week (https://stacks.cdc.gov/view/cdc/22305). For example, MSF has varying start dates depending on country in order to better coordinate response.

While there are packages that provide conversion for ISOweeks and epiweeks, these do not provide seamless conversion from dates to epiweeks with non-standard start dates. This package provides a lightweight utility to be able to convert each day.

Calculation of week numbers

Week numbers are calculated in three steps:

1. Find the day of the week, relative to the week_start (d). The day of the week (d) relative to the week start (s) is calculated using the ISO week day (i) via d = 1L + ((i + (7L - s)) %% 7L).

2. Find the date that represents midweek (m). The date that represents midweek is found by subtracting the day of the week (d) from 4 and adding that number of days to the current date: m = date + (4 - d).

3. Find the week number (w) by counting the number of days since 1 January to (m), and use integer division by 7: w = 1L + ((m - yyyy-01-01) %/% 7)

For the weeks around 1 January, the year is determined by the week number. If the month is January, but the week number is 52 or 53, then the year for the week (YYYY) is the calendar year (yyyy) minus 1. However, if the month is December, but the week number is 1, then the year for the week (YYYY) is the calendar year (yyyy) plus 1.

Structure of the aweek object

The aweek object is a character vector in either the precise ISO week format (YYYY-Www-d) or imprecise ISO week format (YYYY-Www) with a week_start attribute indicating which ISO week day the week begins. The precise ISO week format can be broken down like this:

• YYYY is an ISO week-numbering year, which is the year relative to the week, not the day. For example, the date 2016-01-01 would be represented as 2015-W53-5 (ISO week), because while the date is in the year 2016, the week is still part of the final week of 2015.

• Www is the week number, prefixed by the character "W". This ranges from 01 to 52 or 53, depending on whether or not the year has 52 or 53 weeks.

• d is a digit representing the weekday where 1 represents the first day of the week and 7 represents the last day of the week. #' The attribute week_start represents the first day of the week as an ISO week day. This defaults to 1, which is Monday. If, for example, an aweek object represented weeks starting on Friday, then the week_start attribute would be 5, which is Friday of the ISO week.

Imprecise formats (YYYY-Www) are equivalent to the first day of the week. For example, 2015-W53 and 2015-W53-1 will be identical when converted to date.

Value

an object of class aweek

Note

when combining aweek objects together, you must ensure that they have the same week_start attribute. You can use change_week_start() to adjust it.

See Also

date2week(), get_aweek(), as.Date.aweek(), change_week_start()

Examples

d <- as.Date("2018-12-20") + 1:40
w <- date2week(d, week_start = "Sunday")
print(w)

# subsetting acts as normal
w[1:10]

# Combining multiple aweek objects will only work if they have the same
# week_start day
c(w[1], w[3], w[5], as.aweek(as.Date("2018-12-01"), week_start = "Sunday"))

# differing week_start days will throw an error
mon <- date2week(as.Date("2018-12-01"), week_start = "Monday")
mon
try(c(w, mon))

# combining Dates will be coerced to aweek objects under the same rules
c(w, Sys.Date())

# truncated aweek objects will be un-truncated
w2 <- date2week(d[1:5], week_start = "Sunday", floor_day = TRUE)
w2
c(w[1:5], w2)

aweek documentation built on Oct. 6, 2022, 9:07 a.m.