between_time: Between (For Time Series): Range detection for date or...

View source: R/dplyr-between_time.R

between_timeR Documentation

Between (For Time Series): Range detection for date or date-time sequences

Description

The easiest way to filter time series date or date-time vectors. Returns a logical vector indicating which date or date-time values are within a range. See filter_by_time() for the data.frame (tibble) implementation.

Usage

between_time(index, start_date = "start", end_date = "end")

Arguments

index

A date or date-time vector.

start_date

The starting date

end_date

The ending date

Details

Pure Time Series Filtering Flexibilty

The start_date and end_date parameters are designed with flexibility in mind.

Each side of the time_formula is specified as the character 'YYYY-MM-DD HH:MM:SS', but powerful shorthand is available. Some examples are:

  • Year: ⁠start_date = '2013', end_date = '2015'⁠

  • Month: ⁠start_date = '2013-01', end_date = '2016-06'⁠

  • Day: ⁠start_date = '2013-01-05', end_date = '2016-06-04'⁠

  • Second: ⁠start_date = '2013-01-05 10:22:15', end_date = '2018-06-03 12:14:22'⁠

  • Variations: ⁠start_date = '2013', end_date = '2016-06'⁠

Key Words: "start" and "end"

Use the keywords "start" and "end" as shorthand, instead of specifying the actual start and end values. Here are some examples:

  • Start of the series to end of 2015: ⁠start_date = 'start', end_date = '2015'⁠

  • Start of 2014 to end of series: ⁠start_date = '2014', end_date = 'end'⁠

Internal Calculations

All shorthand dates are expanded:

  • The start_date is expanded to be the first date in that period

  • The end_date side is expanded to be the last date in that period

This means that the following examples are equivalent (assuming your index is a POSIXct):

  • start_date = '2015' is equivalent to start_date = '2015-01-01 + 00:00:00'

  • end_date = '2016' is equivalent to ⁠2016-12-31 + 23:59:59'⁠

Value

A logical vector the same length as index indicating whether or not the timestamp value was within the start_date and end_date range.

References

  • This function is based on the tibbletime::filter_time() function developed by Davis Vaughan.

See Also

Time-Based dplyr functions:

  • summarise_by_time() - Easily summarise using a date column.

  • mutate_by_time() - Simplifies applying mutations by time windows.

  • pad_by_time() - Insert time series rows with regularly spaced timestamps

  • filter_by_time() - Quickly filter using date ranges.

  • filter_period() - Apply filtering expressions inside periods (windows)

  • slice_period() - Apply slice inside periods (windows)

  • condense_period() - Convert to a different periodicity

  • between_time() - Range detection for date or date-time sequences.

  • slidify() - Turn any function into a sliding (rolling) function

Examples

library(dplyr)

index_daily <- tk_make_timeseries("2016-01-01", "2017-01-01", by = "day")
index_min   <- tk_make_timeseries("2016-01-01", "2017-01-01", by = "min")

# How it works
# - Returns TRUE/FALSE length of index
# - Use sum() to tally the number of TRUE values
index_daily %>% between_time("start", "2016-01") %>% sum()

# ---- INDEX SLICING ----

# Daily Series: Month of January 2016
index_daily[index_daily %>% between_time("start", "2016-01")]

# Daily Series: March 1st - June 15th, 2016
index_daily[index_daily %>% between_time("2016-03", "2016-06-15")]

# Minute Series:
index_min[index_min %>% between_time("2016-02-01 12:00", "2016-02-01 13:00")]

# ---- FILTERING WITH DPLYR ----
FANG %>%
    group_by(symbol) %>%
    filter(date %>% between_time("2016-01", "2016-01"))


timetk documentation built on Nov. 2, 2023, 6:18 p.m.