tile: Plot a tiled graphical layout

In chrisadolph/tileForShiny: Plot multiple graphical displays in a tiled layout with automated or customizable titles, axes, and annotations

Description

A generic layout function for plotting tiled arrangements of graphic styles found in the tile package, including scatterplots, lineplots, dotplots and more specialized formats. Includes fine control of titles, axes, axis transformation, and rugs for all plots.

Usage

tile(..., limits = NULL, frame = FALSE, gridlines = list(),
     xaxis = list(), yaxis = list(), topaxis = list(), rightaxis = list(),
     xaxistitle = list(), yaxistitle = list(), topaxistitle = list(), rightaxistitle = list(),
     maintitle = list(), rowtitle = list(), columntitle = list(), plottitle = list(), undertitle = list(),
     RxC=NULL, output = list(), width = list(), height = list(),
     leeway = 0, draw = FALSE, defaults = list(), 
     layoutonly = FALSE, titleboxes = FALSE, axisboxes = FALSE, verbose = FALSE)

Arguments

...	Any number of “traces”, or lists of traces, as supplied by tile graphic functions such as lineplot, scatter, ropeladder, nightplot, riceplot, linesTile, pointsTile, textTile, polylinesTile, or polygonTile
limits	A vector or matrix giving the limits of the plotting region, similar to usr for base graphics, but generalized to the four axis set-up of tile. The usual case is an 8-vector, c(xmin, xmax, ymin, ymax, topmin, topmax, rightmin, rightmax). If no plots have right axes, this could be a 6-vector; if none have right or top axes, it could be a 4-vector, and so on. If an element of limits is NA, then that limit is automatically computed based on the data plotted. If no limits are provided, all limits are computed. To set different limits for each plot, provide a matrix with one row of limits for each plot; otherwise, the same limits are plotted (and, if necessary, computed) for all plots.
frame	Logical; draw a frame around plots (use a vector to set for specific plots). Default is FALSE.
gridlines	A list controlling the printing of gridlines in the plotting regions. Each input may be a scalar (to set the parameter globally for all plots) or a vector (to set the parameter plot by plot). Alternatively, for multiplot layouts you may specify, e.g., separate types for plot 1 by providing type1, separate colors for plot 3 using col3, etc. Plot specific values given in this way override the generic inputs. type A string containing the first letters of each axis which should have gridlines attached to its ticks; e.g., “xy” for gridlines on the x and y axes, “t” for gridlines on the top axis only, and “xytr” for all four axes. Default is no gridlines. lwd Width of gridlines. Default is 0.15. col Color of gridlines. Default is gray50. lty Line type of gridlines. Default is solid.
xaxis	A list; controls the plotting and format of the x-axes. The inputs below are generic, and apply to all plots. Alternatively, for multiplot layouts you may specify, e.g., separate labels for plot 1 by providing labels1, separate colors for plot 3 using col3, etc. Plot specific values given in this way override the generic inputs. This is especially helpful for changing just one plot out of a large layout, or for specifying different numbers of labels or tick locations for different plots. at Vector or matrix of locations to draw ticks. If a matrix, at should have one row for each plot; NAs are ignored. Default is to have tile select at automatically. labels Vector or matrix of labels to apply at tick locations. If a matrix, labels should contain one row for each plot. Default is to use at. tick.length Length of ticks in lines. For ticks facing into the plot, use positive values. For ticks facing out of the plot, use negative values. Default is -0.5. label.loc Location of tick labels relative to axis baseline. Default is 1.25. ticks Show tick marks. Default is TRUE. ntics If ticks are automatic, how many to draw? Default is 5. major Logical, indicating whether to plot the main axis line. Default is TRUE. col Color for all axis elements. Default is black. lwd Line width of axis elements. Default is 0.5. cex Degree of text and symbol magnification. Default is 1. rot Rotation of tick labels in degrees. Default is 0, for no rotation. 90 and 270 should also work well. Non-right angles may work, but might lead to unexpected errors in alignment of plot elements. fontsize Fontsize of tick labels. Default is XXX. add Logical indicating whether this axis be drawn. May be a vector with values for each plot. Default is for tile to include an axis in a plot only if data are plotted to that axis. log Logical or numeric which indicates whether this axis should be logged. May be FALSE, for no logging, TRUE, for natural log scaling, or a positive number, which indicates the logathrmic base for a scale other than the natural log. Default is FALSE.
yaxis	A list; controls the plotting and format of the y-axes; see xaxis for parameters.
topaxis	A list; controls the plotting and format of the top-axes; see xaxis for parameters.
rightaxis	A list; controls the plotting and format of the right-axes; see xaxis for parameters.
xaxistitle	A list; places titles for the x-axes and controls their format. These inputs should be scalar if the same treatment is desired for the titles of different plots, or vector if different results are desired for each title (type, of course, must be scalar, as it applies to the whole layout). Alternatively, for multiplot layouts you may specify, e.g., separate labels for plot 1 by providing labels1, separate colors for plot 3 using col3, etc. Plot specific values given in this way override the generic inputs. This is especially helpful for changing just one plot out of a large layout. labels The text labels for each title. User may provide a single title, which will then be repeated for each plot (unless the user also sets type to something other than "all".) Or user may provide a vector of titles, one for each plot. Default is not to print titles. cex Magnification of title text. Default is 1. col The color of the titles. Default is black. fontsize The fontsize of the title. Default for x-axis titles is XXX. Varies by kind of title. fontface The fontface of the title. Default is plain. rot Rotation of the title; one of 0, 90, 180, or 270. Default varies by type of axis. x Horizontal position of the title relative to the title viewport, in npc. Default is 0.5, the middle of the viewport. y Vertical position of the title relative to the title viewport, in npc. Default is 0.5, the middle of the viewport. type Character; indicates whether the titles should appear on all plots, only the first plot, only in the first plot of each row of plots, or only the first plot of each column of plots. The default depends on the length of label: if 1 or as long as the number of plots, each plot gets a title; if label is as long as the number of rows or columns, then only first row or column gets a title. add Logical indicating whether the title should be plotted. Will be set to TRUE if labels are given. A vector input can selectively turn on and off titles by plot.
yaxistitle	A list; places titles for the y-axes and controls their format; see xaxistitle for parameters.
topaxistitle	A list; places titles for the top-axes and controls their format; see xaxistitle for parameters.
rightaxistitle	A list; places titles for the right-axes and controls their format; see xaxistitle for parameters.
maintitle	A list; places a single title above the entire graphic and controls its format. See xaxistitle for parameters.
rowtitle	A list; places titles to the left of each row of plots and controls their format. See xaxistitle for parameters.
columntitle	A list; places titles above each column of plots and controls their format. See xaxistitle for parameters.
plottitle	A list; places titles above each plot and controls their format. See xaxistitle for parameters.
undertitle	A list; places titles below each plot and controls their format. See xaxistitle for parameters.
RxC	A 2-vector giving the number of rows and columns of the tiling of plots. Default is to place all plots in a single row.
output	A list controlling the output device: file Name of the file where the graphic is to be saved. An appropriate extension is applied automatically. width Width of the entire graphic, in inches. If provided, plot height is calculated automatically based on width and the provided tiling and titles. If width is not provided, tile will automatically select a width for the graphic by allocating a fixed number of inches of width for each graphic (see option null under the main input list width below). pointsize Pointsize for the device. Default is 12. family Font family for the device. Default is Helvetica. type Device type: choices include pdf, postscript, png, jpeg, bmp, bitmap, win.metafile, xfig, pictex, CairoPDF, CairoPS (the latter two require the Cairo package be installed). Leave as NULL to plot to the default device (usually the screen). Default is pdf. See Devices in package grDevices for details. res The resolution of raster graphics (jpeg, bmp, png) in dpi. Default is 300. units The units of width. Default is inches.
width	A list of widths of various plot elements. Modify these to improve the look of spacing of plots and titles, or to expand the width of plotting areas. null Width of plotting areas in inches per null. Default is 2. Multiplies by the width in nulls for each plot. Setting this parameter ensures a fixed width in inches for each plot in the tiling, and can help if your plotting areas appear too small or too large. This parameter is overriden if the user fixes the overall width of the graphic using the width argument to output, in which case the plotting area widths are calculated automatically from the space left over after titles are created. plot Width of the plotting areas in nulls (see unit). May be a vector. Default is 1. Higher values stretch plots horizontally; lower values to squeeze them relative to titles and layout elements. The aspect ratio of the plots is ratio of the plot height to this number. Ordinarily, this parameter should only be changed if users want different widths for different plots (in which case this should be a vector); otherwise, use the plot height to adjust the aspect ratio, and the width of a null (immediately above) to set the width of plots in inches. spacer Width of the space between each column of plots, or between the right-axis titles and y-axis titles, if present. Default is 2. Measured in char units (see unit). Higher values increase the whitespace between plots and can remove overlap between stray tick labels. leftborder Width of the space before the first column of plots, or before the row titles, if present. Default is 2. Measured in char units (see unit). Higher values increase the whitespace before the first column and can eliminate clipping of tick labels on the edge of the graphic. rightborder Width of the space after the final column of plots, or after the final column's right-axis titles, if present. Default is 2. Measured in char units (see unit). Higher values increase the whitespace after the final column and can eliminate clipping of tick labels on the edge of the graphic. rowtitle Width of the column of rowtitles, as a multiple of the widest rowtitle string width. Default is 1.25. yaxistitle Width of y-axis titles, as a multiple of the width of the widest title. Default is 2. Because y-axis titles are usually rotated 90 degrees, this usually multiplies the string height. rightaxistitle Width of right-axis titles, as a multiple of the width of the widest title. Default is 2. Because right-axis titles are usually rotated 90 degrees, this usually multiplies the string height. yaxis.labelspace Width of space between y-axis tick marks and tick labels, as a multiple of the width of the tick labels. Default is 0.5. rightaxis.labelspace Width of space between right-axis tick marks and tick labels, as a multiple of the width of the tick labels. Default is 0.5.
height	A list of heights of various plot elements. Modify these to improve the look of spacing of plots and titles, or to change the aspect ratio of plotting areas. plot Height of the plotting areas in nulls (see unit); if the width of the plot is set to 1 null (the default), then this parameter directly sets the aspect ratio. May be a vector. Default is 1. Higher values stretch plots vertically; lower values to squeeze them relative to titles and layout elements, but may be non-numeric: “square” will set the aspect ratio to be 1:1 regardless of the plot width, and “golden” will set plotting area to be a golden rectangle. spacer Height of the space between each row of plots, or between the x-axis titles and top-axis titles, if present. Default is 2. Measured in char units (see unit). Higher values increase the whitespace between plots and can remove overlap between stray tick labels. topborder Width of the space before the first row of plots, or before the main title, if present. Default is 2. Measured in char units (see unit). Higher values increase the whitespace before the first row and can eliminate clipping of tick labels on the edge of the graphic. bottomborder Width of the space after the final row of plots, or after the final row's under titles, if present. Default is 2. Measured in char units (see unit). Higher values increase the whitespace after the final row and can eliminate clipping of tick labels on the edge of the graphic. maintitle Height of the main title, as a multiple of the maintitle string height. Default is 3. columntitle Height of the row of column titles, as a multiple of the tallest columntitle string height. Default is 1.5. plottitle Height of the plot titles, as a multiple of the tallest plot title string height. Default is 1.5. undertitle Height of the under titles, as a multiple of the tallest under title string height. Default is 1.5. xaxistitle Height of x-axis titles, as a multiple of the height of the tallest title. Default is 2. topaxistitle Height of top-axis titles, as a multiple of the height of the tallest title. Default is 2. xaxis.labelspace Height of space between x-axis tick marks and tick labels, as a multiple of the height of the tick labels. Default is 0.75. topaxis.labelspace Height of space between top-axis tick marks and tick labels, as a multiple of the height of the tick labels. Default is 0.75.
leeway	When finding plot region limits automatically, add a little leeway beyond data limits. Default is 0.
draw	Logical indicating whether a copy of the plot should be plotted to the current screen device, in addition to the device specified in output. Default is FALSE. Will plot over any content on current screen.
defaults	List object with default settings for title heights and widths, and other tile parameters. Users will not normally need to changes these settings.
layoutonly	Logical. If TRUE, tile will draw only axes, titles, and frames, but no data. Intended only as a diagnostic. Default is FALSE.
titleboxes	Logical. Draws boxes around title plotting areas. Helpful as a diagnostic for poorly behavied layouts; not intended for final plots. Default is FALSE.
axisboxes	Logical. Draws boxes around axis plotting areas. Helpful as a diagnostic for poorly behavied layouts; not intended for final plots. Default is FALSE.
verbose	Logical. If TRUE, tile displays a progress report for error checking. Default is FALSE.

