autoaxis {paletteknife}

Auto Axis Tool

Description

Overlay base plot with a new axis and optional gridlines. The axis spacing can be manually specified or automatically generated, including for date and time axis. A default grid is drawn if called with just the side specified.

Usage

autoaxis(
  side,
  major = NA,
  major_grid = FALSE,
  minor = NA,
  minor_grid = FALSE,
  format = "auto",
  spacing = TRUE,
  tck = -0.03,
  ...
)

Arguments

side

Side to add axis, 1 = bottom, 2 = left, 3 = top, 4 = right. If only this argument is given, a default dense grid is drawn. If this argument is given as a character, a date-time grid will be attempted, for example side='1'

major

Spacing of major axis ticks and labels (or approx. number of intervals if spacing = FALSE). If the axis is date or time, use a interval specified in ?seq.POSIXt, such as 'sec' or 'week', or character value for spacing such as ⁠='20'⁠

major_grid

Add grid lines corresponding to major axis ticks, TRUE to get default translucent black, otherwise colour (name or hex)

minor

Spacing (or number) of minor ticks (note, no label for minor). If given as a character string, it will pass to seq.POSIXt

minor_grid

Add gridlines for minor ticks, TRUE uses transparent black, otherwise colour string

format

Date or time format for major axis for example '%Y %b'. If left as the default 'auto' an appropriate choice between seconds and years will be used. Note, major or side must be given as a character string to trigger datetime labels.

spacing

Should major and minor be interpreted as tick spacing (default) or approximate number of ticks

tck

Size of axis tick: minor axis will always take half this value

...

Additional arguments passed to axis(), for example las=2 for perpendicular labels

Details

Major and minor tick marks can be specified in a number of ways:

• As a character string if the axis is datetime, such as 'year' or 'hour' which are passed as by to seq(). These can be prefixed with an integer multiplier, for example '6 hour' or '10 year', as per seq.POSIXt

• As a tick interval using the default spacing = TRUE

• As an approximate number of tick marks to include, using pretty() to find the best interval, using spacing = FALSE. Use a character number if this is a Date or Time axis, such as major = '100' and spacing will be set FALSE automatically.

Major adds labels and ticks, minor is just half-sized ticks marks. Both tick sizes can be changed (or direction changed) using tck.

Three different datetime axis are possible: year, day-offset, seconds-offset. Use format to specify how the label should appear, such as '%b %Y' (see ?strptime)

• Year should be treated as a conventional numeric axis, use major=1/12 not major='month'

• day-offset is an axis of class(x)=='Date' and is identified if the axis range exists within +/-9e4, meaning within dates 1723 - 2216, and minimum interval is 'day'

• second-offset is an axis of class(x)=='POSIXct' and is identified by a range outside of +/-9e4. This will give very strange results if your entire POSIXct axis is within 24 hours of 1970-01-01

A grid can be added at the same time by setting major_grid or minor_grid to TRUE or a colour string. If TRUE, a transparent black is used by default.

Any other options can be passed through to axis() directly (see ?axis), most notably las = 2 to rotate the labels, and cex.axis for label size.

The function will exit with a warning if more than 1000 ticks or gridlines were generated, as this is most likely a mistake with autogenerated date / time intervals and can lead to very slow behaviour.

This does NOT work well for barplot() categorical axis, for this continue to use the basic axis() function with custom labels, see examples.

Value

No return value (NULL)

Examples

plot(sunspots) # This time series is actually given in decimal years
  autoaxis(side=3, major=50, major_grid='coral', minor=10, minor_grid=TRUE, spacing=TRUE)
  autoaxis(side=4, major=11, minor=25, spacing=FALSE, las=2, cex.axis=0.5, tck=0.02)

plot(seq(as.POSIXct('2020-01-01'),as.POSIXct('2020-01-03'),length.out=1e3),
    rnorm(1e3), xlab='POSIXct', xaxt='n')
  autoaxis(side=1, major='day', minor='3 hour', format='%x')
  # Shortcut method to make a default dense grid
  autoaxis(side='3')
  autoaxis(side=2)
  # You can always request a datetime axis (side='4' not 4L) but it will be nonsense
  autoaxis(side='4', col='red')

plot(seq(as.Date('2013-02-01'),as.Date('2020-01-03'),length.out=1e3),
    rnorm(1e3), xlab='Date', xaxt='n')
  autoaxis(side=1, major='10', minor='50', format='%Y')
  autoaxis(side=3, minor='3 month', minor_grid=TRUE)

# Guessing is ambiguous with small values, depends on smallest interval
plot(1:500,runif(500), type='l', xaxt='n', xlab='Time or Date?', main=
  'For small values (<1e5), use interval to guess format\n')
autoaxis(1, major='min', minor='10 sec', format='%M:%S')
autoaxis(3, major='quarter', minor='month', format='%b %Y')

# For barplot() use base functions - remember to set width=1, space=0
# otherwise bars will not be plotted on integer x-coordinates
barplot(mtcars$mpg, width=1, space=0, ylab='mpg')
  # Adjust the x-axis down by 0.5 so that the tick is in centre of each bar
  axis(side=1, at=-0.5+1:length(mtcars$mpg), labels=rownames(mtcars), las=2 )
  # Often prettier, label each bar inside the bar itself using text()
  text(x=-1+1:length(mtcars$mpg), y=1, pos=4,
    labels=rownames(mtcars), srt=90, cex=0.7)
  # autoaxis can still be used for adjusting the numeric scale
  autoaxis(side=2, major=5, major_grid=TRUE, minor=1, minor_grid=TRUE)