sisalTable: Draw Table with Equally Sized Cells
In sisal: Sequential Input Selection Algorithm

Description Usage Arguments Details Value Author(s) Examples

Draws a resizable or fixed-size table with equally sized cells. Main title, axis (tick) labels and axis titles (left, bottom) are optional. Cells can have individual background and text colors and stripes.

sisalTable(labels = matrix(seq_len(12), 3, 4),
           nRows = NROW(labels), nCols = NCOL(labels),
           bg = sample(colors(), nRows * nCols, replace = TRUE),
           stripeCol = NULL, fg = NULL, naFill = "white",
           naStripes = "grey50", main = NULL, xlab = NULL,
           ylab = NULL, xAxisLabels = NULL, yAxisLabels = NULL,
           draw = TRUE, outerRect = TRUE, innerLines = TRUE,
           nStripes = 7, stripeRot = 45, stripeWidth = 0.2,
           stripeScale = 0.95, resizeText = TRUE,
           resizeTable = TRUE, resizeMain = resizeText,
           resizeLab = resizeText, resizeAxes = resizeText,
           resizeLabels = resizeTable && resizeText,
           x = unit(0.5, "npc"), y = unit(0.5, "npc"),
           width = unit(0.97, "npc"), height = unit(0.97, "npc"),
           default.units = "npc", just = "center",
           clip = "inherit", xAxisRot = 0, yAxisRot = 0,
           xAxisJust = c(0.5, 1), xAxisX = 0.5, xAxisY = 1,
           yAxisJust = c(1, 0.5), yAxisX = 1, yAxisY = 0.5,
           mainMargin = if (resizeMain) 0.15 else unit(8, "points"),
           xlabMargin = if (resizeLab) 0.1 else unit(5, "points"),
           ylabMargin = if (resizeLab) 0.1 else unit(5, "points"),
           axesMargin = if (resizeAxes) 0.1 else unit(5, "points"),
           axesSize = 0.8, forceAxesSize = FALSE,
           mainSize = 1, xlabSize = 1, ylabSize = 1,
           mainPar = gpar(fontface = "bold", fontsize = 14),
           labPar = gpar(fontface = "plain", fontsize = 14),
           labelPars = gpar(fontsize = 20, cex = 0.6),
           axesPar = gpar(fontsize = 10),
           rectPar = gpar(), linePar = gpar(),
           name = NULL, gp = NULL, vp = NULL)