Details

With the tile package, you can not only create elegant graphical displays of data, but also of the quantitative implications of fitted regression models. In particular, the package makes it easy to repeat the same graphic in a tiled arrangement (small multiples), and always allows for the inclusion of confidence intervals around any plotted quantity.

A typical script producing a tile graphic follows three steps:

1. Obtain data to plot. These data may be the underlying variables of interest, or quantities inferred from models. (For this step, you should use your own modeling code, or a package for extracting counterfactual inferences from a model, such as Zelig or simcf.) For example, you may have a set of expected values of a response variable calculated conditional on different hypothetical values of covariates, and may wish to plot those expected values along with their confidence intervals. Or you might have the actual draws from posterior distributions, and decide to leave the summary of those draws by confidence intervals up to graphing function.

2. Create traces from the data. A trace is a single set of data to be added to the plot, and may be as simple as a text label or a line segment, or as complex as a set of points combined their best fit line and shaded confidence region. All the parameters affecting the construction and appearance of the trace are set using one of the many functions in the tile package. These include several functions for creating primitives (analogous to grid functions):

   linesTile	Plot a set of connected line segments
   pointsTile	Plot a set of points
   polygonTile	Plot a shaded region
   polylinesTile	Plot a set of unconnected line segments
   textTile	Plot text labels

   And several functions for constructing complex traces for model or data exploration:

   lineplot	Plot lines with confidence intervals, extrapolation warnings
   nightplot	(Experimental) Plot bounded quantites using equal-area lozenges
   riceplot	(Experimental) Plot up to five dimensions to a 2D scatter
   ropeladder	Plot dotplots with confidence intervals, extrapolation warnings,
   	and shaded ranges
   scatter	Plot scatterplots with text and symbol markers,
   	fit lines, and confidence intervals

   This is the point to tweak the look of the plotted data and annotations—essentially, anything inside the plotted areas of the tiled plots. (Rugs, which technically lie along the outer borders of plots, also get set up at this stage. To add a rug, create a trace using rugTile.)

