Getting to Know grid Graphics

Getting to Know grid Graphics

Paul Murrell, The University of Auckland, December 2017

An overview of the short course

Introduction

For the book "London: The Information Capital", each infographic was begun in R and then "finished off" in Adobe Illustrator. This sort of thing bugs me because I have a deep need to do all of my drawing in code (for keeping a record and for replication and for sharing, among other things).

Introduction

One of the distinguishing features of the R graphics system, and the 'grid' graphics system in particular, is that it allows you fine control over details, including access to more advanced graphical features and details. As a "dramatic" demonstration of this idea, the image on this slide was generated completely in R. This course will try to reveal how 'grid' works so that you can do this sort of thing yourself.

Where is grid ?

The 'grid' package provides an ALTERNATIVE graphics system to the 'graphics' package ("base" graphics). Many packages define plotting functions based on 'graphics', but there are some important ones based on 'grid', such as 'lattice' and 'ggplot2'.

Where is grid ?

          library(lattice)
          xyplot(mpg ~ disp, mtcars)

When you draw a plot with 'lattice' or 'ggplot2', the actual drawing is being done by 'grid'.

Exploring grid Grobs

          library(grid)
          grid.ls()

When you draw something with 'grid', a record is kept of the objects that are drawn. 'grid' calls these objects "grobs" (graphical objects). The grid.ls() function can be used to list the grobs on the current page.

Exploring grid Grobs

Some other functions that help with exploring grobs:

grid.grep(path) Search for a grob that matches 'path'.
showGrob(gPath) Highlight grob that matches 'gPath'.
grobBrowser() SVG version with grob names as tooltips
(from the 'gridDebug' package).

grid Viewports

          xyplot(mpg ~ disp, mtcars)

When you draw something with 'grid', a record is also kept of any "viewports" that were created. A viewport is a rectangular sub-region on the page.

Exploring grid Viewports

          grid.ls(viewports=TRUE, grobs=FALSE)

The grid.ls() function can also be used to list the viewports on the current page. (The output on this slide has been trimmed and tidied to fit on one slide.)

Exploring grid Viewports

          grid.ls(viewports=TRUE, fullNames=TRUE)

This is the first few lines of the complete output from grid.ls() that shows both viewports and grobs (and therefore the nesting of grobs within viewports).

Exploring grid Viewports

Some other functions that help with exploring viewports:

showViewport(vp) Highlight viewport that matches 'vp'.
current.viewport() Returns the current viewport.

Ideally, a package will document the naming scheme that it uses for grobs and viewports. Ideally, a package will have a naming scheme!

Exercise

The purpose of this exercise is to make use of the grid.ls() function.

The following code creates a 'lattice' scatterplot: 

library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
  1. What is the name of the grob that represents the main title on the scatterplot? 
    2. library(grid)
grid.ls()
# plot_01.main
  2. What is the name of the viewport that the main title is drawn within? 
    3. library(grid)
grid.ls(viewports=TRUE, fullNames=TRUE)
# plot_01.main.vp

Why Grobs ?

library(lattice)
barchart(Party ~ Amount_Donated, sortedTotals)

One benefit of having access to the low-level 'grid' grobs is that we can make detailed customisations to a plot that was drawn with a high-level function where the high-level function does not provide control over enough of the details. In this case, I want to remove the border around the lattice panel.

Why Grobs ?

library(grid)
grid.ls()

If I can find out what the grob is called ...

Why Grobs ?

library(grid)
grid.remove("plot_01.border.panel.1.1")

... then I can remove it with grid.remove().

Working With Grobs

Functions that can be used to access grobs:

grid.remove() Remove a grob.
grid.edit() Modify a grob component.
grid.get() Get a copy of a grob component.
grid.set() Replace a grob component.

Each function takes the name of a grob as its first argument. The name argument can be a regular expression, if you specify 'grep=TRUE'. You can work with more than one grob at once if you specify 'global=TRUE'.

Modifying Grobs

library(grid)
t <- grid.get("plot_01.ticklabels.bottom.panel.1.1")
names(t)
        
names(t)
        
t$just

Grobs are just lists with components.

Modifying Grobs

library(grid)
grid.edit("plot_01.ticklabels.bottom.panel.1.1",
          just=c("left", "top"))

We can use grid.edit() to change the value of a component.

However, we may NOT edit 'name' or 'vp' components of a grob.

Modifying Grobs

library(grid)
gpar(col="blue", lwd=3, lty="dashed")

The value of the 'gp' component of a grob is created with the gpar() function.

Modifying Grobs

Common gpar() settings:

col (border) colour.
fill fill colour.
lty line type.
lwd line width.
cex text size multiplier.

The other gpar() settings:

fontsize The size of text (in points).
lineheight Vertical height of a line of text (multiplier). For vertical positioning of multi-line text.
fontface "plain", "bold", "italic", or "bolditalic".
fontfamily "sans", "serif", "mono", or the name of a font family that makes sense on the current graphics device.
lineend "round", "square", or "butt". The shape used at the end of lines.
linejoin "round", "mitre", "bevel". The shape used at line corners.
linemitre Number used to decide when mitre joins become bevel joins.
lex Line expansion multiplier (affects line width).

Modifying Grobs

library(grid)
grid.edit("plot_01.ticklabels.bottom.panel.1.1",
          gp=gpar(col="grey"))

Modifying the 'gp' component of a grob ONLY changes the gpar() settings that are given new values.

Exercise

The purpose of this exercise is to make use of the grid.edit() and grid.remove() functions.

The following code creates a 'lattice' scatterplot: 