`labels`	the labels to use in the table cells. A `list` or an `atomic` `vector` containing something that can be displayed as text, e.g. `character` values. One element is used for each cell. If the object has a `"dim"` attribute (`matrix`, `array`), it is used for determining the number of rows and columns in the table. `NA` means no text.
`nRows`	the number of rows in the table. A positive integral number.
`nCols`	the number of columns in the table. A positive integral number.
`bg`	the background colors of the table cells. One element is used for each cell.
`stripeCol`	an optional `vector` of colors. If used, indicates the color of stripes to be painted on top of the background color in each table cell. One element is used for each table cell. `NA` means no stripes.
`fg`	the text colors of the table cells. One element is used for each cell. If `NULL` (the default), black or white text is used so that the contrast between foreground and background is maximized.
`naFill`	background color to use when the label of a table cell is `NA`. This is a single color value.
`naStripes`	table cells with an `NA` label are indicated with stripes. This is the color of the stripes, a single color value. The stripes can be hidden by using a value identical with that of `naFill`.
`main`	the main title of the plot.
`xlab`	a title for the x axis.
`ylab`	a title for the y axis.
`xAxisLabels`	a label for each column of the table.
`yAxisLabels`	a label for each row of the table.
`draw`	a `logical` flag indicating whether to draw the table. If `FALSE`, no drawing is done.
`outerRect`	a `logical` flag indicating whether a rectangle will be drawn around the table.
`innerLines`	a `logical` flag indicating whether line segments will be drawn between the table cells.
`nStripes`	a positive integral number giving the number of stripes to be drawn in table cells. Only applies to those cells where stripes are used, i.e. when the relevant element of `label` is `NA` or `stripeCol` is not `NA`. The stripes are spaced evenly. Defaults to `7`.
`stripeRot`	an integral number giving the rotation angle (degrees, counterclockwise) of the stripes used in table cells. Defaults to `45` which means diagonal stripes parallel to a line segment between the lower left corner and the upper right corner of the cell. Value `0` means horizontal and `90` vertical stripes.
`stripeWidth`	a `numerical` value giving the width of the stripes used in cells as a proportion of the available width. Values between `0` and `1` are allowed, excluding the endpoints. Defaults to `0.2`.
`stripeScale`	a `numerical` value indicating the proportion of the area of a table cell to be used for the stripe pattern. The pattern is always centered, and the possible empty space is left on the borders of the cell. Values between `0` and `1` are allowed, including the endpoints. Defaults to `0.95`.
`resizeText`	a `logical` flag indicating whether to use dynamic text size. This is only used as the default value of `resizeMain`, `resizeLab`, `resizeLabels` and `resizeAxes`. Defaults to `TRUE`.
`resizeTable`	a `logical` flag indicating whether the size of the table will depend on the size of the main `viewport`, which itself may be static or depend on the size of the graphical device. Defaults to `TRUE`. See ‘Details’.
`resizeMain`	a `logical` flag indicating whether the main title will be resizable.
`resizeLab`	a `logical` flag indicating whether the the x axis and y axis titles will be resizable.
`resizeLabels`	a `logical` flag indicating whether the labels used in the table cells will be resizable.
`resizeAxes`	a `logical` flag indicating whether the row and column labels will be resizable.
`x`	a `numeric` vector or `unit` object of length one specifying the x location of the graphical object.
`y`	a `numeric` vector or `unit` object of length one specifying the y location of the graphical object.
`width`	a `numeric` vector or `unit` object of length one specifying the width of the graphical object. See ‘Details’.
`height`	a `numeric` vector or `unit` object of length one specifying the height of the graphical object. See ‘Details’.
`default.units`	a `character` string indicating the `unit` to use for `numeric` values of `x`, `y`, `width` and `height`.
`just`	a `character` or `numeric` vector of one or two values specifying the justification of the graphical object relative to its (x, y) location. See `viewport`.
`clip`	a `character` string specifying what to do if the graphical object overflows the `viewport` reserved for it. See ‘Details’.
`xAxisRot`	a `numeric` value giving the rotation angle of the column labels in degrees.
`yAxisRot`	a `numeric` value giving the rotation angle of the row labels in degrees.
`xAxisJust`	justification setting for column labels. A `numeric` or `character` vector. Rotation (if any) will be done before justification. See `just` in `textGrob` for possible values.
`xAxisX`	x location of column labels relative to the space allocated for them. A `numeric` value where `0` means left and `1` right.
`xAxisY`	y location of column labels relative to the space allocated for them. A `numeric` value where `0` means bottom and `1` top.
`yAxisJust`	justification setting for row labels. A `numeric` or `character` vector. See `xAxisJust`.
`yAxisX`	x location of row labels relative to the space allocated for them. A `numeric` value where `0` means left and `1` right.
`yAxisY`	y location of row labels relative to the space allocated for them. A `numeric` value where `0` means bottom and `1` top.
`mainMargin`	size of the margin between the main title and the table.
`xlabMargin`	size of the margin between the x axis title and the next graphical object towards the table.
`ylabMargin`	size of the margin between the y axis title and the next graphical object towards the table.
`axesMargin`	size of the margin between the row or column labels and the table.
`axesSize`	a positive `numeric` value specifying the desired ratio of fontsize in row and column labels to fontsize in table cells.
`forceAxesSize`	a `logical` flag. If `TRUE`, the function will reduce the size of text in table cells if it is necessary in order to achieve the desired `axesSize`.
`mainSize`	scale factor for fontsize of main title. A positive `numeric` value. Only effective when `resizeMain` is `TRUE`.
`xlabSize`	scale factor for fontsize of x axis title. A positive `numeric` value. Only effective when `resizeLab` is `TRUE`.
`ylabSize`	scale factor for fontsize of y axis title. A positive `numeric` value. Only effective when `resizeLab` is `TRUE`.
`mainPar`	graphical parameters for the main title.
`labPar`	graphical parameters for x and y axis titles.
`labelPars`	graphical parameters for labels used in table cells. Can also be a list, one element for each table cell, recycled if necessary.
`axesPar`	graphical parameters for row and column labels.
`rectPar`	graphical parameters for the rectangle around the table.
`linePar`	graphical parameters for the line segments between table cells.
`name`	a `character` string identifier for the graphical object returned by the function. If `NULL` (the default), a name will be assigned automatically.
`gp`	graphical parameters for the whole object.
`vp`	a `"viewport"` object, the name of a viewport object, a `vpPath` object pointing to a viewport or `NULL` (the default). If not `NULL`, this graphical object will be drawn in the given viewport. The name or the path must point to a descendant of the current viewport. See `current.vpPath`, `current.vpTree`, `downViewport` and `grid.draw`.

