addLegend {epm}

addLegend

Description

Adds a legend to an existing plot, with some additional manual controls.

Usage

addLegend(
  r,
  params = NULL,
  direction,
  side,
  location = "right",
  nTicks = 3,
  adj = NULL,
  shortFrac = 0.02,
  longFrac = 0.3,
  axisOffset = 0,
  border = TRUE,
  ramp,
  isInteger = "auto",
  ncolors = 64,
  breaks = NULL,
  minmax = NULL,
  locs = NULL,
  label = "",
  cex.axis = 0.8,
  tcl = NA,
  labelDist = 0.7,
  minDigits = 2
)

Arguments

r

the epmGrid, rasterLayer, SpatRaster or sf object that has been plotted

params

If an epmGrid plot was saved to a variable, provide that here. Contents will override other arguments.

direction

direction of color ramp. If omitted, then direction is automatically inferred, otherwise can be specified as horizontal or vertical.

side

side for tick marks, see axis documentation. Automatically inferred if omitted.

location

either a location name (see Details), or coordinates for the corners of the bar legend c(xmin, xmax, ymin, ymax).

nTicks

number of tick marks, besides min and max.

adj

if location is top, left, bottom or right, use this argument to adjust the location of the legend, defined in percent of the figure width. See Details for additional information.

shortFrac

Percent of the plot width range that will be used as the short dimension of the legend. Only applies to preset location options.

longFrac

Percent of the plot width range that will be used as the long dimension of the legend. Only applies to preset location options.

axisOffset

distance from color bar for labels, as a percent of the plot width.

border

logical, should the color legend have a black border

ramp

either a vector of color names that will be interpolated, or a color ramp function that takes an integer (see for example colorRampPalette). If omitted, defaults to default epm color palette.

isInteger

If auto, automatically determines if r is made up of integer values, otherwise TRUE or FALSE

ncolors

grain size of color ramp

breaks

If a custom set of color breaks were used in plotting r, pass those color breaks here. This overrides the minmax option.

minmax

min and max values from which the color ramp will be derived. If left as NULL, the min and max of r will be used.

locs

locations of tick marks, if NULL automatically placed. If this is supplied as a character vector, then the labels will be plotted verbatim.

label

text to plot alongside the legend

cex.axis

size of axis labels

tcl

length of tick marks (see help for tcl in ?par)

labelDist

distance from axis to axis labels (passed to mgp)

minDigits

minimum number of significant digits for labels

Details

A number of predefined locations exist in this function to make it easy to add a legend to a plot.

Preset locations are: topleft, topright, bottomleft, bottomright, left, right, top and bottom.
If more fine-tuned control is desired, then a numeric vector of length 4 can be supplied to location, specifying the min x, max x, min y and max y values for the legend.

Additionally, the adj argument can be used to more intuitively adjust where the legend is placed. adj is defined as a percentage of the figure width or height, left to right, or bottom to top, respectively. For example, if the legend is at the bottom, adj = 0.8 will place the legend 80% of the distance from the top of the figure, horizontally centered.

If an epmGrid object was plotted with plot.epmGrid, and if use_tmap = FALSE was specified, and if that plot was assigned to a variable, then you can supply that variable here to the params argument, and a number of options will be automatically handed over to this function.

See examples.

Value

Invisibly returns a list with the following components.

• coords: 2-column matrix of xy coordinates for each color bin in the legend.

• width: Coordinates for the short dimension of the legend.

• pal: the color ramp

• tickLocs: the tick mark locations in plotting units

Author(s)

Pascal Title

Examples

# create square-cell epmGrid object
tamiasEPM2 <- createEPMgrid(tamiasPolyList, resolution = 50000,
	cellType = 'square', method = 'centroid')

# need to disable tmap if we want to anything to a plot
plot(tamiasEPM2, use_tmap = FALSE, legend = FALSE)
addLegend(tamiasEPM2, location = 'right', label = 'richness')
addLegend(tamiasEPM2, location = 'top', label = 'richness')

# fine-tune placement
addLegend(tamiasEPM2, location=c(113281, 1265200, -1500000, -1401898), side = 1)

# Using the params option
xx <- plot(tamiasEPM2, use_tmap = FALSE, legend = FALSE, 
col = viridisLite::magma)
addLegend(tamiasEPM2, params = xx, location = 'top')

# works with hex grids as well
xx <- plot(tamiasEPM, use_tmap = FALSE, legend = FALSE, 
col = viridisLite::magma)
addLegend(tamiasEPM, params = xx, location = 'top')