# Draw a matrix of colored rectangles Draw a matrix of colored rectangles, possibly of varying sizes. ```r 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). ## Returns 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 ```r ## 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)) ```

cimage function