gtable

The R package gtable is designed to help construct and manipulate layouts containing graphical elements. The standard grid package in R provides low-level functions to define viewports, and place graphical elements (grobs) at specific locations within the device window. gtable builds upon these functions and provides a higher-level interface, where one can e.g. merge two layouts, add columns, rows, insert graphical elements in a given cell, and change the display order, among other things.

The gtable package is used internally by ggplot2, and can therefore be used to modify the layout of such plots.

Constructing a gtable

A gtable object can be constructed in a variety of ways,

• Empty table

a <- gtable(unit(1:3, c("cm")), unit(5, "cm"))

This is an empty table with 3 rows and one column. gtable_col and gtable_row provide a simplified interface for 1 column or 1 row layouts, respectively.

• matrix layout of grobs

a <- rectGrob(gp = gpar(fill = "red"))
b <- circleGrob()
c <- linesGrob()

mat <- matrix(list(a, b, c, nullGrob()), nrow = 2)
gtable_matrix("demo", mat, unit(c(1, 1), "null"), unit(c(1, 1), "null"))

It's also easy to implement new constructor functions, e.g.

• based on grid.arrange

• based on a pre-defined layout

Modifying a gtable

Examples to change ggplot2 plots with gtable

• aligning (multiple) ggplot objects on a device, other use-case, aligning base plot and ggplot

• adding new grobs aligned with the plot panel, also this one

• calculate the device size based on the plot aspect ratio

• add new axes to a facet_grid layout, a second axis