The grid package provides low-level functions to create graphical objects (grobs), and position them on a page in specific viewports. The gtable package introduced a higher-level layout scheme, arguably more amenable to user-level interaction. With the arrangeGrob/grid.arrange() pair of functions, gridExtra builds upon gtable to arrange multiple grobs on a page.
In this example we mix a few grobs and plots,
library(gridExtra)
library(grid)
library(ggplot2)
library(lattice)
p <- qplot(1,1)
p2 <- xyplot(1~1)
r <- rectGrob(gp=gpar(fill="grey90"))
t <- textGrob("text")
grid.arrange(t, p, p2, r, ncol=2)
gs <- lapply(1:9, function(ii)
grobTree(rectGrob(gp=gpar(fill=ii, alpha=0.5)), textGrob(ii)))
grid.arrange(grobs=gs, ncol=4,
top="top label", bottom="bottom\nlabel",
left="left label", right="right label")
grid.rect(gp=gpar(fill=NA))
We can provide a matrix defining the layout,
lay <- rbind(c(1,1,1,2,3),
c(1,1,1,4,5),
c(6,7,8,9,9))
grid.arrange(grobs = gs, layout_matrix = lay)
The layout itself may contain holes, but note that for any given grob index the region must be simply connected (no hole),
hlay <- rbind(c(1,1,NA,2,3),
c(1,1,NA,4,NA),
c(NA,7,8,9,NA))
select_grobs <- function(lay) {
id <- unique(c(t(lay)))
id[!is.na(id)]
}
grid.arrange(grobs=gs[select_grobs(hlay)], layout_matrix=hlay)
All cells are of equal size by default, but users may pass explicity widths and/or heights in any valid grid units, or as relative numbers (interpreted as null),
grid.arrange(grobs=gs[1:3], ncol=2, widths = 1:2,
heights=unit(c(1,10), c("in", "mm")))
arrangeGrobThe grid.arrange() function draws on the device; for more complex layouts, we may want to store the gtable and combine it with other objects, e.g. forming nested layouts. To this end, use arrangeGrob(),
g1 <- arrangeGrob(grobs = gs, layout_matrix = t(lay))
g2 <- arrangeGrob(grobs = gs, layout_matrix = lay)
grid.arrange(g1, g2, ncol=2)
Finally, we may want to place grobs on multiple pages; the marrangeGrob() function provides a convenient interface for this, also compatible with ggsave().
set.seed(123)
pl <- lapply(1:11, function(.x)
qplot(1:10, rnorm(10), main=paste("plot", .x)))
ml <- marrangeGrob(pl, nrow=2, ncol=2)
## non-interactive use, multipage pdf
## ggsave("multipage.pdf", ml)
## interactive use; calling `dev.new` multiple times
ml
Tabular data is usually formatted outside the graphics device, e.g via LaTeX, or html tables. However, in some cases it may be convenient to display small tables alongside graphics. A couple of packages offer this possibility with base graphics (plotrix for instance); the gridExtra provides the pair of tableGrob/grid.table functions for this purpose.
Note: This vignette uses the development version of gridExtra, some features may not be yet available in the released version.
library(gridExtra)
library(grid)
d <- head(iris[,1:3])
grid.table(d)
The spacing of each row/column is automatic, and will adjust to bigger cell contents. Plotmath notation may be used, with the parse=TRUE argument. Note that this is applied to individual strings of text, and reverts to standard text if parsing fails (this is useful when mixing multiline text with plotmath in different cells).
d[2,3] <- "this is very wwwwwide"
d[1,2] <- "this\nis\ntall"
colnames(d) <- c("alpha*integral(xdx,a,infinity)",
"this text\nis high", 'alpha/beta')
tt <- ttheme_default(colhead=list(fg_params = list(parse=TRUE)))
grid.table(d, theme=tt)
The formatting is controlled by themes, which are nested lists of graphical parameters. See ttheme_default and ttheme_minimal for two built-in examples. Changing a few parameters at a time amounts to modifying the list with the new values.
tt1 <- ttheme_default()
tt2 <- ttheme_minimal()
tt3 <- ttheme_minimal(
core=list(bg_params = list(fill = blues9[1:4], col=NA),
fg_params=list(fontface=3)),
colhead=list(fg_params=list(col="navyblue", fontface=4L)),
rowhead=list(fg_params=list(col="orange", fontface=3L)))
grid.arrange(
tableGrob(iris[1:4, 1:2], theme=tt1),
tableGrob(iris[1:4, 1:2], theme=tt2),
tableGrob(iris[1:4, 1:2], theme=tt3),
nrow=1)
If the formatting values are fewer than the number of cells, they are recycled along columns,
t1 <- ttheme_default(core=list(
fg_params=list(fontface=c(rep("plain", 4), "bold.italic")),
bg_params = list(fill=c(rep(c("grey95", "grey90"),
length.out=4), "#6BAED6"),
alpha = rep(c(1,0.5), each=5))
))
grid.table(iris[1:5, 1:3], theme = t1)
The text labels can be justified; the default is “centre†for the core and header, and “right†for the row names. These settings can be adjusted by passing the relevant parameters of textGrob via the theme nested lists,
tt1 <- ttheme_default()
tt2 <- ttheme_default(core=list(fg_params=list(hjust=1, x=0.9)),
rowhead=list(fg_params=list(hjust=1, x=0.95)))
tt3 <- ttheme_default(core=list(fg_params=list(hjust=0, x=0.1)),
rowhead=list(fg_params=list(hjust=0, x=0)))
grid.arrange(
tableGrob(mtcars[1:4, 1:2], theme=tt1),
tableGrob(mtcars[1:4, 1:2], theme=tt2),
tableGrob(mtcars[1:4, 1:2], theme=tt3),
nrow=1)
Being based on gtable, the table can be further processed. In particular, we may edit the cell sizes to align with other content on the page.
g <- g2 <- tableGrob(iris[1:4, 1:3], cols = NULL, rows=NULL)
g2$widths <- unit(rep(1/ncol(g2), ncol(g2)), "npc")
grid.arrange(rectGrob(), rectGrob(), nrow=1)
grid.arrange(g, g2, nrow=1, newpage = FALSE)
The alignment of several tables can be achieved with the combine function (adapted from gtable:::join),
d1 <- PlantGrowth[1:3,1, drop=FALSE]
d2 <- PlantGrowth[1:2,1:2]
g1 <- tableGrob(d1)
g2 <- tableGrob(d2)
haligned <- combine(g1,g2, along=1)
valigned <- combine(g1,g2, along=2)
grid.newpage()
grid.arrange(haligned, valigned, ncol=2)
Other grobs such as separating lines and rectangles (borders, boxes) may be added. In this case, keep in mind that row, column and cell numbering includes the column of row labels and the row of column labels if they are present. Let us illustrate this by adding some borders (using rectGrob) to a simple table without row numbers. We’ll add two actually, to give a nice effect of a heavy line under the row of column headers.
library(gtable)
g <- tableGrob(iris[1:4, 1:3], rows = NULL)
g <- gtable_add_grob(g,
grobs = rectGrob(gp = gpar(fill = NA, lwd = 2)),
t = 2, b = nrow(g), l = 1, r = ncol(g))
g <- gtable_add_grob(g,
grobs = rectGrob(gp = gpar(fill = NA, lwd = 2)),
t = 1, l = 1, r = ncol(g))
grid.draw(g)
Note that when using rectGrob the top, bottom, left and right arguments (t, b, l, r) are the rows and columns which will be inside the rectangle. If we repeat the above code almost exactly, but don’t suppress the column of row labels, we see that column 1 is now the column of row labels (and it doesn’t look that good either, but that’s not our point).
g <- tableGrob(iris[1:4, 1:3])
g <- gtable_add_grob(g,
grobs = rectGrob(gp = gpar(fill = NA, lwd = 2)),
t = 2, b = nrow(g), l = 1, r = ncol(g))
g <- gtable_add_grob(g,
grobs = rectGrob(gp = gpar(fill = NA, lwd = 2)),
t = 1, l = 1, r = ncol(g))
grid.draw(g)
When adding line segments to separate rows and columns using segmentsGrob, the row and column numbering scheme is the same (it includes any row or column labels). When working with line segments, you should keep in mind the default coordinate values for segmentsGrob. They are x0 = 0, y0 = 0, x1 = 1, y1 = 1, all in npc, relative to the cell(s) you are modifying, with the lower left corner being 0,0. For clarity, we show all the arguments in these examples. With this in mind, to add a line across the bottom of a single cell, use:
g <- tableGrob(iris[1:4, 1:3])
g <- gtable_add_grob(g,
grobs = segmentsGrob( # line across the bottom
x0 = unit(0,"npc"),
y0 = unit(0,"npc"),
x1 = unit(1,"npc"),
y1 = unit(0,"npc"),
gp = gpar(lwd = 2.0)),
t = 3, b = 3, l = 3, r = 3)
grid.draw(g)
and to add a line to the left side:
g <- tableGrob(iris[1:4, 1:3])
g <- gtable_add_grob(g,
grobs = segmentsGrob( # line across the bottom
x0 = unit(0,"npc"),
y0 = unit(0,"npc"),
x1 = unit(0,"npc"),
y1 = unit(1,"npc"),
gp = gpar(lwd = 2.0)),
t = 3, b = 3, l = 3, r = 3)
grid.draw(g)
Perhaps you’d like to cross out a cell. This can be done with two diagonal lines combined via a grobTree:
g <- tableGrob(iris[1:4, 1:3])
g <- gtable_add_grob(g,
grobs = grobTree(
segmentsGrob( # diagonal line ul -> lr
x0 = unit(0,"npc"),
y0 = unit(1,"npc"),
x1 = unit(1,"npc"),
y1 = unit(0,"npc"),
gp = gpar(lwd = 2.0)),
segmentsGrob( # diagonal line ll -> ur
x0 = unit(0,"npc"),
y0 = unit(0,"npc"),
x1 = unit(1,"npc"),
y1 = unit(1,"npc"),
gp = gpar(lwd = 2.0))),
t = 3, b = 3, l = 3, r = 3)
grid.draw(g)
If you have many cells to decorate you can use replicate to create create the segments. Just keep the tableGrob numbering scheme in mind.
g <- tableGrob(head(iris), theme = ttheme_minimal())
separators <- replicate(ncol(g) - 2,
segmentsGrob(x1 = unit(0, "npc"), gp=gpar(lty=2)),
simplify=FALSE)
## add vertical lines on the left side of columns (after 2nd)
g <- gtable::gtable_add_grob(g, grobs = separators,
t = 2, b = nrow(g), l = seq_len(ncol(g)-2)+2)
grid.draw(g)
We may also access and modify the original content of individual cells, e.g. to highlight a value.
g <- tableGrob(iris[1:4, 1:3])
find_cell <- function(table, row, col, name="core-fg"){
l <- table$layout
which(l$t==row & l$l==col & l$name==name)
}
ind <- find_cell(g, 3, 2, "core-fg")
ind2 <- find_cell(g, 2, 3, "core-bg")
g$grobs[ind][[1]][["gp"]] <- gpar(fontsize=15, fontface="bold")
g$grobs[ind2][[1]][["gp"]] <- gpar(fill="darkolivegreen1", col = "darkolivegreen4", lwd=5)
grid.draw(g)
The tableGrob function can be very slow; unfortunately this is the price to pay for its versatility and easier implementation. We use individual textGrob and rectGrob elements for each cell, instead of relying on the vectorised implementation of these functions. The reason is practical: it is much easier to place, measure, and customise individual grobs, than modify the graphical parameters and positions of a single vectorised grob. An alternative function is presented below, using this vectorised approach, but lacking many of the customisations of tableGrob.
grid.ftable <- function(d, padding = unit(4, "mm"), ...) {
nc <- ncol(d)
nr <- nrow(d)
## character table with added row and column names
extended_matrix <- cbind(c("", rownames(d)),
rbind(colnames(d),
as.matrix(d)))
## string width and height
w <- apply(extended_matrix, 2, strwidth, "inch")
h <- apply(extended_matrix, 2, strheight, "inch")
widths <- apply(w, 2, max)
heights <- apply(h, 1, max)
padding <- convertUnit(padding, unitTo = "in", valueOnly = TRUE)
x <- cumsum(widths + padding) - 0.5 * padding
y <- cumsum(heights + padding) - padding
rg <- rectGrob(x = unit(x - widths/2, "in"),
y = unit(1, "npc") - unit(rep(y, each = nc + 1), "in"),
width = unit(widths + padding, "in"),
height = unit(heights + padding, "in"))
tg <- textGrob(c(t(extended_matrix)), x = unit(x - widths/2, "in"),
y = unit(1, "npc") - unit(rep(y, each = nc + 1), "in"),
just = "center")
g <- gTree(children = gList(rg, tg), ...,
x = x, y = y, widths = widths, heights = heights)
grid.draw(g)
invisible(g)
}
grid.newpage()
grid.ftable(head(iris, 4), gp = gpar(fill = rep(c("grey90", "grey95"), each = 6)))
## R Under development (unstable) (2016-02-17 r70182)
## Platform: x86_64-apple-darwin13.4.0 (64-bit)
## Running under: OS X 10.11.3 (El Capitan)
##
## locale:
## [1] C/en_NZ.UTF-8/en_NZ.UTF-8/C/en_NZ.UTF-8/en_NZ.UTF-8
##
## attached base packages:
## [1] grid stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] gtable_0.1.2 lattice_0.20-33 ggplot2_2.0.0 gridExtra_2.2.1
## [5] knitr_1.12.3
##
## loaded via a namespace (and not attached):
## [1] Rcpp_0.12.1 digest_0.6.8 plyr_1.8.3 formatR_1.2.1
## [5] magrittr_1.5 evaluate_0.8 scales_0.3.0 stringi_0.5-5
## [9] rmarkdown_0.9.2 labeling_0.3 tools_3.3.0 stringr_1.0.0
## [13] munsell_0.4.2 yaml_2.1.13 colorspace_1.2-6 htmltools_0.3The gridExtra package provides a basic implementation of regular polygons, ngonGrob()/grid.ngon, and a convenience function to draw ellipses, ellipseGrob()/grid.ellipse(). We illustrate below the basic usage of these vectorised functions.
library(gridExtra)
library(grid)
library(grid)
N <- 5
xy <- polygon_regular(N)*2
# draw multiple polygons
g <- ngonGrob(unit(xy[,1],"cm") + unit(0.5,"npc"),
unit(xy[,2],"cm") + unit(0.5,"npc"),
n=seq_len(N)+2, gp=gpar(fill=1:N))
grid.newpage()
grid.draw(g)
g2 <- ngonGrob(unit(xy[,1],"cm") + unit(0.5,"npc"),
unit(xy[,2],"cm") + unit(0.5,"npc"),
n=seq_len(N)+2, ar=seq_len(N),
phase=0, angle=pi/(seq_len(N)+2),
size=1:N+5, gp=gpar(fill=1:N))
grid.newpage()
grid.draw(g2)
g3 <- ellipseGrob(unit(xy[,1],"cm") + unit(0.5,"npc"),
unit(xy[,2],"cm") + unit(0.5,"npc"),
angle=-2*seq(0,N-1)*pi/N+pi/2,
size=5, ar=3, gp=gpar(fill=1:N))
grid.newpage()
grid.draw(g3)