future_frame: Make future time series from existing

In business-science/timekit: A Tool Kit for Working with Time Series

Make future time series from existing

Description

Make future time series from existing

Usage

future_frame(
  .data,
  .date_var,
  .length_out,
  .inspect_weekdays = FALSE,
  .inspect_months = FALSE,
  .skip_values = NULL,
  .insert_values = NULL,
  .bind_data = FALSE
)

Arguments

.data	A data.frame or tibble
.date_var	A date or date-time variable.
.length_out	Number of future observations. Can be numeric number or a phrase like "1 year".
.inspect_weekdays	Uses a logistic regression algorithm to inspect whether certain weekdays (e.g. weekends) should be excluded from the future dates. Default is FALSE.
.inspect_months	Uses a logistic regression algorithm to inspect whether certain days of months (e.g. last two weeks of year or seasonal days) should be excluded from the future dates. Default is FALSE.
.skip_values	A vector of same class as idx of timeseries values to skip.
.insert_values	A vector of same class as idx of timeseries values to insert.
.bind_data	Whether or not to perform a row-wise bind of the .data and the future data. Default: FALSE

Details

This is a wrapper for tk_make_future_timeseries() that works on data.frames. It respects dplyr groups.

Specifying Length of Future Observations

The argument .length_out determines how many future index observations to compute. It can be specified as:

• A numeric value - the number of future observations to return.

  • The number of observations returned is always equal to the value the user inputs.

  • The end date can vary based on the number of timestamps chosen.

• A time-based phrase - The duration into the future to include (e.g. "6 months" or "30 minutes").

  • The duration defines the end date for observations.

  • The end date will not change and those timestamps that fall within the end date will be returned (e.g. a quarterly time series will return 4 quarters if .length_out = "1 year").

  • The number of observations will vary to fit within the end date.

Weekday and Month Inspection

The .inspect_weekdays and .inspect_months arguments apply to "daily" (scale = "day") data (refer to tk_get_timeseries_summary() to get the index scale).

• The .inspect_weekdays argument is useful in determining missing days of the week that occur on a weekly frequency such as every week, every other week, and so on. It's recommended to have at least 60 days to use this option.

• The .inspect_months argument is useful in determining missing days of the month, quarter or year; however, the algorithm can inadvertently select incorrect dates if the pattern is erratic.

Skipping / Inserting Values

The .skip_values and .insert_values arguments can be used to remove and add values into the series of future times. The values must be the same format as the idx class.

• The .skip_values argument useful for passing holidays or special index values that should be excluded from the future time series.

• The .insert_values argument is useful for adding values back that the algorithm may have excluded.

Binding with Data

Rowwise binding with the original is so common that I've added an argument .bind_data to perform a row-wise bind of the future data and the incoming data.

This replaces the need to do:

df %>%
   future_frame(.length_out = "6 months") %>%
   bind_rows(df, .)

Now you can just do:

df %>%
    future_frame(.length_out = "6 months", .bind_data = TRUE)

Value

A tibble that has been extended with future date, date-time timestamps.

See Also

• Making Future Time Series: tk_make_future_timeseries() (Underlying function)

Examples

library(dplyr)

# 30-min interval data
taylor_30_min %>%
    future_frame(date, .length_out = "1 week")

# Daily Data (Grouped)
m4_daily %>%
    group_by(id) %>%
    future_frame(date, .length_out = "6 weeks")

# Specify how many observations to project into the future
m4_daily %>%
    group_by(id) %>%
    future_frame(date, .length_out = 100)

# Bind with Original Data
m4_daily %>%
    group_by(id) %>%
    future_frame(date, .length_out = 100, .bind_data = TRUE)

holidays <- tk_make_holiday_sequence(
    start_date = "2017-01-01",
    end_date   = "2017-12-31",
    calendar   = "NYSE")

weekends <- tk_make_weekend_sequence(
    start_date = "2017-01-01",
    end_date   = "2017-12-31"
)

FANG %>%
    group_by(symbol) %>%
    future_frame(
        .length_out       = "1 year",
        .skip_values      = c(holidays, weekends)
    )

business-science/timekit documentation built on Feb. 2, 2024, 2:51 a.m.