This function was written to be used with plotSelected but it should be generic enough to be useful for other purposes, too.

The color and text vectors (including matrices and arrays) pointing to table cells (labels, bg, stripeCol, fg) are interpreted in column-major order, like linear indexing of a matrix. Each data.frame argument is collapsed to a list by combining its columns. Finally, values are recycled if needed, also in xAxisLabels and yAxisLabels.

For possible color values, see col2rgb.

In the various text objects, mathematical annotation (see plotmath) is supported in addition to character values.

For information on setting graphical parameters (gp, mainPar, labPar, ...), see gpar.

The graphical object returned is a gTree which contains a gList of graphical objects and a vpTree of viewports. The child viewports are placed inside the parent using a grid.layout. The size of the whole object is the size of the parent viewport. It will be fixed or depend on the space available to it:

If all graphical elements are non-resizable (but resizeLabels can be TRUE), a suitable fixed size will be computed.
Otherwise, the size is determined by width and height. However, if there are non-resizable elements, the graphical object may be larger than that.

The graphical object will not use any excess space. In other words, the width and height reported by grobWidth and grobHeight are tight. It is possible that some parts of the plot may overflow their assigned space and the bounds computed for the whole graphical object. Examples include using large fixed-size text elements or large values of the gpar graphical parameter "cex". Clipping can be adjusted through clip.

If resizeAxes is TRUE, axesMargin must be a non-negative numeric value giving the size of the margin as a proportion of the side length of a table cell. If resizeAxes is FALSE, axesMargin can also be a unit object. The arguments mainMargin and labMargin are analogous to axesMargin.

The function is usually called for the side effect (a plot is drawn), but it also returns a grob representation of the plot. The returned object is a custom gTree of class "sisalTable".

Mikko Korpela

library(grDevices)
library(grid)
## Default: 3 by 4 table with labels 1:12 and random background colors
grid.newpage()
sisalTable()

## Four examples in a grid layout
rowCol <- c(1, 18, 2, 18, 1)
lo <- grid.layout(nrow = 5, ncol = 5,
                  widths = rowCol, heights = rowCol)
grid.newpage()
pushViewport(viewport(layout = lo, name = "bgLayout"))
grid.rect(gp=gpar(fill="grey75", col="grey75"))

rNames <- c("topmargin", "top", "hspace", "bottom", "bottommargin")
cNames <- c("leftmargin", "left", "vspace", "right", "rightmargin")
for (Row in c(2, 4)) {
    for (Col in c(2, 4)) {
        pushViewport(viewport(layout.pos.row = Row,
                              layout.pos.col = Col,
                              name = paste(rNames[Row],
                                           cNames[Col], sep="")))
        grid.rect(gp=gpar(fill="cadetblue"))
        upViewport(1)
    }
}

colors1Vec <- terrain.colors(12)
colors1Mat <- matrix(colors1Vec, 3, 4)
labels1Vec <- sample(c(letters, LETTERS), 12)
labels1Mat <- matrix(labels1Vec, 3, 4)

## Column vector, aligned with the right side of the viewport
longText <- rep("", 12)
longText[3] <- "a longish piece of text"
longText[9] <- "and some more"
sisalTable(labels1Vec, bg = colors1Vec, vp = "topleft",
           x = 1, just = "right",
           yAxisLabels = longText, xAxisLabels = "Boo")

## Matrix, zero margin
downViewport("topright")
sisalTable(labels1Mat, bg = colors1Mat,
           width = 1, height = 1, name = "trPlot",
           xAxisLabels = 1:4, yAxisLabels = LETTERS[1:3])
grid.rect(width = grobWidth("trPlot"), height = grobHeight("trPlot"),
          gp = gpar(lty="dashed", col = "white", lwd = 2))
upViewport(1)

## Transpose of matrix, width and height 0.75 "npc" units
downViewport("bottomleft")
sisalTable(t(labels1Mat), bg = t(colors1Mat),
           width = 0.75, height = 0.75, name = "blPlot",
           yAxisLabels = 1:4, xAxisLabels = LETTERS[1:3])
grid.rect(width = grobWidth("blPlot"), height = grobHeight("blPlot"),
          gp = gpar(lty="dashed", col = "white", lwd = 2))
upViewport(1)

## ?plotmath, some cells with no background color
labels2 <- expression(x^{y+x}, sqrt(x), bolditalic(x), NA)
bgCol <- c(rep("white", 3), NA)
sisalTable(labels2, nRows=3, nCols=5, bg = bgCol, naFill = NA,
           naStripes = "darkmagenta", vp="bottomright",
           main = "plotmath text")