https://github.com/reconhub/aweek
Convert dates to arbitrary week definitions :calendar:
https://github.com/reconhub/aweek
date-formatting dates epidemiology r r-package timeseries week
Last synced: 3 months ago
JSON representation
Convert dates to arbitrary week definitions :calendar:
- Host: GitHub
- URL: https://github.com/reconhub/aweek
- Owner: reconhub
- License: other
- Created: 2019-02-26T06:07:45.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-10-06T02:40:38.000Z (about 3 years ago)
- Last Synced: 2025-07-25T13:55:55.605Z (3 months ago)
- Topics: date-formatting, dates, epidemiology, r, r-package, timeseries, week
- Language: R
- Homepage: https://www.repidemicsconsortium.org/aweek
- Size: 367 KB
- Stars: 18
- Watchers: 1
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- jimsghstars - reconhub/aweek - Convert dates to arbitrary week definitions :calendar: (R)
README
---
output: github_document
---
[](https://cran.r-project.org/package=aweek)
[](https://codecov.io/gh/reconhub/aweek?branch=master)
[](https://cran.r-project.org/package=aweek)
[](https://zenodo.org/badge/latestdoi/172648833)
[](https://github.com/zkamvar/aweek/actions)
# Welcome to the *aweek* package!
This package will convert dates to [US CDC
epiweeks](https://wwwn.cdc.gov/nndss/document/MMWR_Week_overview.pdf),
[isoweeks](https://en.wikipedia.org/wiki/ISO_week_date), and all others in
between with minimal overhead.
## Installing the package
To install the stable package version from CRAN, you can use
```{r install, eval = FALSE}
install.packages("aweek")
```
To benefit from the latest features and bug fixes, install the development,
*github* version of the package using:
```{r install2, eval = FALSE}
# install.packages("remotes")
remotes::install_github("reconhub/aweek")
```
# Main Features
- `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 number
- `get_date()` converts a week number to a date
- `as.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.
## Dates to weeks
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.
```{r epiweek}
# 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)
date2week(onset) # convert dates to weeks
```
If you want to override the default, you can use the `week_start` attribute of
`date2week()`:
```{r epiweek_options}
date2week(onset, week_start = 1) # ISO weeks starting on Monday (default)
date2week(onset, week_start = 7) # EPI week starting on Sunday
date2week(onset, week_start = 6) # EPI week starting on Saturday
x <- date2week(onset, week_start = "sat", floor_day = TRUE) # truncate to just the weeks
table(x)
table(week2date(x))
```
## Weeks to dates
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:
```{r get_date}
get_date(week = 44:53, year = 2015)
# you can also use this to generate aweek objects
get_aweek(week = 44:53, year = 2015)
```
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
```{r different_starts}
get_date(week = 1, year = 2018, day = 1, start = c("Sunday", "Monday"))
# get_aweek will align them to the default week_start
get_aweek(week = 1, year = 2018, day = 1, start = c("Sunday", "Monday"))
```
## Factors
You can also automatically calculate factor levels, which is useful in
tabulating across weeks and including missing values.
```{r show_factors}
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
table(x)
```
## Locales
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.
```{r locale_dates, error = TRUE}
# 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")
date2week(as.Date("2019-02-26"), week_start = "Sunday")
Sys.setlocale("LC_TIME", lct)
```
## Getting help online
Bug reports and feature requests should be posted on *github* using the
[*issue*](https://github.com/reconhub/aweek/issues) system. All other questions
should be posted on the **RECON forum**:
[https://www.repidemicsconsortium.org/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](CONDUCT.md). By participating in this project you agree to abide by
its terms.
## Similar Work
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](https://cran.r-project.org/package=ISOweek) converts dates to ISO
weeks as the "%W" and "%u" formats don't exist in windows
- [lubridate](https://github.com/tidyverse/lubridate) performs general
datetime handling with some auxiliary functions that return the week or day
of the week.
- [surveillance](https://surveillance.r-forge.r-project.org/) implements ISOWeekYear.