forked from business-science/timetk
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
195 lines (132 loc) · 6.28 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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
message = F,
warning = F,
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
```{r, echo=FALSE}
library(tidyquant)
library(timetk)
```
# timetk
[](https://travis-ci.org/business-science/timetk.svg?branch=master)
[](https://codecov.io/gh/business-science/timetk)
[](https://cran.r-project.org/package=timetk)
<img src="tools/logo.png" width="147" height="170" align="right" />
> A toolkit for working with time series in R
## Benefits
The `timetk` package enables a user to more easily work with time series objects in R. The package has tools for inspecting and manipulating the time-based index, expanding the time features for data mining and machine learning, and converting time-based objects to and from the many time series classes. The following are key benefits:
* __Index extraction__: get the time series index from any time series object.
* __Understand time series__: create a signature and summary from a time series index.
* __Build future time series__: create a future time series from an index.
* __Coerce between time-based tibbles (`tbl`) and the major time series data types `xts`, `zoo`, `zooreg`, and `ts`__: Simplifies coercion and maximizes time-based data retention during coercion to regularized time series (e.g. `ts`).
An example of the forecasting capabilities as shown in vignette TK03 - Forecasting Using a Time Series Signature with `timetk`.
```{r echo=FALSE, out.width='100%'}
knitr::include_graphics("tools/bikes_forecast.png")
```
## Tools
The package contains the following functions:
1. __Get an index__: `tk_index` returns the time series index of time
series objects, models. The argument `timetk_idx` can be used to return a
special timetk "index" attribute for regularized `ts` objects that returns a
non-regularized date / date-time index if present.
2. __Get critical timeseries information__: `tk_get_timeseries_signature` and `tk_get_timeseries_summary` takes an index and provides a time series decomposition and key summary attributes of the index, respectively. The `tk_augment_timeseries_signature` expedites adding the time series decomposition to the time series object.
3. __Make a future timeseries__: `tk_make_future_timeseries` models a
future time series after an existing time series index.
4. __Coercion functions__: `tk_tbl`, `tk_ts`, `tk_xts`, `tk_zoo`, and
`tk_zooreg` coerce time-based tibbles `tbl` to and from each of the main
time-series data types `xts`, `zoo`, `zooreg`, `ts`, maintaining the time-based
index.
## Getting started
Load libraries and start with some time series data
```{r}
library(timetk)
library(tidyquant)
```
Use the FB time series.
```{r}
FB_tbl <- FANG %>%
filter(symbol == "FB")
FB_tbl
```
## Extract a time series index
Get the timeseries index.
```{r}
idx <- tk_index(FB_tbl)
head(idx)
```
## Expand the time series signature
Get the time series signature from the index, a tibble of decomposed features that are useful for __data mining__ and __machine learning__.
```{r}
tk_get_timeseries_signature(idx)
```
## Get a summary of the time series
Get the time series summary from the index, a single-row tibble of key summary information from the time series.
```{r}
# General summary
tk_get_timeseries_summary(idx)[1:6]
# Frequency summary
tk_get_timeseries_summary(idx)[6:12]
```
## Make a future time series
Use an index to make a future time series.
```{r}
holidays <- c("2017-01-02", "2017-01-16", "2017-02-20",
"2017-04-14", "2017-05-29", "2017-07-04",
"2017-09-04", "2017-11-23", "2017-12-25") %>%
ymd()
idx_future <- tk_make_future_timeseries(
idx,
n_future = 366,
skip_values = holidays,
inspect_weekdays = TRUE)
head(idx_future)
```
```{r}
tail(idx_future)
```
## Coerce time series without specifying order.by or worrying about coercion issues
Coercion to `xts`, `zoo`, or `ts` is simplified. The data is ordered correctly automatically using the column containing the date or datetime information. Non-numeric columns are automatically dropped with a warning to the user (the `silent = TRUE` hides the warnings).
```{r}
# xts
FB_xts <- tk_xts(FB_tbl, silent = TRUE)
```
```{r}
# zoo
FB_zoo <- tk_zoo(FB_tbl, silent = TRUE)
```
```{r}
# ts
FB_ts <- tk_ts(FB_tbl, start = 2013, freq = 252, silent = TRUE)
```
This covers the basics of the `timetk` package capabilities. Here's how to get started.
## Installation
_Download development version with latest features_:
``` {r, eval = FALSE}
# install.packages("devtools")
devtools::install_github("business-science/timetk")
```
_Or, download CRAN approved version_:
```{r, eval = FALSE}
install.packages("timetk")
```
## Acknowledgements: Standing On Shoulders
A lot of innovative time series and forecasting work is going on that ultimately benefits the community. We'd like to thank the following people and packages that came before `timetk` in time series analysis and machine learning.
* [`maltese`](https://github.com/bearloga/maltese): Similar in respect to `timetk` in that it enables machine learning-friendly data frame generation exposing a number of critical features that can be used for forecasting.
* [`lubridate`](https://github.com/hadley/lubridate): Contains an excellent set of functions to extract components of the date and datetime index.
* [`xts`](https://github.com/joshuaulrich/xts) and `zoo`: Fundamental packages for working with time series enabling creation of a time series index for `ts` class and calculating periodicity.
## Further Information
The `timetk` package includes a vignette to help users get up to speed quickly:
* TK00 - Time Series Coercion Using `timetk`
* TK01 - Working with the Time Series Index using `timetk`
* TK02 - Making a Future Time Series Index using `timetk`
* TK03 - Forecasting Using a Time Series Signature with `timetk`