forked from tidyverts/tsibble
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
126 lines (92 loc) · 5.74 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
---
output:
github_document:
html_preview: false
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
# tsibble
*/ˈt͡sɪbəl/*
[](https://travis-ci.org/tidyverts/tsibble)
[](https://ci.appveyor.com/project/tidyverts/tsibble)
[](https://codecov.io/github/tidyverts/tsibble?branch=master)
[](https://cran.r-project.org/package=tsibble)
[](https://cran.r-project.org/package=tsibble)
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE, comment = "#>", fig.path = "man/figure/"
)
options(tibble.print_min = 5)
Sys.setenv(TZ = "")
```
The **tsibble** package provides a data class of `tbl_ts` to store and manage temporal-context data frames in a tidy manner. A *tsibble* consists of a time index, keys and other measured variables in a data-centric format, which is built on top of the *tibble*.
## Installation
You could install the stable version on CRAN:
```{r, eval = FALSE}
install.packages("tsibble")
```
You could install the development version from Github using
```{r, eval = FALSE}
# install.packages("devtools")
devtools::install_github("tidyverts/tsibble", build_vignettes = TRUE)
```
## Get started
### Coerce to a tsibble with `as_tsibble()`
The `weather` data included in the package `nycflights13` is used as an example to illustrate. The "index" variable is the `time_hour` containing the date-times, and the "key" is the `origin` as weather stations created via `id()`. **The key(s) together with the index uniquely identifies each observation**, which gives a valid *tsibble*. Other columns can be considered as measured variables.
```{r nycflights13, message = FALSE}
library(tsibble)
weather <- nycflights13::weather %>%
select(origin, time_hour, temp, humid, precip)
weather_tsbl <- as_tsibble(weather, key = id(origin), index = time_hour)
weather_tsbl
```
The **key** is not constrained to a single variable, but expressive of nested and crossed data structures. This incorporates univariate, multivariate, hierarchical and grouped time series into the tsibble framework. See `?tsibble` and [`vignette("intro-tsibble")`](http://pkg.earo.me/tsibble/articles/intro-tsibble.html) for details.
### `fill_na()` to turn implicit missing values into explicit missing values
Often there are implicit missing cases in temporal data. If the observations are made at regular time interval, we could turn these implicit missings to be explicit simply using `fill_na()`. Meanwhile, fill `NA`s in by 0 for precipitation (`precip`). It is quite common to replaces `NA`s with its previous observation for each origin in time series analysis, which is easily done using `fill()` from *tidyr*.
```{r fill-na}
full_weather <- weather_tsbl %>%
fill_na(precip = 0) %>%
group_by(origin) %>%
fill(temp, humid, .direction = "down")
full_weather
```
`fill_na()` also handles filling `NA` by values or functions, and preserves time zones for date-times.
### `tsummarise()` to summarise over calendar periods
`tsummarise()` and its scoped variants (including `_all()`, `_at()`, `_if()`) are introduced to aggregate interested variables over calendar periods. `tsummarise()` goes hand in hand with the index functions including `as.Date()`, `yearmonth()`, and `yearquarter()`, as well as other friends from *lubridate*, such as `year()`, `ceiling_date()`, `floor_date()` and `round_date()`. For example, it would be of interest in computing average temperature and total precipitation per month, by applying `yearmonth()` to the hourly time index.
```{r tsummarise}
full_weather %>%
group_by(origin) %>%
tsummarise(
year_month = yearmonth(time_hour), # monthly aggregates
avg_temp = mean(temp, na.rm = TRUE),
ttl_precip = sum(precip, na.rm = TRUE)
)
```
`tsummarise()` can also help with regularising a tsibble of irregular time space.
### A family of window functions: `slide()`, `tile()`, `stretch()`
Temporal data often involves moving window calculations. Several functions in the *tsibble* allow for different variations of moving windows using purrr-like syntax:
* `slide()`: sliding window with overlapping observations.
* `tile()`: tiling window without overlapping observations.
* `stretch()`: fixing an initial window and expanding to include more observations.
For example, a moving average of window size 3 is carried out on hourly temperatures for each group (*origin*).
```{r slide}
full_weather %>%
group_by(origin) %>%
mutate(temp_ma = slide(temp, ~ mean(., na.rm = TRUE), size = 3))
```
## Reexported functions from the tidyverse
It can be noticed that the tsibble seamlessly works with *dplyr* verbs. Use `?tsibble::reexports` for a full list of re-exported functions.
* **dplyr:**
- `arrange()`, `filter()`, `slice()`
- `mutate()`/`transmute()`, `select()`, `summarise()`/`summarize()` with an additional argument `drop = FALSE` to drop `tbl_ts` and coerce to `tbl_df`
- `rename()`
- `*_join()`
- `group_by()`, `ungroup()`
- `r emo::ji("no_entry_sign")` `distinct()`
* **tidyr:** `fill()`
* **tibble:** `glimpse()`, `as_tibble()`/`as.tibble()`
* **rlang:** `!!`, `!!!`
## Related work
* [zoo](https://CRAN.R-project.org/package=zoo): regular and irregular time series with methods.
* [xts](https://github.com/joshuaulrich/xts): extensible time series.
* [tibbletime](https://github.com/business-science/tibbletime): time-aware tibbles.
* [padr](https://github.com/EdwinTh/padr): padding of missing records in time series.