time_aggregate {timeplyr}

Aggregate time to a higher unit

Description

Aggregate time to a higher unit for possibly many groups with respect to a time index.

Usage

time_aggregate(
  x,
  time_by = NULL,
  from = NULL,
  to = NULL,
  time_type = getOption("timeplyr.time_type", "auto"),
  roll_month = getOption("timeplyr.roll_month", "preday"),
  roll_dst = getOption("timeplyr.roll_dst", "NA"),
  time_floor = FALSE,
  week_start = getOption("lubridate.week.start", 1),
  as_interval = getOption("timeplyr.use_intervals", FALSE)
)

Arguments

x

Time vector.
Can be a Date, POSIXt, numeric, integer, yearmon, or yearqtr vector.

time_by

Time unit.
Must be one of the following:

• string, e.g time_by = "day" or time_by = "2 weeks"

• lubridate duration or period object, e.g. days(1) or ddays(1).

• named list of length one, e.g. list("days" = 7).

• Numeric vector, e.g. time_by = 7.

from

Start.

to

End.

time_type

If "auto", periods are used for the time expansion when days, weeks, months or years are specified, and durations are used otherwise.

roll_month

Control how impossible dates are handled when month or year arithmetic is involved.

roll_dst

See ?timechange::time_add for the full list of details.

time_floor

Should from be floored to the nearest unit specified through the time_by argument? This is particularly useful for starting sequences at the beginning of a week or month for example.

week_start

day on which week starts following ISO conventions - 1 means Monday (default), 7 means Sunday. This is only used when time_floor = TRUE.

as_interval

Should result be a time_interval? Default is TRUE.
This can be controlled globally through options(timeplyr.use_intervals).

Details

time_aggregate aggregates time using distinct moving time range blocks of a specified time unit.

The actual calculation is extremely simple and essentially requires a subtraction, a rounding and an addition.

To perform a by-group time aggregation, simply supply collapse::fmin(x, g = groups, TRA = "replace_fill") as the from argument.

Value

A time_interval.

See Also

time_summarisev time_cut

Examples

library(timeplyr)
library(nycflights13)
library(lubridate)
library(dplyr)

sunique <- function(x) sort(unique(x))

hours <- sunique(flights$time_hour)
days <- as_date(hours)

# Aggregate by week or any time unit easily
sunique(time_aggregate(hours, "week"))
sunique(time_aggregate(hours, ddays(14)))
sunique(time_aggregate(hours, "month"))
sunique(time_aggregate(days, "month"))

# Left aligned
sunique(time_aggregate(days, "quarter"))

# Very fast by group aggregation
start <- collapse::fmin(flights$time_hour, g = flights$tailnum,
                        TRA = "replace_fill")
week_by_tailnum <- time_aggregate(flights$time_hour, time_by = ddays(7),
                                  from = start)
# Confirm this has been done by group as each group will have a
# Different aggregate start date
flights %>%
  stat_summarise(week_by_tailnum, .by = tailnum, stat = "min",
                 sort = FALSE)