Skip to contents

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.

See also

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)