3. Create the tiled graphic. Finally, give all the traces as inputs to a single call to tile. At this point, you can customize the look of the plotting framework: inputs to tile let you change the rows and columns of tiled plots; include, scale, and label ticks for any axes on any plots; add and format titles of axes, plots, rows of plots, or columns of plots; and add and customize gridlines and frames around plots. This is also the time to select the graphical device on which to save the graph.

tile follows a draw-at-once philosophy. No drawing takes place until the user provides all the traces to tile. Considering the entire graphic at once, tile determines how to allocate space in the graphic to each of the tiled plots, axes, and titles. Only then are the elements in the graphic drawn, in the order specified by the layer of each graphical object. As a result, it is not easy to modify or annotate an existing graphic from the R command line. Instead, if you desire to modify a plot, you should modify the traces used to create the graphic, and re-run tile to create the graphic anew.

Value

tile is mainly called for the side-effect of saving a graphic to the requested device. However, it does return a list containing all the user inputs, default settings, and numerous internal values. This list contains a copy of the entire plot in the slot grob. To draw this graphical object to the current device, give the output from tile as input to tileDraw.

Author(s)

Christopher Adolph [e-mail]

References

Murrell, Paul. (2006) R Graphics. Chapman \& Hall/CRC.

See Also

lineplot, scatter, ropeladder, nightplot, riceplot, rugTile, linesTile, pointsTile, textTile, polylinesTile, polygonTile

