R Graphics using the grid package
Sigal Blay
Statistical Genetics Working Group
Dept. of Statistics and Actuarial Science
Simon Fraser University
January 2006

Grid
* Low level graphics system
* Produces editable graphical components (not just graphics output)
* Object Oriented - graphical components can be reused and recombined


* grid provides a standard set of graphical primitives
grid.rect(...)
grid.lines(...)
grid.polygon(...)
grid.circle(...)
grid.text(...)

library(help = grid) for more details


For every function of the form grid.* there is an equivalent function *Grob 
that returns a graphical object but doesn't draw it on the graphics device
grid.rect(...)		rectGrob(...)
grid.lines(...)		linesGrob(...)
grid.polygon(...)	polygonGrob(...)
grid.circle(...)	circleGrob(...)
grid.text(...)		textGrob(..)

Usage:
Rect <- rectGrob(...)
grid.draw(Rect)


* Graphical output can be positioned and sized relative to a large 
number of coordinate systems
grid.rect(x=unit(0, "native"),
          y=unit(1.5, "lines"),
          height=unit(0.5, "inches"),
          ...)

help(unit) for more details


* can specify various graphical parameters
grid.rect(gp=gpar(col="red", lwd=2, fill="yellow", lty="dotted"))
grid.text(gp=gpar(col="red", fontsize=10, fontface="italic"))

help(gpar) for more details


* All drawing occurs in the current grid viewport,
a defined rectangular region with it's own defined coordinate system
vp <- viewport(width=0.5, height=0.25, angle=45)
grid.show.viewport(vp)
To find viewport properties without showing them:
format(vp)	# print vp as a list
names(vp)	# get the names attribute of a list
vp$width	# use the name "width" to extract the associated value
vp$width <- unit(0.8,"npc")	# edit viewport

help(viewport) for more details


vp <- viewport(width=0.5, height=0.2, angle=45, name="VP")
pushViewport(vp)      # create a new region on the graphics device
grid.rect()
grid.xaxis()
grid.yaxis()
grid.text("viewport region", y = 0.9)
upViewport()
grid.text("root region", y = 0.1)
current.viewport()    # viewport[ROOT]
current.vpTree()      # viewport[ROOT]->(viewport[VP])
grid.text("more text", y=0.7, vp="VP")
downViewport("VP")
popViewport()         # remove the current viewport
current.vpTree()      # viewport[ROOT]


* can push multiple viewport
  pushViewport(vpList(vp1, vp2, vp3))
* can push nested viewports
  pushViewport(vpStack(vp1, vp2, vp3))
  pushViewport(vpTree(vp1, vpList(vp2, vp3)))
* can integrate with a layout


plotViewport(...) 
a convenience function for producing a viewport with a central plot region
surrounded by margins given in terms of a number of lines of text.

dataViewport(...)
a convenience function for producing a viewport with x-
and/or y-scales based on numeric values passed to the function.


* grid creates graphical objects (grobs) representing the graphical output
grid.rect(..., name="box")
grid.circle(...)
grid.edit("box", gp=gpar(fill="yellow"))
grid.remove("box")


gTree - a tree of grobs
vp<-viewport(..., name="view")
x <- xaxisGrob(name = "axis1")
y <- yaxisGrob(name = "axis2")
points <- pointsGrob(1:9, 1:9, name="dataPoints")
title <- textGrob(..., name="myTitle")
tree <- gTree(children=gList(x,y, title, points), vp=vp, name="Tree")
grid.draw(tree)

Query and edit a gTree
getNames()       # list all top-level grobs
childNames(tree) # list grob children of a gTree 
childNames(grid.get("Tree"))
grid.add("Tree", grid.rect())
grid.edit(gPath("Tree","dataPoints"), pch=2)
grid.ls()	# Returns a listing of the names of grobs
grid.ls(viewports=TRUE)	# Returns a listing of the names of grobs and viewports


Conclusions
the R grid package enables the production of 
reusable and flexible graphical components 

Further reading
R graphics / Paul Murrell



##################################################################################
# Convert a point from viewport coordinates to device coordinates (inches)
pushViewport(viewport(width=.5, height=.5))
grid.rect()
trans <- current.transform()	# the transformation matrix
vc <- c(0, 0, 1)		# (x, y, 1) - a point in viewport coordinates, in inches
upViewport()
dc <- vc %*% trans		# (x, y, 1) - the same point in device coordinates, in inches
grid.circle(dc[1,1], dc[1,2], 0.05, default.unit="inches")

# Convert a point from device coordinates to viewport coordinates (inches)
vc <- t(solve(t(trans), t(dc))) # dc - device coordinates, vc - viewport coordinates
pushViewport(viewport(width=.5, height=.5))
grid.circle(vc[1,1], vc[1,2], 0.1, default.unit="inches")
upViewport()
##################################################################################