colorbar: Draw a Colour Bar

View source: R/colorbar.R

colorbarR Documentation

Draw a Colour Bar

Description

Draws a colour bar on a plot.

Since R does not use dynamic graphical objects, i.e. graphical objects cannot be modified after they are plotted, the user cannot call the colorbar function and expect an existing plot to adjust its layout in accordance. Thus, the intended use is that the colorbar function be called prior to rather than after plotting.

Usage

colorbar(
  levels,
  labels,
  colors = "black",
  caption,
  label.cex = 0.8,
  caption.cex = 0.8,
  width = 0.2,
  height = 1,
  pos = 4,
  nlevels = 5,
  range = c(0, 1),
  box,
  border,
  border.col = "black",
  aspect.adjust = TRUE,
  insert = TRUE,
  smooth = FALSE,
  bar.width = 0.25,
  bar.height = 0.75,
  plus.category = FALSE,
  horizontal = FALSE,
  add = FALSE,
  ...
)

Arguments

levels

Character or numerical vector specifying labels or level values used to delimit color bar categories.

labels

Character strings specifying the labels of the color bar categories. The number of elements is one less than the number of numerical elements in levels, or an equal number if levels is categorical.

colors

Vector of color definitions. If the number of colors is not equal to or one less than the number of levels, then the specified colors are interpolated to generate a color vector of appropriate length.

caption

Caption for the color bar.

label.cex

Text size of the labels.

caption.cex

Text size of the caption.

width

Numeric value between zero and one specifying the proportion of the width of the plotting axes to be taken up by the axes of the color bar. The default is 0.2. If horizontal = TRUE then the width and height arguments are exchanged.

height

Numeric value between zero and one specifying the proportion of the height of the plotting axes to be taken up by the axes of the color bar. The default is 1. If horizontal = TRUE then the width and height arguments are interchanged.

pos

An integer specifying whether to plot the colorbar at the bottom (= 1), left (= 2), top (= 3) to the right (= 4) of the plotting axes.

nlevels

An integer specifying then number of desired levels if levels cannot be determined from other parameters.

range

A two-element numeric vector specifying the desired range of levels if it cannot be determined from other parameters.

box

Logical value specifying whether to draw a bounding box about the colorbar axes. Alternatively, the color of the box may be given. The default value is FALSE.

border

Logical value specifying whether to draw a bounding rectangle around the entire color bar. The default is FALSE.

border.col

A character value specifying the color of the bounding rectangle around the color bar. The default is ‘black’.

aspect.adjust

Logical value specifying whether the dimensions of both the color bar and graph plotting area are to be adjusted in such a way as the aspect ratio of the plotting axes is conserved. The height of the color bar axes and the plotting axes are also set to be equal. This is only applied if insert = TRUE. The default value is TRUE.

insert

Logical value specifying whether the color bar axes are to be inserted, i.e. a space is created adjacent to, the present plotting axes. The default is TRUE.

smooth

Logical value wspecifying whether the color bar is a continuum of interpolated colors rather than a discrete set of colored rectangles. The default is FALSE.

plus.category

Logical value specifying whether to include a plus category if the labels are numeric. The default is FALSE.

horizontal

Logical value specifying whether the color bar is to be drawn horizontally rather than vertically. The default is FALSE.

add

Logical value specifying whether the color bar is to be drawn in the present plot rather than a new one. The default is FALSE.

bar.width.bar.height

Numeric values specifying the proportion of the color axes to be taken by the width and height of the color bar. The default is 0.25.

list()

Further arguments passed onto colorbar sub-functions.

See Also

filled.contour

Examples

# Default colour bar:
colorbar()

# Categorical colour bar:
dev.new()
colorbar(c("Low", "Medium", "High", "Extreme"),
         color = c("yellow", "blue", "white", "red"),
         caption = c("Caption", "Text"), border = TRUE)

# Display continuous color bar:
dev.new()
colorbar(seq(0, 20, by = 4), color = c("blue", "yellow", "red"),
         caption = c("Temperature", "(Celsius)"), smooth = TRUE)

# Volcano elevation example using 'image':
dev.new()
levels <- seq(90, 200, by = 5)
colors <- terrain.colors(length(levels)-1)
colorbar(levels, col = colors, caption = c("Elevation", "(meters)"), label.cex = 0.7, smooth = TRUE)
image(x = seq(0, 1, len = dim(volcano)[1]),
      y = seq(0, 1, len = dim(volcano)[2]),
      z = volcano,
      zlim = c(min(levels), max(levels)),
      col = colors, xlab = "x", ylab = "y")
box()

# Volcano elevation example using '.filled.contour':
dev.new()
levels <- seq(90, 200, by = 5)
colors <- terrain.colors(length(levels)-1)
colorbar(levels, col = colors, caption = c("Elevation", "(meters)"), label.cex = 0.7)
plot.new() # Seems to require this step, not sure why.
graphics::.filled.contour(x = seq(0, 1, len = dim(volcano)[1]),
                          y = seq(0, 1, len = dim(volcano)[2]),
                          z = volcano,
                          levels = levels, col = colors)
box()

TobieSurette/gulf.graphics documentation built on Feb. 10, 2024, 10:58 p.m.