legendGrad: Add a gradient legend to a plot

In adamlilith/legendary: New types of plots and their legends

Add a gradient legend to a plot

Description

This function adds a legend to an existing plot that shows a gradient in color. It first draws a "containing" box then a bar with a color gradient inside the box. A legend title and labels for levels indicated by the color bar can be added.

Usage

legendGrad(
  x,
  y = NULL,
  inset = 0,
  vert = TRUE,
  width = 0.2,
  height = 0.5,
  labels = c(0, 0.33, 0.67, 1),
  labAdj = 0.75,
  labPos = 4,
  labCex = 1,
  col = c("yellow", "orange", "red"),
  border = "black",
  title = "Title",
  titleAdj = c(0.5, 0.9),
  titlePos = NULL,
  titleCex = 1,
  adjX = c(0.2, 0.65),
  adjY = c(0.1, 0.8),
  boxBg = par("bg"),
  boxBorder = "black",
  swatches = NULL,
  ...
)

Arguments

x	Numeric or character. Describes the location of the legend. This is a numeric value (in which case y must also be supplied) indicating the x-coordinate of the top left of the box surrounding the legend. Alternatively, it is a character describing the position of the box surrounding the legend relative to the existing plot ('topleft', 'topright', 'bottomleft', 'bottomright', 'top', 'bottom', 'left', 'right', or 'center').
y	Numeric or NULL.
inset	Numeric. If x is a word describing the position of the legend, then this is the degree to which the legend is inset (or outset, if negative) relative to the figure's border. If two values are supplied then the first pertains to the horizontal offset and the second the vertical offset.
vert	Logical, if TRUE (default), then the gradient will be drawn vertically and labels plotted to the left or right of the gradient. If FALSE, then the gradient will be drawn horizontally and labels will be plotted above or below the gradient. Note that if vert is FALSE then many of the default values will likely need to be changed.
width	Numeric. Scaling factor for box width.
height	Numeric. Scaling factor for box height.
labels	Vector of characters of numeric values. Labels (from least to most) of levels of the focal variable indicated by the color ramp.
labAdj	Numeric between 0 and 1. If vert is TRUE then this is the horizontal position of labels relative to the containing box. If vert is FALSE then this is the vertical position relative to the containing box.
labPos	1 (right-align labels), 2 (bottom-align labels), 3 (left-align labels), or 4 (top-align labels).
labCex	Positive numeric, size of label text.
col	List of characters or integers. Names of colors to be used to create a gradient to fill the legend bar. The first color will be the lowest value and the last the highest value.
border	Character or integer. Name (or integer code) of color to use to draw border of the gradient bar.
title	Character or NULL. Name of title for the legend.
titleAdj	Two numeric values between 0 and 1. Position of the legend title relative to the container box. The first pertains to horizontal positioning and the second vertical positioning.
titlePos	1 (right-align title), 2 (bottom-align title), 3 (left-align title), or 4 (top-align title).
titleCex	Positive numeric, size of title text.
adjX	Two numeric values between 0 and 1. Size of the gradient bar in the x-dimension as a proportion of the container box size. The first pertains to the left side of the bar and the second the right side.
adjY	Two numeric values between 0 and 1. Size of the gradient bar in the y-dimension as a proportion of the container box size. The first pertains to the bottom of the bar and the second the top.
boxBg	Character or integer. Name (or integer code) of color to use to use for box containing legend. Leave as NULL to not draw a box.
boxBorder	Character or integer. Name (or integer code) of color to use to use for box border containing legend. Leave as NULL to not draw a box border.
swatches	A list or lists, each of which contains information on extra "swatches" of a single color to add above/below/on the gradient bar. These are useful, for example, for describing data that does not fall into the range covered by the data (e.g., NA's). If swatches is NULL then it is ignored. Otherwise, it is a list of lists, and each sublist defines a different swatch. Sublists have these elements: swatchAdjY Two numeric values between 0 and 1. Size of the swatches the x-dimension as a proportion of the container box size. The first pertains to the left side of the bar and the second the right side. (Swatches will always be left-right aligned with the gradient bar.) col Character or integer representing the swatch's color. labels Character, for labelling the swatch. ... Other values to pass to polygon and text for formatting the swatch and its label (e.g., border, lwd, lty, pos, cex, etc.). These values will override any specified in ....
...	Arguments to pass to plot, polygon, or text.

Value

Nothing (side effect is to add a legend to an existing graphics device).

See Also

legend, legendQuad

Examples

wealth <- data.frame(
	country = c('USA', 'Japan', 'Malaysia', 'Germany', 'England',
'North Korea', 'South Korea', 'Nigeria'),
	pop = c(325365189, 126672000, 31718000, 82175700,
54786300, 25370000, 51446201, 185989640),
	gdp = c(18558, 5420, 913.593, 4150, 1870, 12.38, 2029, 1166),
	perCapGdp = c(145894, 57220, 28490, 50206, 34205, 583, 39446, 6351),
	hivPerc = c(0.03, 0.01, 0.40, 0.15, 0.16, NA, 0.29, 0.29)
)

# color ramp
colFx <- grDevices::colorRampPalette(c('white', 'red'))
cols <- colFx(100)
hivPerc <- round(100 * wealth$hivPerc / max(wealth$hivPerc, na.rm=TRUE))
cols <- cols[hivPerc]
cols[is.na(cols)] <- 'gray'

# rescale population (symbols size)
popRescaled <- 1 + 3 * (log10(wealth$pop) - min(log10(wealth$pop)))
plot(wealth$gdp, wealth$perCapGdp, pch=21,
cex=popRescaled, bg=cols, xlab='GDP (Billion $)', ylab='GDP Per Capita ($)')
text(wealth$gdp, wealth$perCapGdp, labels=as.character(wealth$country),
pos=4, xpd=NA)

legendGrad(
	x='bottomright',
	y = NULL,
	inset = 0.02,
	width = 0.23,
	height = 0.3,
	labels = 100 * pretty(wealth$hivPerc),
	labAdjX = 0.4,
	col = c('white', 'red'),
	border = 'black',
	title = 'HIV (%)',
	titleAdj = c(0.5, 0.9),
	adjX = c(0.2, 0.5),
	adjY = c(0.2, 0.8),
	boxBorder = 'black',
	swatches=list(
		list(
			swatchAdjY=c(0.05, 0.15),
			col='gray',
			labels='NA',
		cex=1.2,
			border='black',
		lwd=2,
		lty='dotted'
		)
	)
)

adamlilith/legendary documentation built on July 28, 2023, 8:13 p.m.