grid Graphics Paul Murrell December 7, 2017

Transcription

1 rid Graphics Paul Murrell December 7, 7 rid is a low-level raphics system which provides a reat deal of control and flexibility in the appearance and arranement of raphical output. rid does not provide hih-level functions which create complete plots. What it does provide is a basis for developin such hih-level functions (e.., the lattice and plot packaes), the facilities for customisin and manipulatin lattice output, the ability to produce hih-level plots or non-statistical imaes from scratch, and the ability to add sophisticated annotations to the output from base raphics functions (see the ridbase packae). This document provides an introduction to the fundamental concepts underlyin the rid packae: viewports, units, and raphical parameters. There are also several examples to demonstrate what can be achieved and how to achieve it. The description of the fundamental rid concepts is predicated on the followin approach to constructin a statistical raphic (plot). You must be able to:. create and control different raphical reions and coordinate systems.. control which raphical reion and coordinate system raphical output oes into. 3. produce raphical output (lines, points, text,... ) includin controllin its appearance (colour, line type, line width,... ). Creatin and Controllin Graphics Reions and Coordinate Systems In rid there can be any number of raphics reions. A raphics reion is referred to as a viewport and is created usin the viewport() function. A viewport can be positioned anywhere on a raphics device (pae, window,... ), it can be rotated, and it can be clipped to. The followin code describes a viewport which is centred within the pae, and is half the width of the pae, one quarter of the heiht of the pae, and rotated 45 ; Fiure shows a diaram of this viewport. > viewport(x =.5, y =.5, width =.5, heiht =.5, anle=45) The object returned by the viewport() function is only a description of a raphics reion. A raphics reion is only created on a raphics device when a viewport is pushed onto that device. This is achieved usin the pushviewport() function. Each device has only one current viewport (by default this is the entire device surface), but it maintains a tree

2 of viewports that have been pushed. The current viewport is a node on the viewport tree. The pushviewport() function adds a viewport as a leaf of the tree the previous current viewport becomes the parent of this leaf and the new leaf becomes the current viewport. The popviewport() function prunes the current viewport (and all its children) from the tree the parent of the pruned leaf becomes the current viewport. The function upviewport() acts like popviewport() in terms of settin the current viewport, but does not prune the previous current viewport. The downviewport() function naviates down the tree to a viewport which has been specified by name (it adds no new viewports to the tree). This means that there is always only one raphics reion selected to draw into, but it is possible to return to a previous raphics reion throuh the appropriate set of push/pop/up/down operations. As an example, the followin code creates a raphics reion in the top-left corner of the pae usin pushviewport(). This viewport is iven the name "vp". It then does some drawin and calls upviewport() to return to the root of the viewport tree. Next, it creates another reion in the bottom-riht corner of the pae (aain usin pushviewport()) and does some drawin there. Finally, it performs an upviewport() to the root of the tree and a downviewport() to return to the first raphics reion and does some more drawin there (see Fiure ). > rid.rect(p = par(lty = "dashed")) > vp <- viewport(x =, y =.5, w =.5, h =.5, + just = c("left", "bottom"), name = "vp") > vp <- viewport(x =.5, y =, w =.5, h =.5, + just = c("left", "bottom")) > pushviewport(vp) > rid.rect(p = par(col = "rey")) > rid.text("some drawin in raphics reion ", y =.8) > upviewport() > pushviewport(vp) > rid.rect(p = par(col = "rey")) > rid.text("some drawin in raphics reion ", y =.8) > upviewport() > downviewport("vp") > rid.text("more drawin in raphics reion ", y =.) > popviewport() When several viewports are pushed onto the viewport tree, leaf viewports are located and sized within the context of their parent viewports. The followin code ives an example; a viewport is defined which is one-quarter the size of its parent (half the width and half the heiht), and this viewport is pushed twice. The first time it ets pushed the parent is the root of the viewport tree (which is the entire device) so it is quarter of the size of the pae. The second time the viewport is pushed, it is quarter of the size of its parent viewport. Fiure 3 shows the output of these commands. > rid.rect(p = par(lty = "dashed")) > vp <- viewport(width =.5, heiht =.5) > pushviewport(vp) > rid.rect(p = par(col = "rey")) > rid.text("quarter of the pae", y =.85) > pushviewport(vp) > rid.rect()

