R: Draw a colorgram (heatmap) of a matrix

colorgram {squash} | R Documentation

## 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)

[Package squash version 1.0.8 Index]