Position scales for mixtime data

Source: R/scale-time.R

These are the default scales for mixtime vectors, responsible for mapping time points to aesthetics along with identifying break points and labels for the axes and guides. To override the scales behaviour manually, use scale_*_mixtime. The primary purpose of these scales is to scale time points across multiple granularities onto a common time scale. This is achieved by identifying and coercing all time points to the finest chronon that all time points can be represented in. This common time chronon is automatically identified, but can be manually specified using the common_time.

scale_x_mixtime(
  name = waiver(),
  breaks = waiver(),
  time_breaks = waiver(),
  minor_breaks = waiver(),
  time_minor_breaks = waiver(),
  labels = waiver(),
  time_labels = waiver(),
  time_chronon = waiver(),
  align_discrete = aes_nudge(),
  warps = waiver(),
  time_warps = waiver(),
  limits = NULL,
  expand = waiver(),
  oob = scales::censor,
  guide = waiver(),
  position = "bottom",
  sec.axis = waiver()
)

scale_y_mixtime(
  name = waiver(),
  breaks = waiver(),
  time_breaks = waiver(),
  minor_breaks = waiver(),
  time_minor_breaks = waiver(),
  labels = waiver(),
  time_labels = waiver(),
  time_chronon = waiver(),
  align_discrete = aes_nudge(),
  warps = waiver(),
  time_warps = waiver(),
  limits = NULL,
  expand = waiver(),
  oob = scales::censor,
  guide = waiver(),
  position = "bottom",
  sec.axis = waiver()
)

Arguments

time_breaks

A duration giving the distance between breaks like "2 weeks", or "10 years". If both breaks and time_breaks are specified, time_breaks wins.

time_minor_breaks

A duration giving the distance between minor breaks like "2 weeks", or "10 years". If both minor_breaks and time_minor_breaks are specified, time_minor_breaks wins.

time_labels

A mixtime format string to format the labels.

time_chronon

A time granule that defines the common chronon to use for mixed granularity (e.g. mixtime::tu_day(1L)). The default automatically selects it as the finest chronon that all time points can be represented in.

align_discrete

Either a single number between 0 and 1, or a aes_nudge() object, defining how to align coarser granularities onto the common time scale.

If a single number is supplied, it is used for all positional aesthetics: 0 means start alignment, 1 means end alignment, and 0.5 means center alignment (the default).

To specify different offsets for different positional aesthetics (e.g. x, xmin, xend, y, ymin, ...), pass a aes_nudge() call, for example:

`align_discrete = aes_nudge(center = 0.5, left = 0.25, right = 0.75)“

The center, left, and right arguments apply to the semantically equivalent positional aesthetics (e.g. left applies to xstart, xmin, and xlower).

warps

Normalises the time scale to have a consistent length between specified time points, one of:

  • NULL or waiver() for no warping (the default)

  • A mixtime vector giving positions of warping points

  • A function that takes the limits as input and returns warping points as output

time_warps

A duration giving the distance between temporal warping like "2 weeks", or "10 years". If both warps and time_warps are specified, time_warps wins.

Practical usage

When using mixtime vectors to represent time variables in ggplot2, these scales are automatically applied. In most cases, the default behaviour will be sufficient for scaling time points into plot aesthetics. These scales can be used to manually adjust the scaling behaviour, such as adjusting the breaks and labels or using a different common time scale.

Similarly to the temporal scales in ggplot2 (ggplot2::scale_x_date() and ggplot2::scale_x_datetime()), these scales can adjust the breaks and labels using duration-based intervals and strftime-like formatting. These time aware options are prefixed with time_ (e.g. time_breaks and time_labels), and take precedence over the non-time aware options (e.g. breaks and labels). The scale's breaks can be specified with mixtime::duration() objects (e.g. time_breaks = mixtime::months(1L)), or with strings that can be parsed into durations (e.g. time_breaks = "1 month"). Labels for time points in Gregorian calendars can be specified using base::strftime() formats (e.g. time_labels = "%b %Y" for "Jan 2020"). Concise strings for non-Gregorian calendars are not yet supported, but can be created using custom label functions (e.g. labels = function(x) { ... }).

A core feature of these scales is the ability to handle time from multiple timezones, granularities, and calendars. This is achieved by mapping all time points to a common time scale, which is automatically identifying the finest compatible chronon that can represent the input data. This allows time points across different granularities (e.g. base::POSIXt, base::Date, and mixtime::yearmonth) to be plotted together on a common time scale. In this case the finest chronon is 1 second (from base::POSIXt), so all time points are mapped to a 1 second chronon for plotting. Mapping day and month chronons to seconds introduces indeterminancy - which second should be used to represent a day or month? This is resolved using the align_discrete argument, which defaults to center alignment. This means that a day is mapped to noon, and a month is mapped to the middle of the month.

Another time specific feature of these scales is temporal warping. This adjusts the mapping of time points to plot aesthetics to have a consistent length between specified time points. This is most useful in comparing the shapes of cycles with irregular durations, including:

  • astronomical cycles (e.g. the rising and setting of the sun)

  • economic cycles (e.g. growth and recession phases of economies)

  • predator-prey cycles (e.g. population dynamics of interacting species)

  • biological cycles (e.g. hormonal cycles)

  • calendar cycles (e.g. days in each month)

Further details about time specific scale options are described in the following sections.

Granularity alignment

Visualising mixed granularity time data introduces indeterminacy in the mapping of less precise time points onto a common time scale. For example, plotting monthly and daily data together raises the question of where to place the monthly points relative to the daily points. By default, mixtime uses center alignment, mapping the monthly points to the middle of the month. This is controlled using the align_discrete argument, which accepts a value between 0 (start alignment) and 1 (end alignment) and defaults to 0.5.

The common time scale that defines how all granularities are mapped is automatically identified based on the input data. This is achieved by finding the finest chronon that all time points can be represented in. For example, if the data contains both monthly and daily time points, the common time scale will be daily, with the monthly points aligned according to the align_discrete argument. If multiple time zones are present, the common time zone will default to UTC. The common time scale can be manually specified using the common_time argument, which accepts a mixtime::time_unit.

Temporal warping

Time scales can be warped to have a consistent length between specified time points. This is useful when visually exploring cyclical patterns where each cycle has varying length. By warping the time scale, the shape of each cycle can be more easily compared. Temporal warping is controlled using the warps argument, which accepts a mixtime vector defining the positions of the warping points. Calendar-based warping points can be conveniently specified using the time_warps argument, which accepts a duration like "1 month".

Examples

library(ggplot2)
library(dplyr)
uad_month <- tibble(
  time = mixtime::yearmonth(36L + 0:71),
  value = USAccDeaths
)
uad_year <- uad_month |>
  group_by(time = mixtime::year(time)) |>
  summarise(value = mean(value), .groups = "drop")

bind_rows(
  month = uad_month,
  year = uad_year,
  .id = "grain"
) |>
  ggplot(aes(time, value, color = grain)) +
  geom_line() +
  scale_x_mixtime()