-
Notifications
You must be signed in to change notification settings - Fork 4
/
README.Rmd
167 lines (120 loc) · 5.49 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
---
output: github_document
---
<!-- badges: start -->
[](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)
<!-- badges: end -->
# 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**: <br>
[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.