Examples

# Example 1:  A tile layout template

trace1 <- textTile("Plot Area 1", x=500, y=50, plot=1)
trace2 <- textTile("Plot Area 2", top=500, right=50, plot=2)
trace3 <- textTile("Plot Area 3", x=500, y=50, plot=3)
trace4 <- textTile("Plot Area 4", top=500, right=50, plot=4)
trace5 <- textTile("Plot Area 5", x=500, y=50, plot=5)
trace6 <- textTile("Plot Area 6", top=500, right=50, plot=6)

at.x <- c(1,5,10,20,35)
at.y <- c(0,0.2,0.4,0.6,0.8,1)

tc <- tile(trace1,
           trace2,
           trace3,
           trace4,
           trace5,
           trace6,

           # Plotting options
           RxC=c(2,3),             # Tile 2 rows & 3 columns of plots
           
           gridlines=list(type="xytr"),

           limits=c(0.1,1000,        # min(x), max(x)
                    0,100,           # min(y), max(y)
                    0.1,1000,        # min(top), max(top)
                    0,100),          # min(right), max(right)
           
           xaxis=list(            # User provided tick locations
             log1=10,
             log3=10,
             log5=10
             ),
           
           xaxistitle=list(labels1="X Axis 1",
             labels3="X Axis 3",
             labels5="X Axis 5"),

           topaxis=list(at=at.x,            # User provided tick locations
                        log1=10,
                        log3=10,
                        log5=10
                        ),
 
           topaxistitle=list(labels2="Top Axis 2",
             labels4="Top Axis 4",
             labels6="Top Axis 6"),

           yaxistitle=list(labels1="Y Axis 1",
             labels3="Y Axis 3",
             labels5="Y Axis 5"),
 
           rightaxistitle=list(labels2="Right Axis 2",
             labels4="Right Axis 4",
             labels6="Right Axis 6"),
           
           plottitle=list(fontface="bold",
                          labels=c("Plot Title 1",
                                   "Plot Title 2",
                                   "Plot Title 3",
                                   "Plot Title 4",
                                   "Plot Title 5",
                                   "Plot Title 6")
                          ),
           
           maintitle=list(fontface="bold",
                          labels=c("Main title")
                          ),
           
           rowtitle=list(labels=c("Row Title 1",
                                  "Row Title 2")
                         ),
           
           columntitle=list(labels=c("Column Title 1",
                                     "Column Title 2",
                                     "Column Title 3")
                                     ),
           
           undertitle=list(fontface="italic",
                           labels=c("Under Title 1",
                                    "Under Title 2",
                                    "Under Title 3",
                                    "Under Title 4",
                                    "Under Title 5",
                                    "Under Title 6")
                           ),

           frame=TRUE,
           output = list(file="tile2x3layout")
           )


# Example 2:  Small multiples


# Example 3:  A multi-trace layout

chrisadolph/tileForShiny documentation built on Feb. 6, 2022, 12:34 a.m.