This package will convert dates to US CDC epiweeks, isoweeks, and all others in between with minimal overhead.
To install the stable package version from CRAN, you can use
install.packages("aweek")To benefit from the latest features and bug fixes, install the development, github version of the package using:
# install.packages("remotes")
remotes::install_github("reconhub/aweek")date2week()converts dates to a week format (YYYY-Www-d) that can start on any day.week2date()/as.Date()does the backwards conversion from (YYYY-Www(-d)) to a numeric date.get_aweek()generates an aweek object from a week numberget_date()converts a week number to a dateas.aweek()converts dates, characters, and factors to aweek objects.factor_aweek()creates an aggregated factor of weeks where the levels contain all weeks within range.- Dependencies only on R itself.
With the aweek package, converting dates to weeks is simple. All you need to know is what weekday represents the beginning of your week and a vector of dates.
# generate dates
set.seed(2019-02-26)
onset <- as.Date("2019-02-26") + sort(sample(-6:7, 20, replace = TRUE))
# load aweek
library("aweek")
set_week_start("Monday") # set the default start of the week
print(onset)## [1] "2019-02-21" "2019-02-21" "2019-02-22" "2019-02-22" "2019-02-22" "2019-02-23" "2019-02-23" "2019-02-23" "2019-02-25" "2019-02-26" "2019-02-26" "2019-02-27" "2019-02-28" "2019-02-28" "2019-03-02" "2019-03-03"
## [17] "2019-03-04" "2019-03-05" "2019-03-05" "2019-03-05"
date2week(onset) # convert dates to weeks## <aweek start: Monday>
## [1] "2019-W08-4" "2019-W08-4" "2019-W08-5" "2019-W08-5" "2019-W08-5" "2019-W08-6" "2019-W08-6" "2019-W08-6" "2019-W09-1" "2019-W09-2" "2019-W09-2" "2019-W09-3" "2019-W09-4" "2019-W09-4" "2019-W09-6" "2019-W09-7"
## [17] "2019-W10-1" "2019-W10-2" "2019-W10-2" "2019-W10-2"
If you want to override the default, you can use the week_start
attribute of date2week():
date2week(onset, week_start = 1) # ISO weeks starting on Monday (default)## <aweek start: Monday>
## [1] "2019-W08-4" "2019-W08-4" "2019-W08-5" "2019-W08-5" "2019-W08-5" "2019-W08-6" "2019-W08-6" "2019-W08-6" "2019-W09-1" "2019-W09-2" "2019-W09-2" "2019-W09-3" "2019-W09-4" "2019-W09-4" "2019-W09-6" "2019-W09-7"
## [17] "2019-W10-1" "2019-W10-2" "2019-W10-2" "2019-W10-2"
date2week(onset, week_start = 7) # EPI week starting on Sunday## <aweek start: Sunday>
## [1] "2019-W08-5" "2019-W08-5" "2019-W08-6" "2019-W08-6" "2019-W08-6" "2019-W08-7" "2019-W08-7" "2019-W08-7" "2019-W09-2" "2019-W09-3" "2019-W09-3" "2019-W09-4" "2019-W09-5" "2019-W09-5" "2019-W09-7" "2019-W10-1"
## [17] "2019-W10-2" "2019-W10-3" "2019-W10-3" "2019-W10-3"
date2week(onset, week_start = 6) # EPI week starting on Saturday## <aweek start: Saturday>
## [1] "2019-W08-6" "2019-W08-6" "2019-W08-7" "2019-W08-7" "2019-W08-7" "2019-W09-1" "2019-W09-1" "2019-W09-1" "2019-W09-3" "2019-W09-4" "2019-W09-4" "2019-W09-5" "2019-W09-6" "2019-W09-6" "2019-W10-1" "2019-W10-2"
## [17] "2019-W10-3" "2019-W10-4" "2019-W10-4" "2019-W10-4"
x <- date2week(onset, week_start = "sat", floor_day = TRUE) # truncate to just the weeks
table(x)## x
## 2019-W08 2019-W09 2019-W10
## 5 9 6
table(week2date(x))##
## 2019-02-16 2019-02-23 2019-03-02
## 5 9 6
If you have numeric weeks, you can rapidly convert to dates with
get_date(). Here are all the dates for the first day of last 10 ISO
weeks of 2015:
get_date(week = 44:53, year = 2015)## [1] "2015-10-26" "2015-11-02" "2015-11-09" "2015-11-16" "2015-11-23" "2015-11-30" "2015-12-07" "2015-12-14" "2015-12-21" "2015-12-28"
# you can also use this to generate aweek objects
get_aweek(week = 44:53, year = 2015)## <aweek start: Monday>
## [1] "2015-W44-1" "2015-W45-1" "2015-W46-1" "2015-W47-1" "2015-W48-1" "2015-W49-1" "2015-W50-1" "2015-W51-1" "2015-W52-1" "2015-W53-1"
If you have weeks recorded from different data sets that start on
different days, you can account for that by using the start option.
For example, 2018-01-01 is a Monday, but 2018-W01-1 starting on a Sunday
is 2017-12-31
get_date(week = 1, year = 2018, day = 1, start = c("Sunday", "Monday"))## [1] "2017-12-31" "2018-01-01"
# get_aweek will align them to the default week_start
get_aweek(week = 1, year = 2018, day = 1, start = c("Sunday", "Monday"))## <aweek start: Monday>
## [1] "2017-W52-7" "2018-W01-1"
You can also automatically calculate factor levels, which is useful in tabulating across weeks and including missing values.
set.seed(2019-02-26)
onset <- as.Date("2019-02-26") + sort(sample(-48:49, 20, replace = TRUE))
x <- date2week(onset, week_start = "sat", factor = TRUE)
x## <aweek start: Saturday>
## [1] 2019-W03 2019-W03 2019-W04 2019-W04 2019-W04 2019-W05 2019-W05 2019-W05 2019-W06 2019-W06 2019-W06 2019-W09 2019-W09 2019-W10 2019-W11 2019-W12 2019-W12 2019-W14 2019-W15 2019-W15
## Levels: 2019-W03 2019-W04 2019-W05 2019-W06 2019-W07 2019-W08 2019-W09 2019-W10 2019-W11 2019-W12 2019-W13 2019-W14 2019-W15
table(x)## x
## 2019-W03 2019-W04 2019-W05 2019-W06 2019-W07 2019-W08 2019-W09 2019-W10 2019-W11 2019-W12 2019-W13 2019-W14 2019-W15
## 2 3 3 3 0 0 2 1 1 2 0 1 2
It’s also possible to specify the week_start in terms of the current locale, however it is important to be aware that code like this may not be portable.
# workaround because of differing locale specifications
german <- if (grepl("darwin", R.version$os)) "de_DE.UTF-8" else "de_DE.utf8"
lct <- Sys.getlocale("LC_TIME")
res <- Sys.setlocale("LC_TIME", german)
date2week(as.Date("2019-02-26"), week_start = "Sonntag")## <aweek start: Sonntag>
## [1] "2019-W09-3"
date2week(as.Date("2019-02-26"), week_start = "Sunday")## <aweek start: Sonntag>
## [1] "2019-W09-3"
Sys.setlocale("LC_TIME", lct)## [1] "en_US.UTF-8"
Bug reports and feature requests should be posted on github using the
issue system. All other
questions should be posted on the RECON forum:
https://www.repidemicsconsortium.org/forum/
Contributions are welcome via pull requests.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
There are other packages that can define ISOweeks and/or epiweeks. However, the ability to easily switch between day and week intervals is only available for the ISOweek package and all of the packages above have dependencies that require compiled code.
- ISOweek converts dates to ISO weeks as the “%W” and “%u” formats don’t exist in windows
- lubridate performs general datetime handling with some auxiliary functions that return the week or day of the week.
- surveillance implements ISOWeekYear.