time_cut {timeplyr}

Cut dates and datetimes into regularly spaced date or datetime intervals

Description

time_cut() is very useful for plotting with dates and datetimes and always returns breaks of regular width.

Usage

time_cut(
  x,
  n = 5,
  time_by = NULL,
  from = NULL,
  to = NULL,
  fmt = NULL,
  time_floor = FALSE,
  week_start = getOption("lubridate.week.start", 1),
  n_at_most = TRUE,
  as_factor = TRUE,
  time_type = getOption("timeplyr.time_type", "auto"),
  roll_month = getOption("timeplyr.roll_month", "preday"),
  roll_dst = getOption("timeplyr.roll_dst", "boundary")
)

time_breaks(
  x,
  n = 5,
  time_by = NULL,
  from = NULL,
  to = NULL,
  time_floor = FALSE,
  week_start = getOption("lubridate.week.start", 1),
  n_at_most = TRUE,
  time_type = getOption("timeplyr.time_type", "auto"),
  roll_month = getOption("timeplyr.roll_month", "preday"),
  roll_dst = getOption("timeplyr.roll_dst", "boundary")
)

Arguments

x

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

n

Number of breaks.

time_by

Time unit.
Must be one of the three:

• string, specifying either the unit or the number and unit, e.g time_by = "days" or time_by = "2 weeks"

• named list of length one, the unit being the name, and the number the value of the list, e.g. list("days" = 7). For the vectorized time functions, you can supply multiple values, e.g. list("days" = 1:10).

• Numeric vector. If time_by is a numeric vector and x is not a date/datetime, then arithmetic is used, e.g time_by = 1.

from

Time series start date.

to

Time series end date.

fmt

(Optional) Date/datetime format for the factor labels. If supplied, this is passed to format().

time_floor

Logical. Should the initial date/datetime be floored before building the sequence?

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.

n_at_most

Deprecated. No longer used.

as_factor

Logical. If TRUE the output is an ordered factor. Setting this to FALSE is sometimes much faster.

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. Options are "preday", "boundary", "postday", "full" and "NA". See ?timechange::time_add for more details.

roll_dst

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

Details

To specify exact widths, similar to ggplot2::cut_width(), supply time_by and n = Inf.
time_breaks() is a helper that returns only the time breaks.

By default time_cut() will try to find the prettiest way of cutting the interval by trying to cut the date/date-times into groups of the highest possible time units, starting at years and ending at milliseconds.

When x is a numeric vector, time_cut will behave similar to time_cut except for 3 things:

• The intervals are all right open and equal width, except for the rightmost interval which is closed with width <= the other widths.

• The left value of the leftmost interval is always min(x).

• Up to n breaks are created, i.e ⁠<= n⁠ breaks. This is to prioritise pretty breaks.

time_cut is a generalisation of time_summarisev such that the below identity should always hold:

 identical(time_cut(x, n = Inf, as_factor = FALSE), time_summarisev(x))

Value

time_breaks returns a vector of breaks.
time_cut returns either a factor or a vector the same class as x. In both cases it is the same length as x.

Examples

library(timeplyr)
library(lubridate)
library(ggplot2)
library(dplyr)

time_cut(1:10, n = 5)
# Easily create custom time breaks
df <- nycflights13::flights %>%
  fslice_sample(n = 10, seed = 8192821) %>%
  select(time_hour) %>%
  farrange(time_hour) %>%
  mutate(date = as_date(time_hour))

# time_cut() and time_breaks() automatically find a
# suitable way to cut the data
time_cut(df$date)
# Works with datetimes as well
time_cut(df$time_hour, n = 5) # <= 5 breaks
# Custom formatting
time_cut(df$date, fmt = "%Y %b", time_by = "month")
# Just the breaks
time_breaks(df$date, n = 5, time_by = "month")

cut_dates <- time_cut(df$date)
date_breaks <- time_breaks(df$date)

# Grouping each interval into the start of its interval
identical(date_breaks[group_id(cut_dates)],
          time_cut(df$date, as_factor = FALSE))

# WHen n = Inf and as_factor = FALSE, it should be equivalent to using
# time_aggregate or time_summarisev
identical(time_cut(df$date, n = Inf, time_by = "month", as_factor = FALSE),
          time_summarisev(df$date, time_by = "month"))
identical(time_summarisev(df$date, time_by = "month"),
          time_aggregate(df$date, time_by = "month"))

# To get exact breaks at regular intervals, use time_expandv
weekly_breaks <- time_expandv(df$date,
                              time_by = "5 weeks",
                              week_start = 1, # Monday
                              time_floor = TRUE)
weekly_labels <- format(weekly_breaks, "%b-%d")
df %>%
  time_count(time = date, time_by = "week") %>%
  ggplot(aes(x = date, y = n)) +
  geom_bar(stat = "identity") +
  scale_x_date(breaks = weekly_breaks,
               labels = weekly_labels)