rangeBuilder (version 1.6)

addRasterLegend: addRasterLegend

Description

Adds a legend to an existing raster plot, with some additional manual control

Usage

addRasterLegend(
  r,
  direction,
  side,
  location = "right",
  nTicks = 2,
  adj = NULL,
  shortFrac = 0.02,
  longFrac = 0.3,
  axisOffset = 0,
  border = TRUE,
  ramp = "terrain",
  isInteger = "auto",
  ncolors = 64,
  breaks = NULL,
  minmax = NULL,
  locs = NULL,
  cex.axis = 0.8,
  labelDist = 0.7,
  digits = 2,
  bigmark = "",
  ...
)

Value

Invisibly returns a list with the following components.

• coords2-column matrix of xy coordinates for each color bin in the legend.

• widthCoordinates for the short dimension of the legend.

• palthe color ramp

• tickLocsthe tick mark locations in plotting units

• labelsthe values associated with those tick locations.

Arguments

r

the rasterLayer object that has been plotted

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 dimention of the legend. Only applies to preset location options.

longFrac

Percent of the plot width range that will be used as the long dimention 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 for defining the color ramp, or "terrain" (default raster behavior)

isInteger

If auto, automatically determines if raster 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 the raster, 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 the raster will be used.

locs

locations of tick marks, if NULL automatically placed

cex.axis

size of axis labels

labelDist

distance from axis to axis labels (passed to mgp)

digits

number of decimal places for labels

bigmark

character used to separate thousands and millions, passed to format

...

additional parameters to be passed to axis.

Author

Pascal Title

Details

A number of predefined locations exist in this function to make it easy to add a legend to a raster 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 the figure, horizontally centered. See examples.

Examples

library(raster)
r <- raster(system.file("external/test.grd", package="raster"))

plot(r, legend = FALSE)
addRasterLegend(r, location = 'right')
addRasterLegend(r, location = 'top')

# fine-tune placement
plot(r, legend = FALSE)
addRasterLegend(r, location=c(181000, 181100, 330500, 331500), side = 4)