library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
  1. Change the colour of the main title to red. 
    2. library(grid)
grid.edit("plot_01.main", gp=gpar(col="red"))
  2. Remove the main title from the plot. 
    3. library(grid)
grid.remove("plot_01.main")

Exercise

This is the result you are looking for (before you remove the title): 

svg("lattice-remove-grob.svg")
library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
library(grid)
grid.edit("plot_01.main", gp=gpar(col="red"))
dev.off()

Why Viewports ?

Credit: John G. Bullock, Yale University.

John Bullock made use of the 'lattice' viewports that were created in this multi-panel plot to centre the text below each row of plots. (He did not use the 'xlab' argument to xyplot() because he wanted greater control over the vertical placement of the text.)

Why Viewports ?

Credit: John G. Bullock, Yale University.

John could do this because it is possible to revisit the viewports that are created when a plot is drawn with 'grid'.

Navigating Viewports

xyplot(mpg ~ disp, mtcars)

When you draw something with 'grid', a record is kept of any "viewports" that were created. A viewport is a rectangular sub-region on the page.

Navigating Viewports

          grid.ls(viewports=TRUE, fullNames=TRUE)

Viewports can be nested within each other.

Navigating Viewports

svg("lattice-plot-vp-tree.svg", width=10, height=5)
library(gridGraphviz)
vplsshort <- lapply(vpls, "[", 1:6)
class(vplsshort) <- class(vpls)
nodes <- vplsshort$name
edges <- rep(list(list()), 6)
names(edges) <- nodes
edges$ROOT <- list(edges="plot_01.toplevel.vp")
edges$plot_01.toplevel.vp <- list(edges=nodes[-(1:2)])
gnel <- new("graphNEL", nodes, edges, edgemode="directed")
rag <- agopenTrue(gnel, "",
                  attrs=list(node=list(shape="ellipse")))
# grid.newpage()
grid.graph(rag)
dev.off()

Viewports can be nested within each other.

Navigating Viewports

downViewport("plot_01.toplevel.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(0,1,0,.5)))
        
svg("lattice-plot-down-viewport.svg")
xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.toplevel.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(0,1,0,.5)))
dev.off()

It is possible to revisit the viewports that a plot has created with the downViewport() function (and the name of the viewport we want to visit).

Navigating Viewports

