---
title: "Introduction to tsibble"
author: "Earo Wang"
bibliography: references.bib
biblio-style: authoryear-comp
link-citations: yes
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to tsibble}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The **tsibble** package extends the [tidyverse](https://www.tidyverse.org) to temporal-context data. Built on top of the [tibble](http://tibble.tidyverse.org), a tsibble (or `tbl_ts`) is a data-centric format, following the tidy data principle [@wickham2014tidy]. Compared to the conventional time series objects in R, for example `ts` or `mts`, the tsibble preserves time indices as the essential component and makes heterogeneous data structures possible. Beyond the tibble-like representation, new syntax is introduced to impose additional and informative structures on the tsibble, which is referred to as "key" variables. Multiple keys separated by a vertical bar (`|`) or a comma (`,`) are expressive of nested or crossed variables. This binds [hierarchical and grouped time series](http://pkg.earo.me/hts/) together into the `tbl_ts` class. The tsibble package aims at managing temporal data and getting analysis done in a tidy and modern manner.

```{r initial, echo = FALSE, cache = FALSE, results = 'hide'}
knitr::opts_chunk$set(
  warning = FALSE, message = FALSE, echo = TRUE,
  fig.width = 7, fig.height = 6, fig.align = 'centre',
  comment = "#>"
)
options(tibble.print_min = 5)
Sys.setenv(TZ = "")
```

The `tsibble()` creates a tsibble object, and `as_tsibble()` is an S3 method to coerce other objects to a tsibble. An object that a vector/matrix underlies, such as `ts`, `mts`, or `hts`, can be automated to a tsibble using `as_tsibble()` without any specification. If it is a tibble or data frame, the `as_tsibble()` requires a little more setup in order to identify the index and key variables.

## Index and key(s)

```{r weather}
library(tsibble)
library(lubridate)
weather <- nycflights13::weather %>% 
  select(origin, time_hour, temp, humid, precip)
weather
```

The `weather` data included in the package `nycflights13` contains the hourly meteorological records (such as temperature, humid and precipitation) over the year of 2013 at three stations (i.e. JFK, LGA and EWR) in New York City. Since the `time_hour` is the only one column consisting of the timestamps, the `as_tsibble()` detects it as the index variable; alternatively, it would be more verbose to specify the argument `index = time_hour`. A tsibble is comprised of an index and key variables. In this case, the `origin` variable is the identifier created via the `id()` and passed to the `key` argument in the `as_tsibble()`. Therefore, **the key together with the index uniquely identifies each observation**, which gives a valid tsibble. In other words, each unit of observation is measured at a time point for a key or each combination of keys. Others---`temp`, `humid` and `precip`---are considered as measured variables.

```{r weather-ts, message = TRUE}
weather_tsbl <- as_tsibble(weather, key = id(origin))
weather_tsbl
```

The tsibble fully utilises the `print` method from tibble: a tsibble object (along with its dimension and time interval) and key variables in the header. Above displays the `weather_tsbl` its one-hour interval and the `origin` as keys. It should be noted that the tsibble does not attempt to arrange the data in time order. Given this format, it is much easier for users, in particular who are familiar with tidyverse, to perform common data tasks in temporal context. For example the `tsummarise()` (summarise over time) is used to examine daily highs and lows at each station. As a result, the index is updated to the `date` with one-day interval from `time_hour`; two new variables are created and computed for daily maximum and minimum temperatures.

```{r weather-tsum}
weather_tsbl %>%
  group_by(origin) %>%
  tsummarise(
    date = as_date(time_hour),
    temp_high = max(temp, na.rm = TRUE),
    temp_low = min(temp, na.rm = TRUE)
  )
```

## Nested and crossed keys

The key is not constrained to a single variable, but expressive of nested and crossed data structures [@wilkinson2006grammar]. A built-in dataset `tourism` includes the quarterly overnight trips from 1998 Q1 to 2016 Q4 across Australia, which is sourced from [Tourism Research Australia](https://www.tra.gov.au). The key structure is imposed by `Region | State, Purpose`. The `Region` and `State` naturally form a two-level geographical hierarchy: the lower-level regions are nested into the higher-level states. This nesting/hierarchical structure is indicated using a vertical bar (`|`). The crossing of `Purpose` (purpose of visiting) with the geographical variables suffices to validate the tsibble, where a comma (`,`) separates these two groups. Each observation is the number of trips made to a specific region for a certain purpose of travelling at one quarter of the year.

```{r tourism}
as_tsibble(tourism, key = id(Region | State, Purpose), index = Quarter)
```

The commonly used dplyr verbs, such as `filter()`, `summarise()` and `mutate()`, have been implemented to support the tsibble. To obtain the numerical summaries for the nesting of geography, the `summarise()` is performed in conjunction with the `Region | State` in the `group_by()`. This specification retains the hierarchical structure. The tsibble `summarise()` never collapses the rows over the time index, which is slightly different from the dplyr `summarise()`.

```{r tourism-sum}
tourism %>%
  group_by(Region | State) %>%
  summarise(Geo_Trips = sum(Trips))
```

This syntactical approach appears more advantageous for the structural variables when coming to hierarchical and grouped time series forecast.

## Intervals

It has been seen that the tsibble handles regularly-spaced temporal data well, from seconds to years. The option `regular`, by default, is set to `TRUE` in the `as_tsibble()`. Specify `regular` to `FALSE` to create a tsibble for the data collected at irregular time interval. Below shows the scheduled date time of the flights in New York City:

```{r flights}
flights <- nycflights13::flights %>%
  mutate(
    sched_dep_datetime = make_datetime(year, month, day, hour, minute, 0),
    flight_num = paste0(carrier, flight)
  )
```

The key variable is the `flight_num`. With `regular = FALSE`, it turns to an irregularly-spaced tsibble, where `[!]` highlights the irregularity.

```{r flights-ts}
flights_tsbl <- flights %>%
  as_tsibble(
    key = id(flight_num), 
    index = sched_dep_datetime, 
    regular = FALSE
  )
flights_tsbl
```

More functions on their way to deal with irregular temporal data in the future release.

## Reference
