Bootstrap-branded axis and legend for base R graphics

Shorthand function to apply custom Bootstrap branding, axes, and legend to base R plots. Many tips derived from r-charts.com, since base R graphic documentation is often lacking.

Usage

axes(
  axes = c(3, 4),
  main = NA,
  sub = NA,
  xlab = NA,
  ylab = NA,
  nx = NA,
  ny = NULL,
  grid.col = par("col"),
  grid.lty = "dotted",
  axis.lty = NULL,
  axis.lwd = par("lwd"),
  legend = NULL,
  par = par.brand(),
  ...
)

Arguments

main

The main title (on top) using font, size (character expansion) and color par(c("font.main", "cex.main", "col.main")).

sub

Sub-title (at bottom) using font, size and color par(c("font.sub", "cex.sub", "col.sub")).

xlab

X axis label using font, size and color par(c("font.lab", "cex.lab", "col.lab")).

ylab

Y axis label, same font attributes as xlab.

nx, ny

number of cells of the grid in x and y direction. When NULL, as per default, the grid aligns with the tick marks on the corresponding default axis (i.e., tickmarks as computed by axTicks). When NA, no grid lines are drawn in the corresponding direction.

grid.col

grdiline color

grid.lty

gridline type

legend

a character or expression vector of length \(\ge 1\) to appear in the legend. Other objects will be coerced by as.graphicsAnnot.

par

list of graphical parameters (restored on exit), defaults to par.brand().

...

Arguments passed on to graphics::legend

x,y: the x and y co-ordinates to be used to position the legend. They can be specified by keyword or in any way which is accepted by xy.coords: See ‘Details’.
fill: if specified, this argument will cause boxes filled with the specified colors (or shaded in the specified colors) to appear beside the legend text.
col: the color of points or lines appearing in the legend.
border: the border color for the boxes (used only if fill is specified).
lty,lwd: the line types and widths for lines appearing in the legend. One of these two must be specified for line drawing.
pch: the plotting symbols appearing in the legend, as numeric vector or a vector of 1-character strings (see points). Unlike points, this can all be specified as a single multi-character string. Must be specified for symbol drawing.
angle: angle of shading lines.
density: the density of shading lines, if numeric and positive. If NULL or negative or NA color filling is assumed.
bty: the type of box to be drawn around the legend. The allowed values are "o" (the default) and "n".
bg: the background color for the legend box. (Note that this is only used if bty != "n".)
box.lty,box.lwd,box.col: the line type, width and color for the legend box (if bty = "o").
pt.bg: the background color for the points, corresponding to its argument bg.
cex: character expansion factor relative to current par("cex"). Used for text, and provides the default for pt.cex.
pt.cex: expansion factor(s) for the points.
pt.lwd: line width for the points, defaults to the one for lines, or if that is not set, to par("lwd").
xjust: how the legend is to be justified relative to the legend x location. A value of 0 means left justified, 0.5 means centered and 1 means right justified.
yjust: the same as xjust for the legend y location.
x.intersp: character interspacing factor for horizontal (x) spacing between symbol and legend text.
y.intersp: vertical (y) distances (in lines of text shared above/below each legend entry). A vector with one element for each row of the legend can be used.
adj: numeric of length 1 or 2; the string adjustment for legend text. Useful for y-adjustment when labels are plotmath expressions.
text.width: the width of the legend text in x ("user") coordinates. (Should be positive even for a reversed x axis.) Can be a single positive numeric value (same width for each column of the legend), a vector (one element for each column of the legend), NULL (default) for computing a proper maximum value of strwidth(legend)), or NA for computing a proper column wise maximum value of strwidth(legend)).
text.col: the color used for the legend text.
text.font: the font used for the legend text, see text.
merge: logical; if TRUE, merge points and lines but not filled boxes. Defaults to TRUE if there are points and lines.
trace: logical; if TRUE, shows how legend does all its magical computations.
plot: logical. If FALSE, nothing is plotted but the sizes are returned.
ncol: the number of columns in which to set the legend items (default is 1, a vertical legend).
horiz: logical; if TRUE, set the legend horizontally rather than vertically (specifying horiz overrides the ncol specification).
title: a character string or length-one expression giving a title to be placed at the top of the legend. Other objects will be coerced by as.graphicsAnnot.
inset: inset distance(s) from the margins as a fraction of the plot region when legend is placed by keyword.
xpd: if supplied, a value of the graphical parameter xpd to be used while the legend is being drawn.
title.col: color for title, defaults to text.col[1].
title.adj: horizontal adjustment for title: see the help for par("adj").
title.cex: expansion factor(s) for the title, defaults to cex[1].
title.font: the font used for the legend title, defaults to text.font[1], see text.
seg.len: the length of lines drawn to illustrate lty and/or lwd (in units of character widths).

pos

position of X and Y axes, up to 4 (1-bottom, 2-left, 3-top, 4-right)

grid.lwd

gridline width

Value

Branded axis, grid, and legend definitions for base R plots

Details

This function has no side effect and does not modify the current session, but it does require at minimum to specifiy par(mar = c(2, 2, 7, 3)) to provide margin space for all plot labels.

Will look up this package built-in _brand.yml to apply colors and fonts unless brand_on() is called first.

Examples

set.seed(1)
x <- runif(100, min = -5, max = 5)
y <- x ^ 3 + rnorm(100, mean = 0, sd = 5)

# Here, no brand is active so we need to adjust `par()` manually before plotting
# and remove plot labels. Not needed when using `brand_on()`.
opar <- par(par.brand())

plot(x, y, xlab=NA, ylab=NA, axes=FALSE, main=NA, sub=NA)
axes(nx=NULL, col.sub="red",
  main="My Bootstrap Branded Plot", sub="Subtitle",
  xlab="X Units", ylab="Y Units")
abline(h=0, col="red", lwd=2)


plot(x, type="h", col=c("red", "green")[(x > 0) + 1],
  xlab=NA, ylab=NA, axes=FALSE, main=NA, sub=NA)
axes(main="My Bootstrap Branded Plot", sub="Histogram",
  xlab="X units", ylab="Y units",
  legend=c("Red", "Green"), lty=1, lwd=2, col=c("red", "green"))


hist(x, col=pal.brand(),
  xlab=NA, ylab=NA, axes=FALSE, main=NA, sub=NA)
axes(c(1,4),
  main="My Bootstrap Branded Plot",
  sub="Histogram, dummy legend", ylab="Frequency",
  axis.lty=1, legend=paste("cat", 1:3), fill=pal.brand(1:3), lty=0)



# Restore original state
par(opar)
plot(x, y, main="Default Plot")