time_cut: Cut dates and datetimes into regularly spaced date or...

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

Cut dates and datetimes into regularly spaced date or datetime intervals

Description

Useful functions especially for when plotting time-series. time_cut makes approximately n groups of equal time range. It prioritises the highest time unit possible, making axes look less cluttered and thus prettier. time_breaks returns only the breaks.

Usage

time_cut(
  x,
  n = 5,
  timespan = NULL,
  from = NULL,
  to = NULL,
  time_floor = FALSE,
  week_start = getOption("lubridate.week.start", 1)
)

time_cut_n(
  x,
  n = 5,
  timespan = NULL,
  from = NULL,
  to = NULL,
  time_floor = FALSE,
  week_start = getOption("lubridate.week.start", 1)
)

time_cut_width(x, timespan = granularity(x), from = NULL, to = NULL)

time_breaks(
  x,
  n = 5,
  timespan = NULL,
  from = NULL,
  to = NULL,
  time_floor = FALSE,
  week_start = getOption("lubridate.week.start", 1)
)

Arguments

x	Time vector. E.g. a Date, POSIXt, numeric or any time-based vector.
n	Number of breaks.
timespan	timespan.
from	Start time.
to	End time.
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.

Details

To retrieve regular time breaks that simply spans the range of x, use time_seq() or time_aggregate(). This can also be achieved in time_cut() by supplying n = Inf.

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 of equal width.

• 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.

Value

time_breaks returns a vector of breaks.
time_cut returns either a vector or time_interval.

Examples

library(timeplyr)
library(fastplyr)
library(cheapr)
library(lubridate)
library(ggplot2)
library(dplyr)

time_cut_n(1:10, n = 5)

# Easily create custom time breaks
df <- nycflights13::flights %>%
  f_slice_sample(n = 100) %>%
  with_local_seed(.seed = 8192821) %>%
  f_select(time_hour) %>%
  fastplyr::f_arrange(time_hour) %>%
  mutate(date = as_date(time_hour))

# time_cut_n() and time_breaks() automatically find a
# suitable way to cut the data
time_cut_n(df$date) %>%
  interval_count()
# Works with datetimes as well
time_cut_n(df$time_hour, n = 5) %>%
  interval_count()
time_cut_n(df$date, timespan = "month") %>%
  interval_count()
# Just the breaks
time_breaks(df$date, n = 5, timespan = "month")

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

# When n = Inf it should be equivalent to using time_cut_width
identical(time_cut_n(df$date, n = Inf, "month"),
          time_cut_width(df$date, "month"))
# To get exact breaks at regular intervals, use time_grid
weekly_breaks <- time_grid(
  df$date, "5 weeks",
  from = floor_date(min(df$date), "week", week_start = 1)
)
weekly_labels <- format(weekly_breaks, "%b-%d")
df %>%
  time_by(date, "week", .name = "date") %>%
  f_count() %>%
  mutate(date = interval_start(date)) %>%
  ggplot(aes(x = date, y = n)) +
  geom_bar(stat = "identity") +
  scale_x_date(breaks = weekly_breaks,
               labels = weekly_labels)

timeplyr documentation built on April 3, 2025, 6:15 p.m.