time_aggregate: Aggregate time to a higher unit

In timeplyr: Fast Tidy Tools for Date and Date-Time Manipulation

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

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")
flights %>%
  mutate(start = collapse::fmin(time_hour, g = list(origin, dest), TRA = "replace_fill")) %>%
  mutate(week = time_aggregate(time_hour, dweeks(1), from = start)) %>%
  select(origin, dest, time_hour, week)

timeplyr documentation built on Sept. 12, 2024, 7:37 a.m.