colorgram {squash}

Draw a colorgram (heatmap) of a matrix

Description

Plot a visual representation of a numeric matrix using colors to indicate values.

Usage

colorgram(x = NULL, y = NULL, z = NULL, zsize = 1, 
          map, nz = 10, breaks = pretty, symm = FALSE, base = NA, colFn = jet,
          key = hkey, key.args = list(), 
          xlab = NULL, ylab = NULL, zlab = NULL, 
          outlier = NULL, ...) 

Arguments

x, y

Locations of grid lines at which the values in z are measured. These must be finite, non-missing and in (strictly) ascending order. (see Details below)

z

A numeric matrix containing the values to be visualized as colors (NAs are allowed). Note that x can be used instead of z for convenience.

zsize

A numeric matrix specifying the relative size of each rectangle.

map

A list, as generated by makecmap. If missing, a color map is generated automatically.

nz, breaks, symm, base, colFn

Arguments passed to makecmap, if map is missing.

key

A function to draw a color key, such as hkey or vkey.

key.args

Arguments passed to the function given by key.

xlab, ylab

Labels for axes.

zlab

Label (title) for the color key.

outlier

Color for values outside the map domain. If NULL, values falling outside the map domain will generate an error.

...

Further arguments passed to cimage.

Details

This function assigns colors to the elements of a matrix and plots it using cimage.

Data can be passed to this function in any format recognized by xyzmat.coords.

colorgram is somewhat similar to image. However, colorgram adds the following functionality: 1. The value-to-color mapping can be specified (thus allowing unequal bin sizes). 2. A color key can be added, optionally. 3. A color can be specified for missing values. 4. The size of each grid rectangle can be adjusted to convey additional information.

Two color key functions are provided in the squash package: 1) hkey draws a horizontal key, in the lower-left corner by default. 2) vkey) draws a vertical key, in the lower-right corner by default. The latter usually looks better if the right-hand margin is increased. These keys can be controlled somewhat using key.args. However, that title and map cannot be specified in key.args; use the zlab and map arguments instead.

Value

Invisibly, map.

See Also

If this is not quite what you are looking for, consider image, filled.contour, or levelplot. Also color2D.matplot in the plotrix package.

Examples

  ## median Petal.Length as function of Sepal.Length and Sepal.Width
  pl <- matapply( iris[,1:3], FUN = median, nx = 20, ny = 15 )

  ## Draw a colorgram with the default horizontal color key  
  colorgram(pl, main = 'iris')

  ## ... or with the vertical color key  
  colorgram(pl, main = 'iris', key = vkey)

  ## ... add margin space to improve legibility 
  op <- par(mar = c(5,4,4,4)+0.1)
  colorgram(pl, main = 'iris', key = vkey, 
    key.args = list(skip = 2), zlab = 'Petal\nlength')
  par(op)
  
  ##  Here is the example from the base function "persp"
  x <- seq(-10, 10, length= 30)
  y <- x
  f <- function(x,y) { r <- sqrt(x^2+y^2); 10 * sin(r)/(r) }
  z <- outer(x, y, f)
  colorgram(x, y, z)

  ## ... and with a slight fix to the key:
  colorgram(x, y, z, key.args = list(wh = c(1, 4, 14)))

  ## We could also make more space for the key:
  op <- par(mar = c(7,4,4,2)+0.1)
  colorgram(x, y, z, key.args = list(stretch = 3))
  par(op)
  
  ## Here are some alternatives to colorgram  
  persp(x, y, z, theta = 30, phi = 30, expand = 0.5, col = "lightblue")
  image(x, y, z)  
  contour(x, y, z)

  ## Use 'xlabels' and 'ylabels' to create categorical axes
  colorgram(t(mtcars[,c(2,8:11)]), colFn = heat, 
    xlabels = TRUE, ylabels = TRUE, 
    xlab = NA, ylab = NA, zlab = 'Value', 
    main = 'Motor car specifications', las = 1)