filter_time: Succinctly filter a 'tbl_time' object by its index

In business-science/tibbletime: Time Aware Tibbles

Succinctly filter a tbl_time object by its index

Description

Use a concise filtering method to filter a tbl_time object by its index.

Usage

filter_time(.tbl_time, time_formula)

## S3 method for class 'tbl_time'
x[i, j, drop = FALSE]

Arguments

.tbl_time	A tbl_time object.
time_formula	A period to filter over. This is specified as a formula. See Details.
x	Same as .tbl_time but consistent naming with base R.
i	A period to filter over. This is specified the same as time_formula or can use the traditional row extraction method.
j	Optional argument to also specify column index to subset. Works exactly like the normal extraction operator.
drop	Will always be coerced to FALSE by tibble.

Details

The time_formula is specified using the format from ~ to. 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: '2013' ~ '2015'

• Month: '2013-01' ~ '2016-06'

• Day: '2013-01-05' ~ '2016-06-04'

• Second: '2013-01-05 10:22:15' ~ '2018-06-03 12:14:22'

• Variations: '2013' ~ '2016-06'

The time_formula can also use a one sided formula.

• Only dates in 2015: ~'2015'

• Only dates March 2015: ~'2015-03'

The time_formula can also use 'start' and 'end' as keywords for your filter.

• Start of the series to end of 2015: 'start' ~ '2015'

• Start of 2014 to end of series: '2014' ~ 'end'

All shorthand dates are expanded:

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

• The to 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):

• '2015' ~ '2016' == '2015-01-01 + 00:00:00' ~ '2016-12-31 + 23:59:59'

• ~'2015' == '2015-01-01 + 00:00:00' ~ '2015-12-31 + 23:59:59'

• '2015-01-04 + 10:12' ~ '2015-01-05' == '2015-01-04 + 10:12:00' ~ '2015-01-05 + 23:59:59'

Special parsing is done for indices of class hms. The from ~ to time formula is specified as only HH:MM:SS.

• Start to 5th second of the 12th hour: 'start' ~ '12:00:05'

• Every second in the 12th hour: ~'12'

Subsecond resolution is also supported, however, R has a unique way of handling and printing subsecond dates and the user should be comfortable with this already. Specify subsecond resolution like so: '2013-01-01 00:00:00.1' ~ '2013-01-01 00:00:00.2'. Note that one sided expansion does not work with subsecond resolution due to seconds and subseconds being grouped together into 1 number (i.e. 1.2 seconds). This means ~'2013-01-01 00:00:00' does not expand to something like '2013-01-01 00:00:00.00' ~ '2013-01-01 00:00:00.99', but only expands to include whole seconds.

This function respects dplyr::group_by() groups.

Examples

# FANG contains Facebook, Amazon, Netflix and Google stock prices
data(FANG)
FANG <- as_tbl_time(FANG, date) %>%
  dplyr::group_by(symbol)

# 2013-01-01 to 2014-12-31
filter_time(FANG, '2013' ~ '2014')

# 2013-05-25 to 2014-06-04
filter_time(FANG, '2013-05-25' ~ '2014-06-04')

# Using the `[` subset operator
FANG['2014'~'2015']

# Using `[` and one sided formula for only dates in 2014
FANG[~'2014']

# Using `[` and column selection
FANG['2013'~'2016', c("date", "adjusted")]

# Variables are unquoted using rlang
lhs_date <- "2013"
rhs_date <- as.Date("2014-01-01")
filter_time(FANG, lhs_date ~ rhs_date)

# Use the keywords 'start' and 'end' to conveniently access ends
filter_time(FANG, 'start' ~ '2014')

# hms (hour, minute, second) classes have special parsing
hms_example <- create_series(~'12:01', 'second', class = 'hms')
filter_time(hms_example, 'start' ~ '12:01:30')

business-science/tibbletime documentation built on Jan. 28, 2023, 10:34 a.m.