R: Intelligent date and date-time sequence creation

tk_make_timeseries {timetk} | R Documentation

## 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)
    library(tidyquant)
    library(timetk)

    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"
    )

[Package timetk version 2.4.0 Index]