scale_tind: Time Scales for Plotting with 'ggplot2'

In tind: A Common Representation of Time Indices of Different Types

Time Scales for Plotting with ggplot2

Description

These functions provide ggplot2 scales for tind. Scales will be added automatically by ggplot2, but the default behaviour can be overridden by adding scale_*_tind to the plot.

Usage

scale_x_tind(
  name = ggplot2::waiver(),
  breaks = ggplot2::waiver(),
  minor_breaks = ggplot2::waiver(),
  n.breaks = 7L,
  labels = ggplot2::waiver(),
  limits = NULL,
  expand = ggplot2::waiver(),
  guide = ggplot2::waiver(),
  position = "bottom",
  format = NULL,
  locale = NULL
)

scale_y_tind(
  name = ggplot2::waiver(),
  breaks = ggplot2::waiver(),
  minor_breaks = ggplot2::waiver(),
  n.breaks = 7L,
  labels = ggplot2::waiver(),
  limits = NULL,
  expand = ggplot2::waiver(),
  guide = ggplot2::waiver(),
  position = "left",
  format = NULL,
  locale = NULL
)

Arguments

name	a character string with axis name, waiver() for default name, or NULL for none.
breaks	waiver() for default tick-marks, NULL for none, time indices at which tick-marks should be placed (tind), or a tdiff / character string determining distance between breaks.
minor_breaks	waiver() for default minor tick-marks, NULL for none, or time indices at which minor tick-marks should be placed.
n.breaks	an integer value, desired number of breaks.
labels	waiver() for default labels, NULL for none, or a character vector of labels.
limits	NULL for automatic limits, tinterval of length 1 or tind of length 2.
expand, guide	see scale_continuous.
position	a character string determining axis position, "bottom" or "top" for scale_x_tind, "left" or "right" for scale_y_tind.
format	(optional) a character string determining label format (see format) or a formatting function.
locale	(optional) a character string determining locale to be used for formatting labels, see calendar-names for information on locale settings.

Details

The algorithm determining positioning of breaks and minor breaks always takes the resolution of time indices (see resolution_t) into account. For example, for monthly data with breaks placed every three months (January, April, July, October) minor breaks will never be placed in the middle (mid of February, May, August, November) but rather every month. The algorithm overrides the default approach of ggplot2 — axis limits are determined based on breaks and breaks on time indices and their resolution, whereas ggplot2 starts with limits based on data and determines breaks based on limits only (ignoring the resolution of time indices).

Argument list is a bit different from that of to scale_*_date and scale_*_datetime. Firstly, n.breaks argument is supported, allowing users to set the expected number of breaks on time axis. Secondly, labels cannot be a function. Formatting functions can be provided via format argument, which also supports character string with format specification (see format) rendering date_labels argument redundant. locale argument controls the language used for month and weekday names, see calendar-names. breaks cannot be a function, but can be a tdiff / character string determining distance between breaks rendering date_breaks argument redundant. limits argument is expected to determine time interval and not limits in Cartesian coordinates. Open-ended intervals are supported.

breaks, minor_breaks, and limits cannot be functions as ggplot2 assumes that breaks and limits can be properly set based on (automatic) limits only without taking into account the resolution of time indices, which is not true.

Secondary axes are not supported.

Value

A continuous scale as returned by continuous_scale.

Note

Due to the fact that limits method is currently (as of version 4.0.0) not exported, users cannot use xlim and ylim with tind scales. Limits on time-indexed axes can be set using limits argument to scale_*_tind.

See Also

pretty for computing pretty breakpoints, axis_t for computing time axis parameters, axis.tind for creating axes with graphics package.

Examples

# artificial data
d <- seq(floor_t(today(), "y"), ceiling_t(today(), "y", ceiling = "last"))
df <- data.frame(d = d, D = as.Date(d), y = cumsum(rnorm(length(d))),
                 q = paste0("Q", quarter(d)))
# load ggplot2
have_ggplot2 <- require("ggplot2", quietly = FALSE)
# default scale
if (have_ggplot2) {
    ggplot(df) + geom_line(aes(x = d, y = y)) + theme_bw()
}
# compare with the default scale for Date
if (have_ggplot2) {
    ggplot(df) + geom_line(aes(x = D, y = y)) + theme_bw()
}
# change format
if (have_ggplot2) {
    ggplot(df) + geom_line(aes(x = d, y = y)) + theme_bw() +
        scale_x_tind(format = "%b '%y")
}
# set breaks every 4 months
if (have_ggplot2) {
    ggplot(df) + geom_line(aes(x = d, y = y)) + theme_bw() +
        scale_x_tind(breaks = "4m")
}
# set limits
if (have_ggplot2) {
    ggplot(df) + geom_line(aes(x = d, y = y), na.rm = TRUE) + theme_bw() +
        scale_x_tind(limits = c(today() %-m% 4, today()))
}
# facets with custom formatting and reduced number of breaks
if (have_ggplot2) {
    ggplot(df) + geom_line(aes(x = d, y = y)) + theme_bw() +
        scale_x_tind(n.breaks = 4, format = "%b '%y") +
        facet_wrap(~q, scales = "free_x")
}

tind documentation built on Dec. 28, 2025, 1:06 a.m.