downViewport("plot_01.panel.1.1.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(1,0,0,.5)))
        
svg("lattice-plot-down-2-viewport.svg")
xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.toplevel.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(0,1,0,.5)))
downViewport("plot_01.panel.1.1.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(1,0,0,.5)))
dev.off()

It is possible to revisit the viewports that a plot has created with the downViewport() function (and the name of the viewport we want to visit).

NOTE that drawing occurs relative to the viewport that we are currently in (by default, grid.rect() fills the entire viewport).

Navigating Viewports

upViewport()
grid.rect(gp=gpar(col=NA, fill=rgb(0,0,1,.5)))
        
svg("lattice-plot-up-viewport.svg")
xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.toplevel.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(0,1,0,.5)))
downViewport("plot_01.panel.1.1.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(1,0,0,.5)))
upViewport()
grid.rect(gp=gpar(col=NA, fill=rgb(0,0,1,.5)))
dev.off()

We can navigate up the viewport tree as well, using the upViewport() function.

Exercise

The purpose of this exercise is to make use of the downViewport() function.

The following code creates a 'lattice' scatterplot: 

library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
  1. Navigate to the viewport that the main title was drawn in and draw a rectangle to show that you are in the right place. 
    2. library(grid)
downViewport("plot_01.main.vp")
grid.rect()

Exercise

This is the result you are looking for: 

svg("lattice-down-viewport.svg")
library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
library(grid)
downViewport("plot_01.main.vp")
grid.rect(gp=gpar(col=NA, fill=rgb(0,0,1,.5)))
dev.off()

Why Viewports ?

Credit: Pascal A. Niklaus, University of Zurich.

Pascal Niklaus wanted to add letter labels in the top-left corner of each of his plots.

Why Viewports ?

Credit: Pascal A. Niklaus, University of Zurich.

These letter labels are difficult to position using the coordinate system provided by the scales on the plot axes.

Why Viewports ?

Credit: Brad Boehmke.

Here is a similar example, with more elaborate text annotations, this time on a 'ggplot2' plot.

Viewport Coordinates

xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.panel.1.1.vp")

Every 'grid' viewport has several coordinate systems associated with it.

Viewport Coordinates

grid.text("native", 
          x=unit(300, "native"), y=unit(30, "native"),
          just=c("left", "bottom"))
        
svg("lattice-plot-vp-coords-native.svg")
xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.panel.1.1.vp")
grid.lines(unit(c(0, 300, 300), c("npc", "native", "native")),
           unit(c(30, 30, 0), c("native", "native", "npc")),
           gp=gpar(lty="dashed", lwd=2))
grid.text("native", x=unit(300, "native"), y=unit(30, "native"),
          just=c("left", "bottom"))
dev.off()

The unit() function associates a value with a coordinate system.

"Native" coordinates are relative to the 'xscale' and 'yscale' on the viewport.

Viewport Coordinates

grid.text("absolute", 
          x=unit(1, "in"), y=unit(1, "cm"),
          just=c("left", "bottom"))
        
svg("lattice-plot-vp-coords-abs.svg")
xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.panel.1.1.vp")
grid.lines(unit(c(0, 1, 1), c("npc", "in", "in")),
           unit(c(1, 1, 0), c("cm", "cm", "npc")),
           gp=gpar(lty="dashed", lwd=2))
grid.text("absolute", 
          x=unit(1, "in"), y=unit(1, "cm"),
          just=c("left", "bottom"))
dev.off()

Absolute coordinates include "in", "cm", and "pt". All are measured from the bottom-left corner of the viewport.

Viewport Coordinates

grid.text("normalised", 
          x=unit(.75, "npc"), y=unit(.5, "npc"),
          just=c("left", "bottom"))
        
svg("lattice-plot-vp-coords-npc.svg")
xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.panel.1.1.vp")
grid.lines(unit(c(0, .75, .75), "npc"),
           unit(c(.5, .5, 0), "npc"),
           gp=gpar(lty="dashed", lwd=2))
grid.text("normalised", 
          x=unit(.75, "npc"), y=unit(.5, "npc"),
          just=c("left", "bottom"))
dev.off()

Normalised ("npc") coordinates are 0-to-1 along each side of the viewport.

Viewport Coordinates

grid.text("normalised - absolute", 
          x=unit(1, "npc") - unit(1, "cm"), 
          y=unit(1, "npc") - unit(1, "cm"),
          just=c("right", "top"))
        
svg("lattice-plot-vp-coords-npc-abs.svg")
xyplot(mpg ~ disp, mtcars)
downViewport("plot_01.panel.1.1.vp")
grid.move.to(unit(1, "npc") - unit(1, "cm"), 1)
grid.line.to(unit(1, "npc") - unit(1, "cm"), 
             unit(1, "npc") - unit(1, "cm"),
             gp=gpar(lty="dashed", lwd=2))
grid.line.to(1, unit(1, "npc") - unit(1, "cm"),
             gp=gpar(lty="dashed", lwd=2))
grid.text("normalised - absolute", 
          x=unit(1, "npc") - unit(1, "cm"), 
          y=unit(1, "npc") - unit(1, "cm"),
          just=c("right", "top"))
dev.off()

We can use simple arithmetic on units. In this case, we are positioning text a fixed amount in from the top-right corner of a viewport.

Drawing Grobs

Some basic shapes that 'grid' can draw:

grid.rect(x,y,w,h) rectangles.
grid.circle(x,y,r) circles.
grid.lines(x,y) straight lines through (x,y).
grid.segments(x0,y0,x1,y1) straight lines from (x0,y0) to (x1,y1).
grid.text(label,x,y) text.

The other "shapes" that 'grid' can draw:

grid.move.to(x,y) set current "pen" location.
grid.line.to(x,y) straight line from "pen" location to (x,y) (and set "pen" location to (x,y)).
grid.polyline(x,y,id) straight lines through multiple sets of (x,y).
grid.xspline(x,y,shape) smooth curve relative to (x,y) control points.
grid.roundrect(x,y,w,h,r) rectangle with rounded corners.
grid.polygon(x,y) polygon defined by (x,y) (automatically closing last point to first point).
grid.path(x,y,id) path (potentially defined by multiple polygons).
grid.raster(image,x,y,w,h) raster image.
grid.curve(x1,y1,x2,y2) smooth curve between two end points.
grid.points(x,y,pch) data symbols at (x,y) (default coordinate system is "native"!).

Drawing Grobs

grid.rect(x=unit(.2, "npc"), y=unit(100, "native"),
          width=unit(1, "in"), height=unit(1, "lines"))
        
svg("multiple-units.svg", width=3, height=3)
# grid.newpage()
grid.segments(1:4/5, 0, 1:4/5, 1, gp=gpar(col="grey"))
grid.text(0:4/5, 
          x=unit(0:4/5, "npc") + unit(1, "mm"),
          y=unit(1, "npc") - unit(1, "mm"),
          just=c("left", "top"),
          gp=gpar(col="grey", cex=.5))
grid.segments(0, unit(seq(50, 200, 50), "native"), 
              1, unit(seq(50, 200, 50), "native"), 
              gp=gpar(col="grey"))
grid.text(seq(0, 200, 50), 
          x=unit(1, "npc") - unit(2, "mm"),
          y=unit(seq(0, 200, 50), "native") - unit(1, "mm"),
          just=c("right", "top"),
          gp=gpar(col="grey", cex=.5))
grid.segments(0, .2, 1, .2, 
              arrow=arrow(type="closed", ends="both",
                          angle=15, length=unit(3, "mm")),
              gp=gpar(col="grey", fill="grey", lwd=3))
tg <- textGrob("3 inches", y=.2, gp=gpar(cex=.5, col="grey"))
grid.rect(y=.2, width=1.2*grobWidth(tg), height=unit(1, "lines"),
          gp=gpar(col=NA, fill="white"))
grid.draw(tg)
grid.rect(x=unit(.2, "npc"), y=unit(100, "native"),
          width=unit(1, "in"), height=unit(1, "lines"))
grid.text("text", x=unit(.2, "npc"), y=unit(100, "native"),
          gp=gpar(col="grey"))
dev.off()

Whenever we draw a grob, we can specify the position and size of the grob using any of the available coordinate systems (the default is almost always "npc").

Drawing Grobs

grid.circle(x=1:5/6, y=.5, r=1:5/25)
        
svg("vectorised-grobs.svg")
grid.circle(x=1:5/6, y=.5, r=1:5/20, gp=gpar(fill=NA))
dev.off()

For most grobs, the location and size specifications can be vectors so that a single call to a 'grid' function can produce multiple shapes.

Exercise

The purpose of this exercise is to make use of the unit() function as well as 'grid' functions that draw basic shapes.

The following code creates a 'lattice' scatterplot: 

library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
  1. Navigate to the viewport that the data symbols were drawn in and draw a horizontal line at mpg == 25. 
    2. library(grid)
downViewport("plot_01.panel.1.1.vp")
grid.segments(0, unit(25, "native"),
              1, unit(25, "native"))
upViewport(0)
  2. Draw a label just above and to the right of the symbol for the "Pontiac Firebird" (disp=400, mpg=19.2). 
    3. library(grid)
downViewport("plot_01.panel.1.1.vp")
grid.text("Pontiac Firebird",
          x=unit(400, "native") + unit(1, "mm"),
          y=unit(19.2, "native") + unit(1, "mm"),
          just=c("left", "bottom"))
upViewport(0)

Exercise

This is the result you are looking for: 

svg("lattice-viewport-add.svg")
library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
library(grid)
downViewport("plot_01.panel.1.1.vp")
grid.segments(0, unit(25, "native"),
              1, unit(25, "native"))
grid.text("Pontiac Firebird",
          x=unit(400, "native") + unit(1, "mm"),
          y=unit(19.2, "native") + unit(1, "mm"),
          just=c("left", "bottom"))
upViewport(0)
dev.off()
        

library(grid)
library(lattice)
data_macular <- read.csv('Data/anonymous_data.csv', row.names=1)
# Reduce down to four genes for demonstration purposes
data_macular <- 
    data_macular[as.numeric(gsub("Gene", "", data_macular$gene)) < 5, ]
data_macular$gene <- factor(data_macular$gene)
genes <- levels(data_macular$gene)

# The problem (too many empty panels)
svg("lattice-empty-panels.svg")
print(xyplot(rnflThickness ~ age | mrn + gene, data_macular, pch=16,
             par.strip.text=list(cex=.5)))
dev.off()      

# A solution with grid viewports
xlim <- extendrange(data_macular$age)
ylim <- extendrange(data_macular$rnflThickness)
highlights <- hcl(1:4*90, 60, 60)
highlights <- adjustcolor(highlights, alpha=.5)
vpplot <- function(highlight=FALSE) {
# grid.newpage()
pushViewport(viewport(width=.9, height=.9,
                      layout=grid.layout(4, 1)))
for (i in seq_along(genes)) {
    pushViewport(viewport(layout.pos.row=5 - i))
    print(xyplot(rnflThickness ~ age | mrn, data_macular, pch=16,
                 subset=gene == genes[i],
                 layout=c(6, 1),
                 xlim=xlim, ylim=ylim, ylab=NULL, xlab=NULL,
                 scales=list(x=list(alternating=rep(1, 6), labels=i == 1))),
          newpage=FALSE,
          panel.width=list(2, "cm"), panel.height=list(2, "cm"))
    grid.rect(x=0, width=unit(2, "lines"), height=.8, just="left",
              gp=gpar(col=NA, fill="grey"))
    grid.text(genes[i], x=unit(1, "lines"), rot=90)
    if (highlight) {
        grid.rect(gp=gpar(col=NA, fill=highlights[i]))
    }
    upViewport()
}
grid.text("retinal nerve fiber thickness", x=unit(-1, "lines"), rot=90)
grid.text("age", y=0, just="top")
}
svg("lattice-multi-plots.svg")
vpplot()
dev.off()
svg("lattice-multi-plots-vp.svg")
vpplot(TRUE)
dev.off()

Why Viewports ?

Credit: Tom Wright, affiliation unknown.

Tom Wright has a 'lattice' plot with too many empty panels.

Why Viewports ?

We can do a little bit better if we draw separate 'lattice' plots in separate 'grid' viewports.

Why Viewports ?

This version of the "improved" plot has the 'grid' viewports highlighted by coloured rectangles.

Starting a New Page

grid.newpage()
        
svg("grid-newpage.svg")
grid.newpage()
dev.off()

With raw 'grid', we have to explicitly call the grid.newpage() function to start a new page/screen. All other 'grid' functions just add to the current page/screen.

'lattice' plotting functions, like xyplot(), automatically start a new page, unless you tell them not to with something like print(xyplot(...), newpage=FALSE).

Creating Viewports

vp <- viewport(width=.5, height=.5)
pushViewport(vp)
grid.rect(gp=gpar(col=NA, fill="grey80"))
        
svg("grid-viewport.svg")
vp <- viewport(width=.5, height=.5)
pushViewport(vp)
grid.rect(gp=gpar(col=NA, fill="grey80"))
dev.off()

We can create a new viewport description with the viewport() function. In this case, we are describing a viewport that is half the width of the page and half the height of the page (the default is to be centred on the middle of the page). The location and size of viewports are specified using the unit() function, just like for grobs (and the default coordinate system is "npc").

We create a viewport on the page using the pushViewport() function. After the "push", all drawing occurs within that viewport. In this case, we draw a rectangle that shows the extent of the viewport that we have created.

Creating Viewports

vp2 <- viewport(x=0, y=.5, width=.5, height=.5, 
                just=c("left", "bottom"))
pushViewport(vp2)
grid.rect()
        
svg("grid-viewport2.svg")
vp2 <- viewport(x=0, y=.5, width=.5, height=.5, 
                just=c("left", "bottom"))
pushViewport(vp)
grid.rect(gp=gpar(col=NA, fill="grey80"))
pushViewport(vp2)
grid.rect()
dev.off()

When we push a viewport, the viewport description is always relative to the current viewport. In this case, we define and push a viewport that is in the top-left quarter of the current viewport. We draw a rectangle to show the extent of this new viewport.

Creating Viewports

grid.newpage()
pushViewport(vp)
print(xyplot(mpg ~ disp, mtcars), newpage=FALSE)
        
svg("grid-viewport-lattice-plot.svg")
pushViewport(vp)
grid.rect(gp=gpar(col=NA, fill="grey80"))
print(xyplot(mpg ~ disp, mtcars), newpage=FALSE)
dev.off()

A 'lattice' plot is just a lot of pushing viewports and drawing shapes.

We can tell a 'lattice' plot to do its pushing of viewports and drawing of shapes in the current viewport rather than starting a new page all for itself. We do this by explicitly calling print() on the plot and setting the 'newpage' argument to FALSE.

Exercise

The purpose of this exercise is to make use of the viewport() and pushViewport() functions.

The following code creates a 'lattice' scatterplot: 

library(lattice)
xyplot(mpg ~ disp, mtcars, main="Fast Cars")
  1. Create a viewport in the bottom-right quarter of the page and draw the plot in that viewport. 
    2. library(grid)
grid.newpage()
pushViewport(viewport(x=.5, y=0, width=.5, height=.5,
                      just=c("left", "bottom")))
print(xyplot(mpg ~ disp, mtcars, main="Fast Cars"),
      newpage=FALSE)
upViewport()

Exercise

This is the result you are looking for: 

svg("grid-viewport-create.svg")
library(grid)
grid.newpage()
pushViewport(viewport(x=.5, y=0, width=.5, height=.5,
                      just=c("left", "bottom")))
print(xyplot(mpg ~ disp, mtcars, main="Fast Cars"),
      newpage=FALSE)
upViewport()
dev.off()

Summary

  • 'lattice' plots create 'grid' grobs and viewports.
  • grid.ls() lists grobs and viewports.
  • grid.remove() and grid.edit() modify grobs.
  • downViewport() and upViewport() navigate between viewports.
  • grid.rect(), grid.text(), etc draw new grobs.
  • gpar() controls graphical parameters.
  • viewport() and pushViewport() create new viewports.
  • 'lattice' plots can be drawn within any viewport.

Nuff said

Where is grid ?

library(ggplot2)
qplot(disp, mpg, data=mtcars, main="Fast Cars")

When you draw a plot with 'lattice' or 'ggplot2', the actual drawing is being done by 'grid'.

Exploring grid Grobs

grid.ls()

One difference between the grobs created by 'lattice' and the grobs created by 'ggplot2' is that the latter produces a single grob that draws everything. To see all of the individual grobs that are drawn, we need the grid.force() function.

Exploring grid Grobs

grid.force()
grid.ls()

Another difference between the grobs created by 'lattice' and the grobs created by 'ggplot2' is that the latter are arranged in a hierarchy. For example, there is a "panel" grob, with a "grill" as its child, and various rectangles and polylines as children of that.

Yet another difference is that the 'ggplot2' naming scheme is less intuitive and less complete (and undocumented).

Modifying Grobs

grid.edit("title::text", grep=TRUE, 
          gp=gpar(col="red"))

We can use grid.edit() to change the value of a component just like with 'lattice' plots.

There are two extra complications here: first, we are using 'grep=TRUE' to use grob name pattern matching; second, we are using a grob name *path* to specify a grob with "text" in its name that is the child of a grob with "title" in its name.

Modifying Grobs

grid.remove("title.2-4-2-4")

We can use grid.remove() to remove grobs just like with 'lattice' plots.

Notice that removing a parent grob also removes its children.

Navigating Viewports

qplot(disp, mpg, data=mtcars, main="Fast Cars")
grid.force()
grid.ls(viewports=TRUE, fullNames=TRUE)

'ggplot2' creates viewports just like 'lattice'.

Navigating Viewports

downViewport("panel.3-4-3-4")
grid.rect(gp=gpar(col=NA, fill=rgb(0,1,0,.5)))
        
svg("ggplot2-plot-down-viewport.svg")
qplot(disp, mpg, data=mtcars, main="Fast Cars")
grid.force()
downViewport("panel.6-4-6-4")
grid.rect(gp=gpar(col=NA, fill=rgb(0,1,0,.5)))
dev.off()

It is possible to revisit the viewports that 'ggplot2' has created, just like with 'lattice'.

However, one difference is that the viewport representing the 'ggplot2' plot region does NOT have a "native" scale corresponding to the axis scales.

Exercise

The purpose of this exercise is to make use of 'grid' functions with a 'ggplot2' plot.

The following code creates a 'ggplot2' scatterplot: 

library(ggplot2)
qplot(disp, mpg, data=mtcars, main="Fast Cars")
  1. Navigate to the viewport that the main title was drawn in and draw a rectangle to show the extent of the viewport. 
    2. grid.force()
downViewport("title.2-4-2-4")
grid.rect(gp=gpar(col=NA, fill=rgb(0,0,1,.5)), name="r")
  2. Edit the title grob to move it to the right-hand edge of the plot. 
    3. grid.edit("title::text", grep=TRUE, x=unit(1, "npc"), hjust=1)
  3. Remove the rectangle that you just drew. 
    4. # MUCH easier if you gave the grob a name in the previous answer!
grid.remove("r")

Exercise

This is the result you are looking for: 

svg("ggplot2-plot-ann.svg")
library(ggplot2)
qplot(disp, mpg, data=mtcars, main="Fast Cars")
grid.force()
library(grid)
downViewport("title.2-4-2-4")
grid.edit("title::text", grep=TRUE, x=unit(1, "npc"), hjust=1)
dev.off()

Where is grid ?

library(vcd)
mosaic(Titanic)

A number of other packages build on top of 'grid' (or 'lattice' or 'ggplot2'), but there is no guarantee of a naming scheme for grobs and viewports.

Exploring grid Grobs

grid.ls()

Where is grid ?

The 'gridGraphics' package provides a way to convert plots drawn with the 'graphics' package into identical plots drawn with 'grid'.

Where is grid ?

plot(mpg ~ disp, mtcars, pch=16, main="Fast Cars")
library(gridGraphics)
grid.echo()

We can draw a plot based on 'graphics' then call grid.echo() to convert it into 'grid' grobs and viewports.

Exploring grid Grobs

grid.ls()

Navigating Viewports

grid.ls(viewports=TRUE, fullNames=TRUE)

Exercise

The purpose of this exercise is to make use of 'grid' functions with a 'graphics' plot.

The following code creates a 'graphics' scatterplot: 

plot(mpg ~ disp, mtcars, pch=16, main="Fast Cars")
  1. Convert the plot to an identical 'grid' plot, change the title to red. 
    2. plot(mpg ~ disp, mtcars, pch=16, main="Fast Cars")
library(gridGraphics)
grid.echo()
grid.edit("graphics-plot-1-main-1", gp=gpar(col="red"))
  2. Remove the title. 
    3. plot(mpg ~ disp, mtcars, pch=16, main="Fast Cars")
library(gridGraphics)
grid.echo()
grid.remove("graphics-plot-1-main-1")

Exercise

This is the result you are looking for (before you delete the title): 

svg("graphics-plot.svg")
dev.control("enable")
plot(mpg ~ disp, mtcars, pch=16, main="Fast Cars")
library(gridGraphics)
grid.echo()
grid.edit("graphics-plot-1-main-1", gp=gpar(col="red"))
dev.off()

Why grid ?

svg("lattice.svg")
library(lattice)
barchart(yield ~ variety | site, data = barley,
         groups = year, layout = c(1,6), stack = TRUE,
         auto.key = list(space = "right"),
         ylab = "Barley Yield (bushels/acre)",
         scales = list(x = list(rot = 45)))
dev.off()

The concepts of viewports in the 'grid' package provide a better basis (than the 'graphics' package) for producing complex plots like 'lattice' multi-panel conditioning plots.

For example, how does 'lattice' leave enough space for the axis labels and the plot legend, but make the panels as large as possible ?

Why grid ?

svg("ggplot2.svg")
library(ggplot2)
model <- lm(mpg ~ wt + factor(cyl), data=mtcars)
grid <- with(mtcars, expand.grid(wt = seq(min(wt), max(wt), length = 20),
                                 cyl = levels(factor(cyl))))
grid$mpg <- stats::predict(model, newdata=grid)
err <- stats::predict(model, newdata=grid, se = TRUE)
grid$fit <- err$fit
grid$ucl <- err$fit + 1.96 * err$se.fit
grid$lcl <- err$fit - 1.96 * err$se.fit
qplot(wt, mpg, data=mtcars, colour=factor(cyl)) +
  geom_line(aes(y=fit), data=grid) + 
  geom_ribbon(aes(ymin = lcl, ymax = ucl), data=grid, alpha=.1, lwd=0)
dev.off()

Plots produced by 'ggplot2' also benefit from 'grid' concepts like viewports to determine the arrangement of pieces of a complex plot within a page.

Why grid ?

The fact that 'grid' is a general-purpose graphics system (not just for plots) means that 'grid' concepts like viewports can be applied to things like arranging photos together on a page.

Why grid ?

The fact that 'grid' is a general-purpose graphics system also means that 'grid' can be used as a rudimentary desktop publishing system (code-based, of course).

grid Layouts

svg("lattice-layout.svg")
barchart(yield ~ variety | site, data = barley,
         groups = year, layout = c(1,6), stack = TRUE,
         auto.key = list(space = "right"),
         ylab = "Barley Yield (bushels/acre)",
         scales = list(x = list(rot = 45)))
grid.rect(gp=gpar(col=NA, fill=rgb(1,1,1,.5)))
downViewport("plot_01.toplevel.vp")
nr <- current.viewport()$layout$nrow
nc <- current.viewport()$layout$ncol
for (i in 1:nr) {
  for (j in 1:nc) {
    pushViewport(viewport(layout.pos.col=j, layout.pos.row=i))
    grid.rect(gp=gpar(col="red", fill=NA))
    popViewport()
  }
}
dev.off()

The approach that 'lattice' takes is to use a 'grid' "layout". A layout divides up a (parent) viewport into a number of rows and columns and subsequent (child) viewports that are pushed beneath the (parent) viewport with the layout can occupy a subset of the cells in the (parent) layout.

Creating Layouts

widths <- unit(c(1, 2, 1), c("null", "null", "cm"))
lay <- grid.layout(3, 3, widths=widths)
vplay <- viewport(layout=lay)
pushViewport(vplay)
pushViewport(viewport(layout.pos.row=2, 
                      layout.pos.col=2))
grid.rect(gp=gpar(col=NA, fill=rgb(1,0,0,.5)))
        
svg("grid-layout.svg", width=3, height=3)
pushViewport(vplay)
for (i in 1:3) {
  pushViewport(viewport(layout.pos.row=i))
  grid.segments(0, 0, 1, 0, gp=gpar(lty="dashed", lwd=2))
  if (i == 1)
    grid.segments(0, 1, 1, 1, gp=gpar(lty="dashed", lwd=2))
  popViewport()
}
for (j in 1:3) {
  pushViewport(viewport(layout.pos.col=j))
  grid.segments(0, 0, 0, 1, gp=gpar(lty="dashed", lwd=2))
  if (i == 3)
    grid.segments(1, 0, 1, 1, gp=gpar(lty="dashed", lwd=2))
  popViewport()
}
pushViewport(viewport(layout.pos.row=2, layout.pos.col=2))
grid.rect(gp=gpar(col=NA, fill=rgb(1,0,0,.5)))
dev.off()

A layout can be specified as part of the description of a viewport.

A viewport can specify its location in terms of the rows and columns of a parent layout.

Exercise

The purpose of this exercise is to make use of the grid.layout() function.

  1. Produce a layout like the diagram below. 
    2. plot(mpg ~ disp, mtcars, pch=16, main="Fast Cars")
library(gridGraphics)
grid.echo()
grid.edit("graphics-plot-1-main-1", gp=gpar(col="red"))
          
       +-----------------------------------------+ 
       |         w=7/9      5    h=0.5/5.5       |
       +-----+-----------------------------+-----+
       |     |              1    h=1.0/5.5 |     |
       |     +-----------------------------+     |
       |  6  |              2    h=1.0/5.5 |  7  |
       |     +-----------------------------+     |
       |w=1/9|              3    h=1.0/5.5 |w=1/9|
       |     +-----------------------------+     |
       |     |                             |     |
       |     |              4    h=2.0/5.5 |     |
       |     |                             |     |
       +-----+-----------------------------+-----+

Credit: Julio Sergio Santana. 

layout <- grid.layout(5, 3, widths=c(1, 7, 1),
                      heights=c(.5, 1, 1, 1, 2))
grid.show.layout(layout)
grid.newpage()
pushViewport(viewport(layout=layout))
pushViewport(viewport(layout.pos.row=1))
grid.rect(); grid.text("5")
popViewport()
pushViewport(viewport(layout.pos.row=2, layout.pos.col=2))
grid.rect(); grid.text("1")
popViewport()
pushViewport(viewport(layout.pos.row=3, layout.pos.col=2))
grid.rect(); grid.text("2")
popViewport()
pushViewport(viewport(layout.pos.row=4, layout.pos.col=2))
grid.rect(); grid.text("3")
popViewport()
pushViewport(viewport(layout.pos.row=5, layout.pos.col=2))
grid.rect(); grid.text("4")
popViewport()
pushViewport(viewport(layout.pos.row=2:5, layout.pos.col=1))
grid.rect(); grid.text("6")
popViewport()
pushViewport(viewport(layout.pos.row=2:5, layout.pos.col=3))
grid.rect(); grid.text("7")
popViewport()

Exercise

This is the result you are looking for (the grid.show.layout() function takes a 'grid' layout as its argument and draw a diagram of the layout): 

svg("grid-show-layout.svg")
layout <- grid.layout(5, 3, widths=c(1, 7, 1),
                      heights=c(.5, 1, 1, 1, 2))
grid.show.layout(layout)
dev.off()

Viewport Coordinates

grid.rect(width=stringWidth("axis label"))
        
svg("grid-stringwidth.svg", width=2, height=2)
grid.text("axis label", gp=gpar(col="grey"))
grid.rect(width=stringWidth("axis label"), gp=gpar(fill=NA))
dev.off()

The stringWidth() function lets us specify a width in terms of the size of a piece of text (like a label on a plot axis).

There is also a stringHeight() function.

Both of these functions can be used to specify the widths of columns (or heights of rows) in a 'grid' layout (for example to leave enough space for axis labels around a plot).

Viewport Coordinates

grid.text("axis label", name="t")
grid.rect(width=grobWidth("t"))
        
svg("grid-grobwidth.svg", width=2, height=2)
grid.text("axis label", name="t")
grid.rect(width=grobWidth("t"), gp=gpar(fill=NA))
dev.off()

The grobWidth() function lets us specify a width in terms of the size of a grob (even a collection of grobs like a plot legend).

There is also a grobHeight() function.

Both of these functions can also be used to specify the widths of columns (or heights of rows) in a 'grid' layout (for example to leave enough room for a legend beside a plot).

Why grid ?

This sort of diagram presents a different sort of problem: how to draw a line from the edge of one shape to the edge of another shape ?

Viewport Coordinates

grid.text("label", x=1/3, y=1/3, name="t")
grid.circle(2/3, 2/3, r=unit(1, "mm"),
            gp=gpar(fill="black"))
grid.segments(grobX("t", 0), grobY("t", 0), 2/3, 2/3) 
        
svg("grid-grobx.svg", width=3, height=3)
grid.text("label", x=1/3, y=1/3, name="t")
grid.circle(2/3, 2/3, r=unit(1, "mm"),
            gp=gpar(fill="black"))
grid.segments(grobX("t", 0), grobY("t", 0), 2/3, 2/3) 
dev.off()

The grobX() function lets us specify a location in terms of the boundary of a grob.

There is also a grobY() function.

Exercise

The purpose of this exercise is to make use of the grobX(), grobY(), grobWidth(), and grobHeight() functions.

The following code draws two pieces of text: 

grid.newpage()
grid.text("label 1", 1/3, 2/3, name="l1")
grid.text("label two", 2/3, 1/3, name="l2")
  1. Draw a circle around each piece of text (with a radius that is half of the width of the text, plus 1mm). 
    2. grid.circle(1/3, 2/3, r=0.5*grobWidth("l1") + unit(1, "mm"),
            name="c1")
grid.circle(2/3, 1/3, r=0.5*grobWidth("l2") + unit(1, "mm"),
            name="c2")
  2. Draw a line from the bottom-right edge of the top-left circle to the top-left edge of the bottom-right circle. 
    3. grid.segments(grobX("c1", 315), grobY("c1", 315),
              grobX("c2", 135), grobY("c2", 135))

Exercise

This is the result you are looking for: 

svg("grob-width-x.svg", width=3, height=3)
grid.text("label 1", 1/3, 2/3, name="l1")
grid.text("label two", 2/3, 1/3, name="l2")
grid.circle(1/3, 2/3, r=0.5*grobWidth("l1") + unit(1, "mm"),
            name="c1", gp=gpar(fill=NA))
grid.circle(2/3, 1/3, r=0.5*grobWidth("l2") + unit(1, "mm"),
            name="c2", gp=gpar(fill=NA))
grid.segments(grobX("c1", 315), grobY("c1", 315),
              grobX("c2", 135), grobY("c2", 135))
dev.off()

Why grid ?

# Background data
unknown <- 8.7
total <- 9.1
known <- total - unknown

theta0 <- pi/4
thetaN <- theta0 + 2*pi*unknown/total
theta <- seq(theta0, thetaN, length.out=100)
x <- 0.3*c(0, cos(theta)) + 0.5
y <- 0.3*c(0, sin(theta)) + 0.35

library(png)
bg <- readPNG("AfterTheBombs.png")

library(gridSVG)
gridsvg("gridsvg.svg", width=7, height=5.5, res=96, prefix="gridsvg")
# grid.newpage()
grid.raster(bg, height=1)
pushViewport(viewport(width=unit(1, "snpc"), height=unit(1, "snpc")))
grid.polygon(x, y, gp=gpar(col=NA, fill=rgb(.67, 0, .11)),
             name="pie")
# This could, in theory, be done with an feBlend filter
# using "BackgroundImage" as second source, but that 
# requires setting 'enable-background;"new"' somewhere in 
# the SVG (at least), which is not (currently) possible 
# with 'gridSVG'
img <- feImage(href="AfterTheBombs-flipped.png", 
               preserveAspectRatio="xMidYMin slice",
               result="img")
compose <- feBlend("SourceGraphic", "img", "darken")
grid.filter("pie", filterEffect(list(img, compose)))
headText <- 
    "The Department of Defense is unable to account for the use of
$8.7 billion of the $9.1 billion it spent on reconstruction in Iraq"
heading <- textGrob(headText,
                    x=unit(0.5, "cm"),
                    y=unit(3, "lines"),
                    just=c("left", "top"),
                    gp=gpar(col="white"))
pushViewport(viewport(gp=gpar(cex=.8)),
             viewport(x=0.05, y=1,
                      just=c("left", "top"),
                      height=grobHeight(heading) + unit(4, "lines"),
                      width=grobWidth(heading) + unit(1, "cm")))
grid.rect(gp=gpar(fill="black"))
grid.segments(x0=unit(0.5, "cm"),
              x1=unit(1, "npc") - unit(0.5, "cm"),
              y0=unit(1, "npc") - unit(2, "lines"),
              y1=unit(1, "npc") - unit(2, "lines"),
              gp=gpar(col="grey50", lwd=2))
grid.text("That's 96 Percent",
          x=unit(0.5, "cm"),
          y=unit(1, "npc") - unit(1, "lines"),
          just="left",
          gp=gpar(fontface="bold", col="white"))
grid.draw(heading)
popViewport(2)
dev.off()

This sort of infographic is an example of something that is hard to do in standard R graphics because it involves more advanced graphics operations (like raster image compositing).

Where is grid ?

The 'gridSVG' package provides access to some of the more sophisticated graphics features of SVG.

gridSVG

library(gridSVG)
grid.circle(r=.2, name="c")
grid.filter("c", filterEffect(feGaussianBlur(sd=3)))
grid.export()
        
library(gridSVG)
gridsvg("gridsvg-blur.svg", prefix="gridsvg-blur")
grid.circle(r=.2, name="c")
grid.filter("c", filterEffect(feGaussianBlur(sd=3)))
dev.off()

The gridsvg() function opens a 'gridSVG' device. An alternative is the grid.export() function.

Exercise

The purpose of this exercise is to make use of the 'gridSVG' package.

The following code draws a scatterplot: 

library(lattice)
xyplot(jitter(Sepal.Length) ~ jitter(Sepal.Width), 
       group=Species, iris,
       par.settings=list(
           superpose.symbol=list(pch=21, 
                                 col="black",
                                 fill="grey")))
  1. Blur all of the points except for the "setosa" variety (hint: there are three separate points grobs in the plot, one for each variety). 
    2. library(gridSVG)
grid.filter("group.[12]", grep=TRUE, global=TRUE,
            filterEffect(feGaussianBlur(sd=3)))
grid.export("lattice-iris-blur.svg")

Exercise

This is the result you are looking for
(which is an SVG file):

Summary

  • 'ggplot2' plots create 'grid' grobs and viewports.
  • Other packages create 'grid' grobs and viewports too, but there is no guarantee of a naming scheme.
  • 'gridGraphics' creates 'grid' grobs and viewports from 'graphics' plots.
  • grid.layout() creates layouts.
  • grobX(), grobY(), grobWidth(), and grobHeight() describe locations and sizes in terms of the locations and sizes of other grobs.
  • 'gridSVG' exports 'grid' grobs and viewports to SVG, with the possibility of fancier graphics features.

Nuff said

Writing for Others

  • Name all grobs and viewports.
  • Document your naming scheme.
  • Use upViewport() instead of popViewport().

These are some guidelines for writing 'grid' graphics code that will help others to work with your result.

Haere rā!

Farewell!