scales: label_date – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

label_date

Label date/times

Description

label_date() and label_time() label date/times using date/time format strings. label_date_short() automatically constructs a short format string suffiicient to uniquely identify labels. It's inspired by matplotlib's ConciseDateFormatter, but uses a slightly different approach: ConciseDateFormatter formats "firsts" (e.g. first day of month, first day of day) specially; date_short() formats changes (e.g. new month, new year) specially.

Usage

label_date(format = "%Y-%m-%d", tz = "UTC")

label_date_short(format = c("%Y", "%b", "%d", "%H:%M"), sep = "\n")

label_time(format = "%H:%M:%S", tz = "UTC")

date_format(format = "%Y-%m-%d", tz = "UTC")

time_format(format = "%H:%M:%S", tz = "UTC")

Arguments

format

For date_format() and time_format() a date/time format string using standard POSIX specification. See strptime() for details.

For date_short() a character vector of length 4 giving the format components to use for year, month, day, and hour respectively.

tz

a time zone name, see timezones(). Defaults to UTC

sep

Separator to use when combining date formats into a single string.

Value

All label_() functions return a "labelling" function, i.e. a function that takes a vector x and returns a character vector of length(x) giving a label for each input value.

Labelling functions are designed to be used with the labels argument of ggplot2 scales. The examples demonstrate their use with x scales, but they work similarly for all scales, including those that generate legends rather than axes.

Old interface

date_format() and time_format() are retired; please use label_date() and label_time() instead.

Examples

date_range <- function(start, days) {
  start <- as.POSIXct(start)
  c(start, start + days * 24 * 60 * 60)
}

two_months <- date_range("2020-05-01", 60)
demo_datetime(two_months)
demo_datetime(two_months, labels = date_format("%m/%d"))
# ggplot2 provides a short-hand:
demo_datetime(two_months, date_labels = "%m/%d")

# An alternative labelling system is label_date_short()
demo_datetime(two_months, date_breaks = "7 days", labels = label_date_short())
# This is particularly effective for dense labels
one_year <- date_range("2020-05-01", 365)
demo_datetime(one_year, date_breaks = "month")
demo_datetime(one_year, date_breaks = "month", labels = label_date_short())

scales

Scale Functions for Visualization

v1.1.1

MIT + file LICENSE

Authors

Hadley Wickham [aut, cre], Dana Seidel [aut], RStudio [cph]

Initial release