R: Draw a matrix of colored rectangles

cimage {squash} | R Documentation

## Draw a matrix of colored rectangles

### Description

Draw a matrix of colored rectangles, possibly of varying sizes.

### Usage

    cimage(x = NULL, y = NULL, zcol = NULL, zsize = 1,
           xlab = NULL, ylab = NULL, xlabels = NULL, ylabels = NULL,
           border = NA, add = FALSE, axes = TRUE, useRaster = FALSE, ...)

### Arguments

`x` | Vector of rectangle midpoints or breakpoints along X-axis (corresponding to the columns of zcol).
`y` | Vector of rectangle midpoints or breakpoints along Y-axis (corresponding to the rows of zcol).
`zcol` | Matrix of colors for each rectangle, e.g. RGB values or integer indices.
`zsize` | Relative size for each rectangle, ranging from 0 to 1. Will be recycled if necessary.
`xlab, ylab` | Labels for the axes.
`xlabels, ylabels` | Categorical labels for rows/columns.
`border` | Color for rectangle borders.
`add` | Add to the current plot instead of creating a new one?
`axes` | Draw axes on the plot?
`useRaster` | TRUE = draw a true raster image (using `rasterImage`). FALSE = draw a series of individual rectangles.
`...` | Further arguments passed to `plot`.

### Details

Data (`x`, `y`, and `zcol`) can be passed to this function in any format recognized by `xyzmat.coords`.

This function is somewhat similar to the function `image`, except that the colors are specified explicitly, and the size of each rectangle can be adjusted.

If `xlabels` is `NULL` (the default), standard numeric axes are drawn on the X-axis. If `xlabels` is `TRUE`, the rownames of `zcol` are placed below each column. Otherwise, `xlabels` is taken as a vector of labels to be placed below each column. Likewise for `ylabels` and the Y-axis.

Using `useRaster=TRUE` can reduce the file size for large matrices drawn to vector-based graphics output such as PDFs. However, the output may look strange with smaller matrices on graphics devices that do smoothing by default (such as PDF output viewed in Preview).

### Value

None.

### Note

Currently, this function will may not behave as expected if the `x` and/or `y` values are specified as midpoints and are not evenly spaced.

### See Also

`image` and `rasterImage` provide somewhat similar functionality.

This function is called by `colorgram`, which accepts a numeric (rather than color) matrix as input.

The package pixmap may be more suitable for plotting images that are not data-driven (e.g. external files).

### Examples

      ## Visualize nearly all built-in R colors
      color.mat <- matrix(colors()[1:625], nrow = 25)
      cimage(zcol = color.mat)

      ## An example using "zsize"
      x <- y <- 1:10
      zcolor <- matrix( rainbow(100)[outer(x, y)], nrow = 10 )
      zsize <- matrix( runif(100), nrow = 10 )
      cimage(x, y, zcol = zcolor, zsize = zsize)

      ## Another simple example
      red <- green <- 0:255
      rg <- outer(red, green, rgb, blue = 1, maxColorValue = 255)
      cimage(red, green, zcol = rg)

      ## The same, but using useRaster (resulting in faster image generation,
      ## and smaller file size if saved as a PDF)
      cimage(red, green, zcol = rg, useRaster = TRUE)

      ## An example with categorical axes
      colormixer <- function(x, y) {
          r <- (col2rgb(x) + col2rgb(y)) / 2
          rgb(as.data.frame(t(r)), maxColorValue = 255)
      }
      set.seed(123)
      x <- sample(colors(), 15)
      y <- sample(colors(), 10)
      mix <- outer(x, y, colormixer)
      op <- par(mar = c(8, 8, 2, 2), las = 2)
      cimage(zcol = mix, xlabels = x, ylabels = y, xlab = NA, ylab = NA)
      par(op)

      ## An example with non-uniform midpoints and breakpoints
      rg2 <- rg[seq(1, 255, by = 62), seq(1, 255, by = 62)]
      cimage(x = (1:5)^2, y = c(3, 5, 6, 9, 10, 11), zcol = rg2,
             zsize = matrix(runif(25, min = 0.5), nrow = 5))

[Package squash version 1.0.8 Index]