Intelligent date and date-time sequence creation

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

Value

A vector containing date or date-times

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.

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")
#> Using by: day
#>  [1] "2017-01-01" "2017-01-02" "2017-01-03" "2017-01-04" "2017-01-05"
#>  [6] "2017-01-06" "2017-01-07" "2017-01-08" "2017-01-09" "2017-01-10"
#> [11] "2017-01-11" "2017-01-12" "2017-01-13" "2017-01-14" "2017-01-15"
#> [16] "2017-01-16" "2017-01-17" "2017-01-18" "2017-01-19" "2017-01-20"
#> [21] "2017-01-21" "2017-01-22" "2017-01-23" "2017-01-24" "2017-01-25"
#> [26] "2017-01-26" "2017-01-27" "2017-01-28" "2017-01-29" "2017-01-30"
#> [31] "2017-01-31" "2017-02-01" "2017-02-02" "2017-02-03" "2017-02-04"
#> [36] "2017-02-05" "2017-02-06" "2017-02-07" "2017-02-08" "2017-02-09"
#> [41] "2017-02-10" "2017-02-11" "2017-02-12" "2017-02-13" "2017-02-14"
#> [46] "2017-02-15" "2017-02-16" "2017-02-17" "2017-02-18" "2017-02-19"
#>  [ reached 'max' / getOption("max.print") -- omitted 315 entries ]

# Just Start
tk_make_timeseries("2017") # Same result
#> Using by: day
#>  [1] "2017-01-01" "2017-01-02" "2017-01-03" "2017-01-04" "2017-01-05"
#>  [6] "2017-01-06" "2017-01-07" "2017-01-08" "2017-01-09" "2017-01-10"
#> [11] "2017-01-11" "2017-01-12" "2017-01-13" "2017-01-14" "2017-01-15"
#> [16] "2017-01-16" "2017-01-17" "2017-01-18" "2017-01-19" "2017-01-20"
#> [21] "2017-01-21" "2017-01-22" "2017-01-23" "2017-01-24" "2017-01-25"
#> [26] "2017-01-26" "2017-01-27" "2017-01-28" "2017-01-29" "2017-01-30"
#> [31] "2017-01-31" "2017-02-01" "2017-02-02" "2017-02-03" "2017-02-04"
#> [36] "2017-02-05" "2017-02-06" "2017-02-07" "2017-02-08" "2017-02-09"
#> [41] "2017-02-10" "2017-02-11" "2017-02-12" "2017-02-13" "2017-02-14"
#> [46] "2017-02-15" "2017-02-16" "2017-02-17" "2017-02-18" "2017-02-19"
#>  [ reached 'max' / getOption("max.print") -- omitted 315 entries ]

# Only dates in February, 2017
tk_make_timeseries("2017-02")
#> Using by: day
#>  [1] "2017-02-01" "2017-02-02" "2017-02-03" "2017-02-04" "2017-02-05"
#>  [6] "2017-02-06" "2017-02-07" "2017-02-08" "2017-02-09" "2017-02-10"
#> [11] "2017-02-11" "2017-02-12" "2017-02-13" "2017-02-14" "2017-02-15"
#> [16] "2017-02-16" "2017-02-17" "2017-02-18" "2017-02-19" "2017-02-20"
#> [21] "2017-02-21" "2017-02-22" "2017-02-23" "2017-02-24" "2017-02-25"
#> [26] "2017-02-26" "2017-02-27" "2017-02-28"

# Start + Length Out, Guesses by = "day"
tk_make_timeseries("2012", length_out = 6) # Guesses by = "day"
#> Using by: day
#> [1] "2012-01-01" "2012-01-02" "2012-01-03" "2012-01-04" "2012-01-05"
#> [6] "2012-01-06"

# Start + By + Length Out, Spacing 6 observations by monthly interval
tk_make_timeseries("2012", by = "1 month", length_out = 6)
#> [1] "2012-01-01" "2012-02-01" "2012-03-01" "2012-04-01" "2012-05-01"
#> [6] "2012-06-01"

# 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)
#>  [1] "2012-01-01" "2012-02-01" "2012-03-01" "2012-04-01" "2012-05-01"
#>  [6] "2012-06-01" "2012-07-01" "2012-08-01" "2012-09-01" "2012-10-01"
#> [11] "2012-11-01" "2012-12-01" "2013-01-01" "2013-02-01" "2013-03-01"
#> [16] "2013-04-01" "2013-05-01" "2013-06-01"

# 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)
#>  [1] "2010-08-01" "2010-09-01" "2010-10-01" "2010-11-01" "2010-12-01"
#>  [6] "2011-01-01" "2011-02-01" "2011-03-01" "2011-04-01" "2011-05-01"
#> [11] "2011-06-01" "2011-07-01" "2011-08-01" "2011-09-01" "2011-10-01"
#> [16] "2011-11-01" "2011-12-01" "2012-01-01"

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

