/
README.Rmd
113 lines (82 loc) · 5.71 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
---
output:
github_document:
html_preview: false
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
# tsibble <img src="man/figures/logo.png" align="right" />
[](https://github.com/tidyverts/tsibble/actions?workflow=R-CMD-check)
[](https://cran.r-project.org/package=tsibble)
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE, comment = "#>", fig.path = "man/figures/"
)
options(tibble.print_min = 5)
```
The **tsibble** package provides a data infrastructure for tidy temporal data with wrangling tools. Adapting the [tidy data principles](https://tidyr.tidyverse.org/articles/tidy-data.html), *tsibble* is a data- and model-oriented object. In *tsibble*:
1. Index is a variable with inherent ordering from past to present.
2. Key is a set of variables that define observational units over time.
3. Each observation should be uniquely identified by **index** and **key**.
4. Each observational unit should be measured at a common **interval**, if regularly spaced.
## 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("remotes")
remotes::install_github("tidyverts/tsibble")
```
## Get started
### Coerce to a tsibble with `as_tsibble()`
To coerce a data frame to *tsibble*, we need to declare key and index. For example, in the `weather` data from the package `nycflights13`, the `time_hour` containing the date-times should be declared as **index**, and the `origin` as **key**. Other columns can be considered as measured variables.
```{r nycflights13, message = FALSE}
library(dplyr)
library(tsibble)
weather <- nycflights13::weather %>%
select(origin, time_hour, temp, humid, precip)
weather_tsbl <- as_tsibble(weather, key = origin, index = time_hour)
weather_tsbl
```
The **key** can be comprised of empty, one, or more variables. See `package?tsibble` and [`vignette("intro-tsibble")`](https://tsibble.tidyverts.org/articles/intro-tsibble.html) for details.
The **interval** is computed from index based on the representation, ranging from year to nanosecond, from numerics to ordered factors. The table below shows how tsibble interprets some common time formats.
| **Interval** | **Class** |
|--------------|---------------------------|
| Annual | `integer`/`double` |
| Quarterly | `yearquarter` |
| Monthly | `yearmonth` |
| Weekly | `yearweek` |
| Daily | `Date`/`difftime` |
| Subdaily | `POSIXt`/`difftime`/`hms` |
A full list of index classes supported by tsibble can be found in `package?tsibble`.
### `fill_gaps()` to turn implicit missing values into explicit missing values
Often there are implicit missing cases in time series. If the observations are made at regular time interval, we could turn these implicit missingness to be explicit simply using `fill_gaps()`, filling gaps in precipitation (`precip`) with 0 in the meanwhile. 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_gaps(precip = 0) %>%
group_by_key() %>%
tidyr::fill(temp, humid, .direction = "down")
full_weather
```
`fill_gaps()` also handles filling in time gaps by values or functions, and respects time zones for date-times. Wanna a quick overview of implicit missing values? Check out [`vignette("implicit-na")`](https://tsibble.tidyverts.org/articles/implicit-na.html).
### `index_by()` + `summarise()` to aggregate over calendar periods
`index_by()` is the counterpart of `group_by()` in temporal context, but it groups the index only. In conjunction with `index_by()`, `summarise()` aggregates interested variables over time periods. `index_by()` goes hand in hand with the index functions including `as.Date()`, `yearweek()`, `yearmonth()`, and `yearquarter()`, as well as other friends from **lubridate**. For example, it would be of interest in computing average temperature and total precipitation per month, by applying `yearmonth()` to the index variable (referred to as `.`).
```{r tsummarise}
full_weather %>%
group_by_key() %>%
index_by(year_month = ~ yearmonth(.)) %>% # monthly aggregates
summarise(
avg_temp = mean(temp, na.rm = TRUE),
ttl_precip = sum(precip, na.rm = TRUE)
)
```
While collapsing rows (like `summarise()`), `group_by()` and `index_by()` will take care of updating the key and index respectively. This `index_by()` + `summarise()` combo can help with regularising a tsibble of irregular time space too.
## Learn more about tsibble
An ecosystem, [the tidyver*ts*](https://tidyverts.org/), is built around the *tsibble* object for tidy time series analysis.
* The [tsibbledata](https://tsibbledata.tidyverts.org) package curates a range of tsibble data examples to poke around the tsibble object.
* The [feasts](https://feasts.tidyverts.org) package provides support for visualising the data and extracting time series features.
* The [fable](https://fable.tidyverts.org) package provides common forecasting methods for tsibble, such as ARIMA and ETS. The [fabletools](https://fabletools.tidyverts.org) package, which is **fable** built upon, lays the modelling infrastructure to ease the programming with tsibble.
---
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/tidyverts/tsibble/blob/main/.github/CODE_OF_CONDUCT.md).
By participating in this project you agree to abide by its terms.