sisalTable: Draw Table with Equally Sized Cells

Description Usage Arguments Details Value Author(s) Examples

View source: R/sisalTable.R

Description

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.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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)

Arguments

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.

Details

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:

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.

Value

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".

Author(s)

Mikko Korpela

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
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")

sisal documentation built on May 29, 2017, 9:09 a.m.