tk_make_timeseries: Intelligent date and date-time sequence creation

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

Intelligent date and date-time sequence creation

Description

Improves on the seq.Date() and seq.POSIXt() functions by simplifying into 1 function tk_make_timeseries(). Intelligently handles character dates and logical assumptions based on user inputs.

Usage

tk_make_timeseries(
  start_date,
  end_date,
  by,
  length_out = NULL,
  include_endpoints = TRUE,
  skip_values = NULL,
  insert_values = NULL
)

Arguments

start_date	Used to define the starting date for date sequence generation. Provide in "YYYY-MM-DD" format.
end_date	Used to define the ending date for date sequence generation. Provide in "YYYY-MM-DD" format.
by	A character string, containing one of "sec", "min", "hour", "day", "week", "month", "quarter" or "year". You can create regularly spaced sequences using phrases like by = "10 min". See Details.
length_out	Optional length of the sequence. Can be used instead of one of: start_date, end_date, or by. Can be specified as a number or a time-based phrase.
include_endpoints	Logical. Whether or not to keep the last value when length_out is a time-based phrase. Default is TRUE (keep last value).
skip_values	A sequence to skip
insert_values	A sequence to insert

Details

The tk_make_timeseries() function handles both date and date-time sequences automatically.

• Parses date and date times from character

• Intelligently guesses the sequence desired based on arguments provided

• Handles spacing intelligently

• When both by and length_out are missing, guesses either second or day sequences

• Can skip and insert values if needed.

Start and End Date Specification

Start and end dates can be specified in reduced time-based phrases:

• start_date = "2014": Is converted to "2014-01-01" (start of period)

• end_date = "2014": Is converted to "2014-12-31" (end of period)

• start_date = "2014-03": Is converted to "2014-03-01" (start of period)

• end_date = "2014-03": Is converted to "2014-03-31" (end of period)

A similar process can be used for date-times.

By: Daily Sequences

Make a daily sequence with tk_make_timeseries(by). Examples:

• Every Day: by = "day"

• Every 2-Weeks: by = "2 weeks"

• Every 6-months: by = "6 months"

If missing, will guess by = "day"

By: Sub-Daily Sequences

Make a sub-daily sequence with tk_make_timeseries(by). Examples:

• Every minute: by = "min"

• Every 30-seconds: by = "30 sec"

• Every 2-hours: ⁠by = "2 hours⁠

If missing, will guess by = "sec" if the start or end date is a date-time specification.

Length Out

The length_out can be specified by number of observation or complex time-based expressions. The following examples are all possible.

• length_out = 12 Creates 12 evenly spaced observations.

• length_out = "12 months" Adjusts the end date so it falls on the 12th month.

Include Endpoint

Sometimes the last date is not desired. For example, if the user specifies ⁠length_out = 12 months⁠, the user may want the last value to be the 12th month and not the 13th. Just toggle, include_endpoint = FALSE to obtain this behavior.

Skip / Insert Timestamps

Skips and inserts are performed after the sequence is generated. This means that if you use the length_out parameter, the length may differ than the length_out.

Value

A vector containing date or date-times

See Also

• Intelligent date or date-time sequence creation: tk_make_timeseries()

• Holidays and weekends: tk_make_holiday_sequence(), tk_make_weekend_sequence(), tk_make_weekday_sequence()

• Make future index from existing: tk_make_future_timeseries()

Examples

library(dplyr)

# Set max.print to 50
options_old <- options()$max.print
options(max.print = 50)

# ---- DATE ----

# Start + End, Guesses by = "day"
tk_make_timeseries("2017-01-01", "2017-12-31")

# Just Start
tk_make_timeseries("2017") # Same result

# Only dates in February, 2017
tk_make_timeseries("2017-02")

# Start + Length Out, Guesses by = "day"
tk_make_timeseries("2012", length_out = 6) # Guesses by = "day"

# Start + By + Length Out, Spacing 6 observations by monthly interval
tk_make_timeseries("2012", by = "1 month", length_out = 6)

# Start + By + Length Out, Phrase "1 year 6 months"
tk_make_timeseries("2012", by = "1 month",
                   length_out = "1 year 6 months", include_endpoints = FALSE)

# Going in Reverse, End + Length Out
tk_make_timeseries(end_date = "2012-01-01", by = "1 month",
                   length_out = "1 year 6 months", include_endpoints = FALSE)

# ---- DATE-TIME ----

# Start + End, Guesses by second
tk_make_timeseries("2016-01-01 01:01:02", "2016-01-01 01:01:04")

# Date-Time Sequence - By 10 Minutes
# - Converts to date-time automatically & applies 10-min interval
tk_make_timeseries("2017-01-01", "2017-01-02", by = "10 min")


# --- REMOVE / INCLUDE ENDPOINTS ----

# Last value in this case is desired
tk_make_timeseries("2017-01-01", by = "30 min", length_out = "6 hours")

# Last value in monthly case is not wanted
tk_make_timeseries("2012-01-01", by = "1 month",
                   length_out = "12 months",
                   include_endpoints = FALSE) # Removes unnecessary last value


# ---- SKIP & INSERT VALUES ----

tk_make_timeseries(
    "2011-01-01", length_out = 5,
    skip_values   = "2011-01-05",
    insert_values = "2011-01-06"
)

options(max.print = options_old)

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