image-methods {Matrix} | R Documentation

## Methods for image() in Package 'Matrix'

### Description

Methods for function `image` in package Matrix. An image of a matrix simply color codes all matrix entries and draws the n x m matrix using an n x m grid of (colored) rectangles.

The Matrix package `image` methods are based on `levelplot()` from package lattice; hence these methods return an “object” of class `"trellis"`, producing a graphic when (auto-) `print()`ed.

### Usage

    ## S4 method for signature 'dgTMatrix'
    image(x,
          xlim = c(1, di[2]),
          ylim = c(di[1], 1), aspect = "iso",
          sub = sprintf("Dimensions: %d x %d", di[1], di[2]),
          xlab = "Column", ylab = "Row", cuts = 15,
          useRaster = FALSE,
          useAbs = NULL, colorkey = !useAbs,
          col.regions = NULL,
          lwd = NULL, border.col = NULL, ...)

### Arguments

`x` | a Matrix object, i.e., fulfilling `is(x, "Matrix")`.
`xlim, ylim` | x- and y-axis limits; may be used to “zoom into” matrix. Note that x,y “feel reversed”: `ylim` is for the rows (= 1st index) and `xlim` for the columns (= 2nd index). For convenience, when the limits are integer valued, they are both extended by `0.5`; also, `ylim` is always used decreasingly.
`aspect` | aspect ratio specified as number (y/x) or string; see `levelplot`.
`sub, xlab, ylab` | axis annotation with sensible defaults; see `plot.default`.
`cuts` | number of levels the range of matrix values would be divided into.

`useRaster`

logical indicating if raster graphics should be used (instead of the tradition rectangle vector drawing). If true, `panel.levelplot.raster` (from lattice package) is used, and the colorkey is also done via rasters, see also `levelplot` and possibly `grid.raster`.

Note that using raster graphics may often be faster, but can be slower, depending on the matrix dimensions and the graphics device (dimensions).

`useAbs` | logical indicating if `abs(x)` should be shown; if `TRUE`, the former (implicit) default, the default `col.regions` will be `grey` colors (and no `colorkey` drawn). The default is `FALSE` unless the matrix has no negative entries.
`colorkey` | logical indicating if a color key aka ‘legend’ should be produced. Default is to draw one, unless `useAbs` is true. You can also specify a `list`, see `levelplot`, such as`list(raster=TRUE)` in the case of rastering.
`col.regions` | vector of gradually varying colors; see `levelplot`.
`lwd` | (only used when `useRaster` is false:) non-negative number or `NULL` (default), specifying the line-width of the rectangles of each non-zero matrix entry (drawn by `grid.rect`). The default depends on the matrix dimension and the device size.
`border.col` | color for the border of each rectangle. `NA` means no border is drawn. When `NULL` as by default, `border.col <- if(lwd < .01) NA else NULL` is used. Consider using an opaque color instead of `NULL` which corresponds to `grid::get.gpar("col")`.
`...` | further arguments passed to methods and `levelplot`, notably `at` for specifying (possibly non equidistant) cut values for dividing the matrix values (superseding `cuts` above).

### Value

as all lattice graphics functions, `image(<Matrix>)` returns a `"trellis"` object, effectively the result of `levelplot()`.

### Methods

All methods currently end up calling the method for the `dgTMatrix` class. Use `showMethods(image)` to list them all.

### See Also

`levelplot`, and `print.trellis` from package lattice.

### Examples

    showMethods(image)
    ## If you want to see all the methods' implementations:
    showMethods(image, incl=TRUE, inherit=FALSE)

    data(CAex)
    image(CAex, main = "image(CAex)")
    image(CAex, useAbs=TRUE, main = "image(CAex, useAbs=TRUE)")

    cCA <- Cholesky(crossprod(CAex), Imult = .01)
    ## See  ?print.trellis --- place two image() plots side by side:
    print(image(cCA, main="Cholesky(crossprod(CAex), Imult = .01)"),
          split=c(x=1,y=1,nx=2, ny=1), more=TRUE)
    print(image(cCA, useAbs=TRUE),
          split=c(x=2,y=1,nx=2,ny=1))

    data(USCounties)
    image(USCounties)# huge
    image(sign(USCounties))## just the pattern
        # how the result looks, may depend heavily on
        # the device, screen resolution, antialiasing etc
        # e.g. x11(type="Xlib") may show very differently than cairo-based

    ## Drawing borders around each rectangle;
        # again, viewing depends very much on the device:
    image(USCounties[1:400,1:200], lwd=.1)
    ## Using (xlim,ylim) has advantage : matrix dimension and (col/row) indices:
    image(USCounties, c(1,200), c(1,400), lwd=.1)
    image(USCounties, c(1,300), c(1,200), lwd=.5 )
    image(USCounties, c(1,300), c(1,200), lwd=.01)
    ## These 3 are all equivalent :
    (I1 <- image(USCounties, c(1,100), c(1,100), useAbs=FALSE))
     I2 <- image(USCounties, c(1,100), c(1,100), useAbs=FALSE,        border.col=NA)
     I3 <- image(USCounties, c(1,100), c(1,100), useAbs=FALSE, lwd=2, border.col=NA)
    stopifnot(all.equal(I1, I2), all.equal(I2, I3))
    ## using an opaque border color
    image(USCounties, c(1,100), c(1,100), useAbs=FALSE, lwd=3, border.col = adjustcolor("skyblue", 1/2))

    if(doExtras <- interactive() || nzchar(Sys.getenv("R_MATRIX_CHECK_EXTRA")) ||
        identical("true", unname(Sys.getenv("R_PKG_CHECKING_doExtras")))) {
    ## Using raster graphics: For PDF this would give a 77 MB file,
    ## however, for such a large matrix, this is typically considerably
    ## *slower* (than vector graphics rectangles) in most cases :
    if(doPNG <- !dev.interactive())
       png("image-USCounties-raster.png", width=3200, height=3200)
    image(USCounties, useRaster = TRUE) # should not suffer from anti-aliasing
    if(doPNG)
       dev.off()
       ## and now look at the *.png image in a viewer you can easily zoom in and out
    }#only if(doExtras)

[Package Matrix version 1.2-17 Index]