---
title: "Changing periodicity"
author: "Davis Vaughan"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Changing periodicity}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Introducing as_period()

Often with time series you want to aggregate your dataset to a less 
granular period. An example of this might be moving from a daily series to 
a monthly series to look at broader trends in your data. `as_period()` allows
you to do exactly this. 

The `period` argument in `as_period()` for specifying the transformation you
want is a character with a general format of `"frequency period"` where frequency 
is a number like 1 or 2, and period is an interval like `weekly` or `yearly`. 
There must be a space between the two.

## Datasets required

```{r, message=FALSE, warning=FALSE}
library(tibbletime)
library(dplyr)

# Facebook stock prices.
data(FB)

# Convert FB to tbl_time
FB <- as_tbl_time(FB, index = date)

# FANG stock prices
data(FANG)

# Convert FANG to tbl_time and group
FANG <- as_tbl_time(FANG, index = date) %>%
  group_by(symbol)

```

## Daily to monthly

To see this in action, transform the daily `FB` data set to monthly data.

```{r}
as_period(FB, '1 month')

# Additionally, the following are equivalent
# as_period(FB, 'month')
# as_period(FB, 'm')
# as_period(FB, '1 m')
```

## Generic periods

You aren't restricted to only 1 month periods. Maybe you wanted every 2 months?

```{r}
as_period(FB, '2 m')
```

Or maybe every 25 days? Note that the dates do not line up exactly with a 
difference of 25 days. This is due to the data set not being completely regular
(there are gaps due to weekends and holidays). 
`as_period()` chooses the first date it can find in the period specified.

```{r}
as_period(FB, '25 d')
```


## Details and the `start_date` argument

By default, the date that starts the first group is calculated as:

1) Find the minimum date in your dataset.

2) Floor that date to the period that you specified. 

In the 1 month example above, `2013-01-02` is the first date in the series, 
and because "month" was chosen, the first group is defined as 
(2013-01-01 to 2013-01-31).

Occasionally this is not what you want. Consider what would happen if you 
changed the period to "every 2 days". The first date is `2013-01-02`, but 
because "day" is chosen, this isn't floored to `2013-01-01` so the groups are
(2013-01-02, 2013-01-03), (2013-01-04, 2013-01-05) and so on. 
If you wanted the first group to be (2013-01-01, 2013-01-02), you can use
the `start_date` argument.

```{r}
# Without start_date
as_period(FB, '2 d')
```

```{r}
# With start_date
as_period(FB, '2 d', start_date = "2013-01-01")
```


## The `side` argument

By default, the first date per period is returned. If you want the end of each
period instead, specify the `side = "end"` argument.

```{r}
as_period(FB, 'y', side = "end")
```

## Grouped datasets

One of the neat things about working in the `tidyverse` is that these functions
can also work with grouped datasets. Here we transform the daily series of the 
4 FANG stocks to a periodicity of every 2 years.

```{r}
FANG %>%
  as_period('2 y')
```