# Start + End, Guesses by second
tk_make_timeseries("2016-01-01 01:01:02", "2016-01-01 01:01:04")
#> Using by: sec
#> [1] "2016-01-01 01:01:02 UTC" "2016-01-01 01:01:03 UTC"
#> [3] "2016-01-01 01:01:04 UTC"

# 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")
#>  [1] "2017-01-01 00:00:00 UTC" "2017-01-01 00:10:00 UTC"
#>  [3] "2017-01-01 00:20:00 UTC" "2017-01-01 00:30:00 UTC"
#>  [5] "2017-01-01 00:40:00 UTC" "2017-01-01 00:50:00 UTC"
#>  [7] "2017-01-01 01:00:00 UTC" "2017-01-01 01:10:00 UTC"
#>  [9] "2017-01-01 01:20:00 UTC" "2017-01-01 01:30:00 UTC"
#> [11] "2017-01-01 01:40:00 UTC" "2017-01-01 01:50:00 UTC"
#> [13] "2017-01-01 02:00:00 UTC" "2017-01-01 02:10:00 UTC"
#> [15] "2017-01-01 02:20:00 UTC" "2017-01-01 02:30:00 UTC"
#> [17] "2017-01-01 02:40:00 UTC" "2017-01-01 02:50:00 UTC"
#> [19] "2017-01-01 03:00:00 UTC" "2017-01-01 03:10:00 UTC"
#> [21] "2017-01-01 03:20:00 UTC" "2017-01-01 03:30:00 UTC"
#> [23] "2017-01-01 03:40:00 UTC" "2017-01-01 03:50:00 UTC"
#> [25] "2017-01-01 04:00:00 UTC" "2017-01-01 04:10:00 UTC"
#> [27] "2017-01-01 04:20:00 UTC" "2017-01-01 04:30:00 UTC"
#> [29] "2017-01-01 04:40:00 UTC" "2017-01-01 04:50:00 UTC"
#> [31] "2017-01-01 05:00:00 UTC" "2017-01-01 05:10:00 UTC"
#> [33] "2017-01-01 05:20:00 UTC" "2017-01-01 05:30:00 UTC"
#> [35] "2017-01-01 05:40:00 UTC" "2017-01-01 05:50:00 UTC"
#> [37] "2017-01-01 06:00:00 UTC" "2017-01-01 06:10:00 UTC"
#> [39] "2017-01-01 06:20:00 UTC" "2017-01-01 06:30:00 UTC"
#> [41] "2017-01-01 06:40:00 UTC" "2017-01-01 06:50:00 UTC"
#> [43] "2017-01-01 07:00:00 UTC" "2017-01-01 07:10:00 UTC"
#> [45] "2017-01-01 07:20:00 UTC" "2017-01-01 07:30:00 UTC"
#> [47] "2017-01-01 07:40:00 UTC" "2017-01-01 07:50:00 UTC"
#> [49] "2017-01-01 08:00:00 UTC" "2017-01-01 08:10:00 UTC"
#>  [ reached 'max' / getOption("max.print") -- omitted 95 entries ]


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

# Last value in this case is desired
tk_make_timeseries("2017-01-01", by = "30 min", length_out = "6 hours")
#>  [1] "2017-01-01 00:00:00 UTC" "2017-01-01 00:30:00 UTC"
#>  [3] "2017-01-01 01:00:00 UTC" "2017-01-01 01:30:00 UTC"
#>  [5] "2017-01-01 02:00:00 UTC" "2017-01-01 02:30:00 UTC"
#>  [7] "2017-01-01 03:00:00 UTC" "2017-01-01 03:30:00 UTC"
#>  [9] "2017-01-01 04:00:00 UTC" "2017-01-01 04:30:00 UTC"
#> [11] "2017-01-01 05:00:00 UTC" "2017-01-01 05:30:00 UTC"
#> [13] "2017-01-01 06:00:00 UTC"

# 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
#>  [1] "2012-01-01" "2012-02-01" "2012-03-01" "2012-04-01" "2012-05-01"
#>  [6] "2012-06-01" "2012-07-01" "2012-08-01" "2012-09-01" "2012-10-01"
#> [11] "2012-11-01" "2012-12-01"


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

tk_make_timeseries(
    "2011-01-01", length_out = 5,
    skip_values   = "2011-01-05",
    insert_values = "2011-01-06"
)
#> Using by: day
#> [1] "2011-01-01" "2011-01-02" "2011-01-03" "2011-01-04" "2011-01-06"

options(max.print = options_old)

Usage

Arguments

Value

Details

See also

Examples