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

filter_time {tibbletime} | R Documentation

## 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')

[Package tibbletime version 0.1.6 Index]