README.Rmd

---
title: "Introduction to tqr package"
author: "Mitsuo Shiota"
date: "2019-07-19"
output: 
  github_document:
    toc: TRUE
editor_options: 
  
  chunk_output_type: console
---

<!-- badges: start -->
[![R-CMD-check](https://github.com/mitsuoxv/tqr/workflows/R-CMD-check/badge.svg)](https://github.com/mitsuoxv/tqr/actions)
<!-- badges: end -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

Updated: `r Sys.Date()`

# tqr: add-on to tsibble, inspired by tidyquant

When I utilize [`tidyquant` package](https://cran.r-project.org/web/packages/tidyquant/readme/README.html) for economic analyses, I often find myself writing similar functions repeatedly. I also find the idea of time aware dataframe of [`tsibble` package](https://cran.r-project.org/web/packages/tsibble/index.html) may help me deal with time series data more confidently. So I have decided to build this package to facilitate my work.

As of version 0.0.0.9011, I have added time-wise functions to transform a numeric vector, and a function factory using those time-wise functions, rewritten functions to transform a tsibble using that function factory, and deprecated old function factories.

1. Time-wise functions to transform a numeric vector
  - moving_average: transform into moving averages
  - growth_rate: transform into growth rates
  - season_adjust: transform into seasonally adjusted values
2. A function factory to produce functions to transform a tsibble
  - cal_time_wise: produce functions using time_wise vector functions
3. Functions to transform a tsibble
  - tq_diff: transform numeric columns into differences
  - tq_ma: transform numeric columns into moving averages
  - tq_gr: transform numeric columns into growth rates
  - tq_sa: transform numeric columns into seasonally adjusted values
4. Deprecated function factories
  - cal_factory: produce functions
  - cal_factory_zoo: produce functions utilizing zoo package
  - cal_factory_ts: produce functions utilizing ts class
  - cal_factory_xts: produce functions utilizing xts package


## Installation

This package is only for my own use for now. "You" means "future me".

You can install the development version with:

```{r install, eval=FALSE}

remotes::install_github("mitsuoxv/tqr")

```

## Libraries

As I read [Hyndman, R.J., & Athanasopoulos, G. (2021) Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3.](https://otexts.com/fpp3/), I use `fpp3` meta package here.

```{r setup, message=FALSE}

library(fpp3)
library(tqr)

```

## Transform a tsibble into lower frequency

If you are familiar with tsibble functions, like `index_by` and `group_by_key`, you can convert to lower frequency.

```{r convert1}

aus_livestock

aus_livestock %>% 
  index_by(Quarter = yearquarter(Month)) %>% 
  group_by_key() %>% 
  summarize(Count = sum(Count))

```

If you are familiar with dplyr and tidyselect functions, you can convert multiple variables at once.

```{r convert2}

aus_production

aus_production %>% 
  index_by(Year = year(Quarter)) %>% 
  summarize(across(!Quarter, sum))

```


## Time-wise functions to transform a numeric vector are useful and flexible

In the above examples, `sum` function transforms a numeric vector.

tsibble package provides `difference` function, which also transforms a time-wise numeric vector. Using it, you can create a new variable "diff".

```{r difference1}

aus_arrivals %>% 
  group_by_key() %>% 
  mutate(diff = difference(Arrivals)) %>% 
  ungroup()

```

Or you can transform a existing variable "Arrivals". You can use `difference` function flexibly.

```{r difference2}

aus_arrivals %>% 
  group_by_key() %>% 
  mutate(Arrivals = difference(Arrivals)) %>% 
  ungroup()

```

## cal_time_wise: function factory to produce a function to transform a tsibble

`cal_time_wise` function is functionized from the last example, and is a function factory. It receives a time-wise function to transform a numeric vector as its first argument, and it returns a function to transform a tsibble.

## tq_diff: calculate differences

`tq_diff` function is created like below. `tq_ma`, `tq_gr` and `tq_sa` functions are also created by this function factory.

```{r tq_diff1, eval=FALSE}

tq_diff <- cal_time_wise(
  tsibble::difference
)

```

The variables, which these created functions transform, are all numeric variables which are not key or index variables.

In the below example, "Month" is the index variable, and "State" and "Industry" are the key variables. "Series ID" is a character vector. So `tq_diff` transforms just "Turnover", a numeric variable.

```{r tq_diff2}

aus_retail %>% 
  tq_diff()

```

For arguments other than the first one, a tsibble, of `tq_diff` function, look at `tsibble::difference` document. Note that `n` in the previous version of `tq_diff` is changed to `lag`.

## "order_by" argument in time-wise functions to transform a numeric vector

You can find "order_by" argument in `tsibble::difference` document. It is optional in `difference` function.

```{r order_by1}

tsbl <- tsibble(year = 2000:2005, value = (0:5)^2, index = year)
scrambled <- tsbl %>% slice(sample(nrow(tsbl)))

wrong <- mutate(scrambled, diff = difference(value))
arrange(wrong, year)

right <- mutate(scrambled, diff = difference(value, order_by = year))
arrange(right, year)

```

`cal_time_wise` function assigns the index variable in a tsibble to "order_by" argument of `difference` function. As a result, `tq_diff` function returns right even if the rows are reshuffled.

```{r order_by2}

tsbl %>% 
  tq_diff()

scrambled %>% 
  tq_diff() %>% 
  arrange(year)

```


## moving_average and tq_ma: calculate moving averages

`moving_average` function calculates moving averages using `slider` package. "n" specifies the window width. "order_by" is optional, and works in the same way as in `difference` function. For other arguments, refer to its document.

```{r moving_average}

aus_livestock %>% 
  mutate(Count = if_else(row_number() == 4, NA_real_, Count)) %>% 
  group_by_key() %>% 
  mutate(
    ma3 = moving_average(Count, n = 3),
    ma3_na.rm = moving_average(Count, n = 3, na.rm = TRUE),
    ma3_left = moving_average(Count, n = 3, .align = "left")
    ) %>% 
  ungroup()

```

`tq_ma` function transforms "Count" variable. For arguments other than the first one, a tsibble, look at `moving_average` document.

```{r tq_ma}

aus_livestock %>% 
  tq_ma(n = 3)

```


## growth_rate and tq_gr: calculate growth rates

`growth_rate` function calculates growth rates. "n" specifies the lag. "order_by" is optional, and works in the same way as in `difference` function. For other arguments, refer to its document.

```{r growth_rate}

aus_arrivals %>% 
  group_by_key() %>% 
  mutate(
    gr_yoy = growth_rate(Arrivals, n = 4),
    gr_annualized = growth_rate(Arrivals, n = 1, annualize = 4),
    gr_yoy_not_pct = growth_rate(Arrivals, n = 4, pct = FALSE)
    )

```

`tq_gr` function transforms "Arrivals" variable in this example. For arguments other than the first one, a tsibble, look at `growth_rate` document.

```{r tq_gr}

aus_arrivals %>% 
  tq_gr(n = 4)

```


## season_adjust and tq_sa: calculate seasonally adjusted values

`season_adjust` function calculates seasonally adjusted values using `season` package. It requires not just "x" argument, a numeric vector, but also "order_by" argument, a time vector. For other arguments, refer to `season` document.

```{r season_adjust}

aus_arrivals %>% 
  group_by_key() %>% 
  mutate(sa = season_adjust(Arrivals, Quarter)) %>% 
  ungroup()

```

`tq_sa` function transforms "Arrivals" variable in this example.

```{r tq_sa1}

aus_arrivals %>% 
  tq_sa()

```

`tq_sa` function returns right even if the rows are reshuffled, as `tq_diff`, `tq_ma` and `tq_gr` functions do.

```{r tq_sa2}

aus_arrivals %>% 
  slice(sample(nrow(aus_arrivals))) %>% 
  tq_sa() %>% 
  arrange(Origin, Quarter)
  
```

EOL