3 .5npc.5npc.5npc.5npc Fiure : A diaram of a simple rid viewport (produced usin the rid.show.viewport() function. Some drawin in raphics reion MORE drawin in raphics reion Some drawin in raphics reion Fiure : Definin and drawin in multiple raphics reions. 3

4 > rid.text("quarter of the\nprevious viewport") > popviewport() Each viewport has a number of coordinate systems available. The full set is described in Table, but there are four main types: absolute coordinates (e.., "inches", "cm") allow locations and sizes in terms of physical coordinates there is no dependence on the size of the pae; normalised coordinates (e.., "npc") allow locations and sizes as a proportion of the pae size (or the current viewport); relative coordinates (i.e., "native") allow locations and sizes relative to a user-defined set of x- and y-ranes; referential coordinates (e.., "strwidth") where locations and sizes are based on the size of some other raphical object. It is possible to specify the coordinate system for relative coordinates, but all other coordinate systems are implicitly defined based on the location and size of the viewport and/or the size of other raphical objects. Directin Graphics Output into Different Graphics Reions and Coordinate Systems Graphics output is always relative to the current viewport (on the current device). Selectin which reion you want is a matter of push/pop/up/downin the appropriate viewports. However, that is not all; every viewport has a number of coordinate systems associated with it, so it is also necessary to select the coordinate system that you want to work with. The selection of which coordinate system to use within the current viewport is made usin the unit() function. The unit() function creates an object which is a combination of a value and a coordinate system (plus some extra information for certain coordinate systems). Here are some examples from the help(unit) pae: > unit(, "npc") [] npc > unit(:3/4, "npc") [].5npc.5npc.75npc > unit(:3/4, "npc")[] [].5npc > unit(:3/4, "npc") + unit(, "inches") [].5npc+inches.5npc+inches.75npc+inches > min(unit(.5, "npc"), unit(, "inches")) [] min(.5npc, inches) 4

5 Coordinate System Name Description "npc" Normalised Parent Coordinates. Treats the bottom-left corner of the current viewport as the location (, ) and the top-riht corner as (, ). "native" Locations and sizes are relative to the x- and y- scales for the current viewport. "inches" Locations and sizes are in terms of physical inches. For locations, (, ) is at the bottom-left of the viewport. "cm" Same as "inches", except in centimetres. "mm" Millimetres. "points" Points. There are 7.7 points per inch. "bipts" Bi points. There are 7 bi points per inch. "picas" Picas. There are points per pica. "dida" Dida. 57 dida equals 38 points. "cicero" Cicero. There are dida per cicero. "scaledpts" Scaled points. There are scaled points per point. "char" Locations and sizes are specified in terms of multiples of the current nominal fontheiht. "lines" Locations and sizes are specified in terms of multiples of the heiht of a line of text (dependent on both the current fontsize and the current lineheiht). "snpc" Square Normalised Parent Coordinates. Locations and size are expressed as a proportion of the smaller of the width and heiht of the current viewport. "strwidth" Locations and sizes are expressed as multiples of the width of a iven strin (dependent on the strin and the current fontsize). "strheiht" Locations and sizes are expressed as multiples of the heiht of a iven strin (dependent on the strin and the current fontsize). "robwidth" Locations and sizes are expressed as multiples of the width of a iven raphical object (dependent on the current state of the raphical object). "robheiht" Locations and sizes are expressed as multiples of the heiht of a iven raphical object (dependent on the current state of the raphical object). Table : The full set of coordinate systems available in rid viewports. 5

6 > unit.c(unit(.5, "npc"), unit(, "inches") + unit(:3/4, "npc"), + unit(, "strwidth", "hi there")) [].5npc inches+.5npc inches+.5npc [4] inches+.75npc strwidth Notice that unit objects are treated much like numeric vectors. You can index a unit object, it is possible to do simple arithmetic (includin min and max), and there are several unitversions of common functions (e.., unit.c, unit.rep, and unit.lenth; unit.pmin, and unit.pmax)). rid functions that have aruments specifyin locations and sizes typically assume a default coordinate system is bein used. Most often this default is "npc". In other words, if a raw numeric value, x, is specified this is implicitly taken to mean unit(x, "npc"). The viewport() function is one that assumes "npc" coordinates, so in all of the viewport examples to this point, we have only used "npc" coordinates to position viewports within the pae or within each other. It is also possible to position viewports usin any of the coordinate systems described in Table. As an example, the followin code makes use of "npc", "native", "inches", and "strwidth" coordinates. It first pushes a viewport with a user-defined x-scale, then pushes another viewport which is centred at the x-value 6 and half-way up the first viewport, and is 3 inches hih and as wide as the text coordinates for everyone. Fiure 4 shows the resultin output. > pushviewport(viewport(y = unit(3, "lines"), width =.9, heiht =.8, + just = "bottom", xscale = c(, ))) > rid.rect(p = par(col = "rey")) > rid.xaxis() > pushviewport(viewport(x = unit(6, "native"), y = unit(.5, "npc"), + width = unit(, "strwidth", "coordinates for everyone"), + heiht = unit(3, "inches"))) > rid.rect() > rid.text("coordinates for everyone") > popviewport() If you want to check the fiure, the scalin factor is 3.5/6 (i.e., the rectanle in the fiure should be.75" or 3.94cm hih). 6

7 quarter of the pae quarter of the previous viewport Fiure 3: The result of pushin the same viewport onto the viewport stack twice. coordinates for everyone Fiure 4: A viewport positioned usin a variety of coordinate systems. 7

8 Fiure 5: A viewport positioned usin a layout.. Layouts rid provides an alternative method for positionin viewports within each other based on layouts. A layout may be specified for any viewport. Any viewport pushed immediately after a viewport containin a layout may specify its location with respect to that layout. In the followin simple example, a viewport is pushed with a layout with 4 rows and 5 columns, then another viewport is pushed which occupies the second and third columns of the third row of the layout. > pushviewport(viewport(layout = rid.layout(4, 5))) > rid.rect(p = par(col = "rey")) > rid.sements(c(:4/5, rep(, 3)), c(rep(, 4), :3/4), + c(:4/5, rep(, 3)), c(rep(, 4), :3/4), + p = par(col = "rey")) > pushviewport(viewport(layout.pos.col = :3, layout.pos.row = 3)) > rid.rect(p = par(lwd = 3)) > popviewport() Layouts introduce a special sort of unit called "null". These can be used in layouts to specify relative column-widths or row-heihts. In the followin, slihtly more complex, example, the layout specifies somethin similar to a standard plot arranement; there are bottom and left marins 3 lines of text wide, top and riht marins cm wide, and two rows and columns within these marins where the bottom row is twice the heiht of the top row (see Fiure 6). The primary reference for layouts is []. Layouts in rid represent an extension of the idea to allow a reater rane of units for specifyin row heihts and column widths. rid also differs in the way that children of the layout specify their location within the layout. 8

9 3lines null null cm cm (, ) (, ) (, 3) (, 4) cm null (, ) (, ) (, 3) (, 4) null null (3, ) (3, ) (3, 3) (3, 4) null 3lines (4, ) (4, ) (4, 3) (4, 4) 3lines 3lines null null cm Fiure 6: A more complex layout. > rid.show.layout(rid.layout(4, 4, widths = unit(c(3,,, ), + c("lines", "null", "null", "cm")), + heihts = c(,,, 3), + c("cm", "null", "null", "lines"))) 9

10 3 Producin Graphics Output rid provides a standard set of raphical primitives: lines, text, points, rectanles, polyons, and circles. There are also two hiher level components: x- and y-axes. Table lists the rid functions that produce these primitives. NOTE: all of these raphical primitives are available in all raphical reions and coordinate systems. There used to be (prior to R.3.) a separate rid.arrows() function, but this has been superseded by an arrow arument to the line-drawin primitives (lines, sements, line-to). rid.text rid.rect rid.circle rid.polyon rid.points rid.lines rid.sements rid.rill rid.move.to rid.line.to rid.xaxis rid.yaxis Can specify anle of rotation. Can specify type of plottin symbol. Convenience function for drawin rid lines Top or bottom axis Left or riht axis Table : rid raphical primitives. 3. Controllin the Appearance of Graphics Output rid reconises a fixed set of raphical parameters for modifyin the appearance of raphical output (see Table 3). col colour of lines, text,... fill colour for fillin rectanles, circles, polyons,... lwd line width lty line type fontsize The size of text (in points) fontface The font face (bold, italic,... ) fontfamily The font family Table 3: rid raphical parameters. Graphical parameter settins may be specified for both viewports and raphical objects. A raphical parameter settin for a viewport will hold for all raphical output within that viewport and for all viewports subsequently pushed onto the viewport stack, unless the raphical object or viewport specifies a different parameter settin. A description of raphical parameter settins is created usin the par() function, and this description is associated with a viewport or a raphical object via the p arument. The followin code demonstrates the effect of raphical parameter settins (see Fiure 7).

11 This text and the inner rectanle have specified their own par settins This text and the outer rectanle accept the par settins of the viewport Fiure 7: The effect of different raphical parameter settins. > pushviewport(viewport(p = par(fill = "rey", fontface = "italic"))) > rid.rect() > rid.rect(width =.8, heiht =.6, p = par(fill = "white")) > rid.text(paste("this text and the inner rectanle", + "have specified their own par settins", sep = "\n"), + y =.75, p = par(fontface = "plain")) > rid.text(paste("this text and the outer rectanle", + "accept the par settins of the viewport", sep = "\n"), + y =.5) > popviewport()

12 4 Examples The remainin sections provide some code examples of the use of rid. The first example constructs a simple scatterplot from first principles. Just like in base raphics, it is quite straihtforward to create a simple plot by hand. The followin code produces the equivalent of a standard plot(:) (see Fiure 8). > rid.rect(p = par(lty = "dashed")) > x <- y <- : > pushviewport(plotviewport(c(5., 4., 4.,.))) > pushviewport(dataviewport(x, y)) > rid.rect() > rid.xaxis() > rid.yaxis() > rid.points(x, y) > rid.text(":", x = unit(-3, "lines"), rot = 9) > popviewport() Now consider a more complex example, where we create a barplot with a leend (see Fiure 9). There are two main parts to this because rid has no predefined barplot function; the construction of the barplot will itself be instructive, so we will start with just that. The data to be plotted are as follows: we have four measures to represent at four levels; the data are in a matrix with the measures for each level in a column. > bardata <- matrix(sample(:4, 6, replace = TRUE), ncol = 4) We will use colours to differentiate the measures. > boxcolours <- :4 We create the barplot within a function so that we can easily reproduce it when we combine it with the leend. > bp <- function(bardata) { + nbars <- dim(bardata)[] + nmeasures <- dim(bardata)[] + bartotals <- rbind(rep(, nbars), apply(bardata,, cumsum)) + baryscale <- c(, max(bartotals)*.5) + pushviewport(plotviewport(c(5, 4, 4, ), + yscale = baryscale, + layout = rid.layout(, nbars))) + rid.rect() + rid.yaxis() + for (i in :nbars) { + pushviewport(viewport(layout.pos.col = i, yscale = baryscale)) + rid.rect(x = rep(.5, nmeasures), + y = unit(bartotals[:nmeasures, i], "native"), + heiht = unit(diff(bartotals[,i]), "native"),

13 + width =.8, just = "bottom", p = par(fill = boxcolours)) + popviewport() + } + popviewport() + } Now we turn our attention to the leend. We need some labels and we will enforce the constraint that the boxes in the leend should be.5" square: > lelabels <- c("group A", "Group B", "Group C", "Somethin Loner") > boxsize <- unit(.5, "inches") The followin draws the leend elements in a column, with each element consistin of a box with a label beneath. > le <- function(lelabels) { + nlabels <- lenth(lelabels) + pushviewport(viewport(layout = rid.layout(nlabels, ))) + for (i in :nlabels) { + pushviewport(viewport(layout.pos.row = i)) + rid.rect(width = boxsize, heiht = boxsize, just = "bottom", + p = par(fill = boxcolours[i])) + rid.text(lelabels[i], y = unit(.5, "npc") - unit(, "lines")) + popviewport() + } + popviewport() + } Now that we have the two components, we can arrane them toether to form a complete imae. Notice that we can perform some calculations to make sure that we leave enouh room for the leend, includin line of text as left and riht marins. We also impose top and bottom marins on the leend to match the plot marins. > rid.rect(p = par(lty = "dashed")) > leend.width <- max(unit(rep(, lenth(lelabels)), + "strwidth", as.list(lelabels)) + + unit(, "lines"), + unit(.5, "inches") + unit(, "lines")) > pushviewport(viewport(layout = rid.layout(,, + widths = unit.c(unit(,"null"), leend.width)))) > pushviewport(viewport(layout.pos.col = )) > bp(bardata) > popviewport() > pushviewport(viewport(layout.pos.col = )) > pushviewport(plotviewport(c(5,, 4, ))) > le(lelabels) > popviewport(3) 3

14 8 : Fiure 8: The rid equivalent of plot(:). Group A 8 6 Group B 4 Group C Somethin Loner Fiure 9: A barplot plus leend from first principles usin rid. 4

15 5 rid and lattice The lattice packae is built on top of rid and provides a quite sophisticated example of writin hih-level plottin functions usin rid. Because lattice consists of rid calls, it is possible to both add rid output to lattice output, and lattice output to rid output. Addin rid to lattice Panel functions in lattice can include rid calls. The followin example adds a horizontal line at to a standard xyplot (see Fiure ): > xyplot(y ~ x, panel = function(x, y) { + panel.xyplot(x, y); + rid.lines(unit(c(, ), "npc"), unit(, "native"), + p = par(col = "rey")) + }) The followin example writes a left-justified label in each strip (see Fiure ): > xyplot(y ~ x, strip = function(which.iven, which.panel,...) { + rid.text(paste("variable ", which.iven, ": Level ", + which.panel[which.iven], sep = ""), + unit(, "mm"),.5, just = "left") + }) Addin lattice to rid It is also possible to use a lattice plot as an element of a rid imae. The followin example splits up the pae so that there is an xyplot beside a panel of text (see Fiure ). First of all, the lattice plot is created, but not drawn. rid is used to create some reions and the lattice plot is drawn into one of those reions. > sometext <- paste("a panel of text", "produced usin", "raw rid code", + "that could be used", "to describe", + "the plot", "to the riht.", sep = "\n") > latticeplot <- xyplot(y ~ x, layout = c(, 4)) > rid.rect(p = par(lty = "dashed")) > pushviewport(viewport(layout = rid.layout(,, + widths = unit.c(unit(, "strwidth", sometext) + + unit(, "cm"), + unit(, "null"))))) > pushviewport(viewport(layout.pos.col = )) > rid.rect(p = par(fill = "liht rey")) > rid.text(sometext, + x = unit(, "cm"), y = unit(, "npc") - unit(, "inches"), + just = c("left", "top")) > popviewport() > pushviewport(viewport(layout.pos.col = )) 5

16 x y Fiure : A lattice panel function usin rid. x y 3 Variable : Level Variable : Level Variable : Level 3 Variable : Level 4 Variable : Level 5 3 Variable : Level 6 3 Variable : Level 7 Variable : Level 8 Fiure : A lattice strip function usin rid. 6

17 A panel of text produced usin raw rid code that could be used to describe the plot to the riht. y x Fiure : A lattice plot used as a component of a larer rid imae. > print(latticeplot, newpae = FALSE) > popviewport() References [] Paul R. Murrell. Layouts: A mechanism for arranin plots on a pae. Journal of Computational and Graphical Statistics, 8: 34,