cimage: Draw a matrix of colored rectangles

In aroneklund/squash: Color-Based Plots for Multivariate Visualization

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

aroneklund/squash documentation built on June 3, 2023, 11:55 a.m.