legendBreaks: Add a legend with thresholded values to a plot

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

Add a legend with thresholded values to a plot

Description

This function adds a legend to an existing plot that shows blocks of color. It is useful, for example, for displaying maps of continuous values that have been thresholded at multiple values. It first draws a "containing" box then inside the box a second box with a set of stacked bars, one per color. A legend title and labels for levels indicated by the color bar can be added.

Usage

legendBreaks(
  x,
  y = NULL,
  inset = 0,
  horiz = FALSE,
  width = 0.2,
  height = 0.5,
  labels = c(0.25, 0.5, 0.75),
  labAdjX = 0.75,
  labAdjY = c(0.25, 0.5, 0.75),
  col = c("gray", "yellow", "orange", "red"),
  colBorder = NA,
  border = "black",
  title = "Title",
  titleAdj = c(0.5, 0.9),
  adjX = c(0.2, 0.5),
  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.
horiz	Logical, if FALSE (default), color boxes are plotted in along a column. If TRUE, then color boxes are plotted along a row.
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.
labAdjX	Numeric or numeric vector of values typically between 0 and 1. If horiz is FALSE (default), then this a single value indicating the horizontal position of labels relative to the colored part of the legend. If horiz is TRUE, then this is a vector of numbers typically between 0 and 1 indicating horizontal position of labels relative to the colored part of the legend (0 = left, 1 = right).
labAdjY	Numeric vector of values or a single numeric value typically between 0 and 1. If horiz is FALSE (default), then this a vector of numbers typically between 0 and 1 indicating the vertical position of labels relative to the colord part of the legend (0 = bottom, 1 = top). If horiz is TRUE, then this is a single value indicating the vertical position of labels relative to the containing box.
col	List of characters or integers. Names of colors. The first color will be the lowest value and the last the highest value.
colBorder	Characters or integer. Names of color to be used to draw an outline around each color in the color box. Use NA (default) to skip drawing an outline.
border	Character or integer. Name (or integer code) of color to use to draw border of the color bar.
title	Character or NULL. Name of title for the legend.
titleAdj	Two numeric values between 0 and 1. Position of the legend relative to the legend box. The first pertains to horizontal positioning and the second vertical positioning.
adjX	Two numeric values between 0 and 1. Size of the color bar in the x-dimension as a proportion of the legend 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 color bar in the y-dimension as a proportion of the legend 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 color 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 typically between 0 and 1. This is only used if horiz = FALSE (default). Size of the swatches the in y-dimension as a proportion of the legend box size. The first pertains to the bottom side of the swatch and the second the top side. swatchAdjX Two numeric values typically between 0 and 1. This is only used if horiz = TRUE. Size of the swatches the in x-dimension as a proportion of the legend box size. The first pertains to the left side of the swatch and the second the right side. col Character or integer representing the swatch's color. border Character or integer. Name (or integer code) of color to use to draw border of the swatch. labels Character, for labeling the swatch.
...	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

data(welfare)

# for visual clarity, put countries with high HIV on bottom
# of data frame so they're plotted last
welfare <- welfare[order(welfare$hivAge15to49_2018_perc), ]
welfare <- rbind(
	welfare[is.na(welfare$hivAge15to49_2018_perc), ],
	welfare[!is.na(welfare$hivAge15to49_2018_perc), ]
)

pop <- welfare$population2019
gdp <- welfare$gdp_2019usd
hiv <- welfare$hivAge15to49_2018_perc
hiv <- hiv / 100

gdpPerCap <- gdp / pop

# color categories
hivMax <- max(hiv, na.rm=TRUE)
cols <- rep(NA, length(hiv))
cols[hiv <= hivMax] <- 'darkred'
cols[hiv <= 0.75 * hivMax] <- 'red'
cols[hiv <= 0.5 * hivMax] <- 'lightsalmon'
cols[hiv <= 0.25 * hivMax] <- 'white'
cols[is.na(hiv)] <- 'gray'

# legend label positions
hivQuants <- hivMax * c(0, 0.25, 0.5, 0.75, 1)
hivLabelPos <- c(0, hivQuants / hivMax)
labels <- sprintf('%.2f', c(0, hivQuants))

# vertical alignment of legend
plot(log10(gdp), gdpPerCap,
	pch=21,	cex=2, bg=cols, xlab='GDP (log 2019 USD)',
ylab='2019 GDP per Capita (USD)',
)

legendBreaks(
	x='bottomright',
	y = NULL,
	inset = 0.02,
width = 0.23,
height = 0.7,
labels = labels,
labAdjX = 0.75,
labAdjY = hivLabelPos,
col = c('white', 'lightsalmon', 'red', 'darkred'),
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',
		border='black',
		labels='NA'
	)
)
)

# horizontal alignment of legend
plot(log10(gdp), gdpPerCap,
pch=21,	cex=2, bg=cols, xlab='GDP (log 2019 USD)',
ylab='2019 GDP per Capita (USD)',
)

legendBreaks(
x = 'topleft',
y = NULL,
horiz = TRUE,
inset = 0.02,
width = 0.7,
height = 0.23,
labels = labels,
labAdjX = hivLabelPos,
labAdjY = 0.13,
col = c('white', 'lightsalmon', 'red', 'darkred'),
border = 'black',
title = 'HIV (%)',
titleAdj = c(0.5, 0.9),
adjX = c(0.2, 0.95),
adjY = c(0.3, 0.8),
boxBorder = NA,
boxBg = NA,
swatches=list(
	list(
		swatchAdjX=c(0.03, 0.18),
		col='gray',
		border='black',
		labels='NA'
	)
)
)

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