Generate a time series frequency from a periodicity

Usage

time_frequency(data, period = "auto", message = TRUE)

time_trend(data, period = "auto", message = TRUE)

Arguments

data: A tibble with a date or datetime index.
period: Either "auto", a time-based definition (e.g. "14 days"), or a numeric number of observations per frequency (e.g. 10). See tibbletime::collapse_by() for period notation.
message: A boolean. If message = TRUE, the frequency used is output along with the units in the scale of the data.

Value

Returns a scalar numeric value indicating the number of observations in the frequency or trend span.

Details

A frequency is loosely defined as the number of observations that comprise a cycle in a data set. The trend is loosely defined as time span that can be aggregated across to visualize the central tendency of the data. It's often easiest to think of frequency and trend in terms of the time-based units that the data is already in. This is what time_frequency() and time_trend() enable: using time-based periods to define the frequency or trend.

Frequency:

As an example, a weekly cycle is often 5-days (for working days) or 7-days (for calendar days). Rather than specify a frequency of 5 or 7, the user can specify period = "1 week", and time_frequency()` will detect the scale of the time series and return 5 or 7 based on the actual data.

The period argument has three basic options for returning a frequency. Options include:

"auto": A target frequency is determined using a pre-defined template (see template below).
time-based duration: (e.g. "1 week" or "2 quarters" per cycle)
numeric number of observations: (e.g. 5 for 5 observations per cycle)

The template argument is only used when period = "auto". The template is a tibble of three features: time_scale, frequency, and trend. The algorithm will inspect the scale of the time series and select the best frequency that matches the scale and number of observations per target frequency. A frequency is then chosen on be the best match. The predefined template is stored in a function time_scale_template(). However, the user can come up with his or her own template changing the values for frequency in the data frame and saving it to anomalize_options$time_scale_template.

Trend:

As an example, the trend of daily data is often best aggregated by evaluating the moving average over a quarter or a month span. Rather than specify the number of days in a quarter or month, the user can specify "1 quarter" or "1 month", and the time_trend() function will return the correct number of observations per trend cycle. In addition, there is an option, period = "auto", to auto-detect an appropriate trend span depending on the data. The template is used to define the appropriate trend span.

Examples


library(dplyr)

data(tidyverse_cran_downloads)

#### FREQUENCY DETECTION ####

# period = "auto"
tidyverse_cran_downloads %>%
    filter(package == "tidyquant") %>%
    ungroup() %>%
    time_frequency(period = "auto")
#> frequency = 7 days
#> [1] 7

time_scale_template()
#> # A tibble: 8 × 3
#>   time_scale frequency trend   
#>   <chr>      <chr>     <chr>   
#> 1 second     1 hour    12 hours
#> 2 minute     1 day     14 days 
#> 3 hour       1 day     1 month 
#> 4 day        1 week    3 months
#> 5 week       1 quarter 1 year  
#> 6 month      1 year    5 years 
#> 7 quarter    1 year    10 years
#> 8 year       5 years   30 years

# period = "1 month"
tidyverse_cran_downloads %>%
    filter(package == "tidyquant") %>%
    ungroup() %>%
    time_frequency(period = "1 month")
#> frequency = 31 days
#> [1] 31

#### TREND DETECTION ####

tidyverse_cran_downloads %>%
    filter(package == "tidyquant") %>%
    ungroup() %>%
    time_trend(period = "auto")
#> trend = 91 days
#> [1] 91