index.Rmd

---
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(timetk)
```


# timetk

[![Travis-CI Build Status](https://travis-ci.org/business-science/timetk.svg?branch=master)](https://travis-ci.org/business-science/timetk.svg?branch=master)
[![codecov](https://codecov.io/gh/business-science/timetk/branch/master/graph/badge.svg)](https://codecov.io/gh/business-science/timetk)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/timetk)](https://cran.r-project.org/package=timetk)
![](http://cranlogs.r-pkg.org/badges/timetk?color=brightgreen)
![](http://cranlogs.r-pkg.org/badges/grand-total/timetk?color=brightgreen)

<img src="README_0_logo.png" width="147" height="170" align="right" />

> A collection of tools 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 decomposition 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("README_1_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(lubridate)
```

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`