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: 9 days 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.