# Automatic frequency and trend calculation from a time series index

Source:`R/get-tk_get_frequency.R`

`tk_get_frequency.Rd`

Automatic frequency and trend calculation from a time series index

## Usage

```
tk_get_frequency(idx, period = "auto", message = TRUE)
tk_get_trend(idx, period = "auto", message = TRUE)
```

## Arguments

- idx
A date or datetime index.

- period
Either "auto", a time-based definition (e.g. "2 weeks"), or a numeric number of observations per frequency (e.g. 10).

- message
A boolean. If

`message = TRUE`

, the frequency or trend is output as a message 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 tk_get_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
`tk_get_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)

When `period = "auto"`

, the `tk_time_scale_template()`

is used to calculate the frequency.

**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.

**Time Scale Template**

The `tk_time_scale_template()`

is a Look-Up Table used by the trend and period to find the
appropriate time scale. It contains three features: `time_scale`

, `frequency`

, and `trend`

.

The algorithm will inspect the scale of the time series and select the best frequency or trend 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 `tk_time_scale_template()`

.
You can modify the template with `set_tk_time_scale_template()`

.

## See also

Time Scale Template Modifiers:

`get_tk_time_scale_template()`

,`set_tk_time_scale_template()`

## Examples

```
library(dplyr)
idx_FB <- FANG %>%
filter(symbol == "FB") %>%
pull(date)
# Automated Frequency Calculation
tk_get_frequency(idx_FB, period = "auto")
#> frequency = 5 observations per 1 week
#> [1] 5
# Automated Trend Calculation
tk_get_trend(idx_FB, period = "auto")
#> trend = 64 observations per 3 months
#> [1] 64
# Manually Override Trend
tk_get_trend(idx_FB, period = "1 year")
#> trend = 252 observations per 1 year
#> [1] 252
```