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(),
common_time = waiver(),
time_align = 0.5,
warps = waiver(),
time_warps = waiver(),
limits = NULL,
expand = waiver(),
oob = scales::censor,
guide = waiver(),
position = "bottom",
sec.axis = waiver()
)The name of the scale. Used as the axis or legend title. If
waiver(), the default, the name of the scale is taken from the first
mapping used for that aesthetic. If NULL, the legend title will be
omitted.
One of:
NULL for no breaks
waiver() for the breaks specified by date_breaks
A Date/POSIXct vector giving positions of breaks
A function that takes the limits as input and returns breaks as output
A duration giving the distance between breaks like
"2 weeks", or "10 years". If both breaks and time_breaks are specified,
time_breaks wins.
One of:
NULL for no breaks
waiver() for the breaks specified by date_minor_breaks
A Date/POSIXct vector giving positions of minor breaks
A function that takes the limits as input and returns minor breaks as output
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.
One of the options below. Please note that when labels is a
vector, it is highly recommended to also set the breaks argument as a
vector to protect against unintended mismatches.
NULL for no labels
waiver() for the default labels computed by the
transformation object
A character vector giving labels (must be same length as breaks)
An expression vector (must be the same length as breaks). See ?plotmath for details.
A function that takes the breaks as input and returns labels as output. Also accepts rlang lambda function notation.
Uses strftime strings or similar to format the labels from the time points.
Acts like a vctrs ptype defining the common chronon to
use for mixed granularity. The default automatically selects it.
A number between 0 and 1 defining how to align coarser granularities onto the common time scale. 0 means start alignment, 1 means end alignment, and 0.5 means center alignment (the default).
Warp the time scale to have a consistent length, 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
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.
One of:
NULL to use the default scale range
A numeric vector of length two providing limits of the scale.
Use NA to refer to the existing minimum or maximum
A function that accepts the existing (automatic) limits and returns
new limits. Also accepts rlang lambda function
notation.
Note that setting limits on positional scales will remove data outside of the limits.
If the purpose is to zoom, use the limit argument in the coordinate system
(see coord_cartesian()).
For position scales, a vector of range expansion constants used to add some
padding around the data to ensure that they are placed some distance
away from the axes. Use the convenience function expansion()
to generate the values for the expand argument. The defaults are to
expand the scale by 5% on each side for continuous variables, and by
0.6 units on each side for discrete variables.
One of:
Function that handles limits outside of the scale limits (out of bounds). Also accepts rlang lambda function notation.
The default (scales::censor()) replaces out of
bounds values with NA.
scales::squish() for squishing out of bounds values into range.
scales::squish_infinite() for squishing infinite values into range.
A function used to create a guide or its name. See
guides() for more information.
For position scales, The position of the axis.
left or right for y axes, top or bottom for x axes.
sec_axis() is used to specify a secondary axis.
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 time_align 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.
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 time_align 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 time_align
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.
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".
## The common timezone for mixed timezone data is UTC.
#df_tz_mixed <- data.frame(
# time = mixtime::mixtime(
# as.POSIXct("2023-10-01", tz = "Australia/Melbourne") + 0:23 * 3600,
# as.POSIXct("2023-10-01", tz = "America/New_York") + 0:23 * 3600
# ),
# value = c(cumsum(rnorm(12, 2)), cumsum(rnorm(12, -2)))
#)
#ggplot(df_tz_mixed, aes(time, value)) +
# geom_time_line()
## Alternative breaks and labels apply to the common time scale.
#ggplot(df_tz_mixed, aes(time, value)) +
# geom_time_line() +
# scale_x_mixtime(time_breaks = "6 hours", time_labels = "%H:%M")
## Plotting monthly and daily data together will align months to the middle day of the month.
#df_chronon_mixed <- data.frame(
# time = c(
# mixtime::yearmonth("2023-01") + 0:11,
# as.Date("2023-01-01") + 0:364
# ),
# value = c(cumsum(rnorm(12, 30)), cumsum(rnorm(365, 1)))
#)
## Warping the x-axis
#ggplot(df_chronon_mixed, aes(time, value)) +
# geom_time_line(time_warps = "1 month")