Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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:

Awesome Lists containing this project

README 

        
---

output: github_document

---



[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-ago/aweek)](https://cran.r-project.org/package=aweek) 

[![Codecov test coverage](https://codecov.io/gh/reconhub/aweek/branch/master/graph/badge.svg)](https://codecov.io/gh/reconhub/aweek?branch=master) 

[![Downloads](https://cranlogs.r-pkg.org/badges/grand-total/aweek?color=ff69b4)](https://cran.r-project.org/package=aweek)

[![DOI](https://zenodo.org/badge/172648833.svg)](https://zenodo.org/badge/latestdoi/172648833)

[![R-CMD-check](https://github.com/zkamvar/aweek/workflows/R-CMD-check/badge.svg)](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.