Package 'prepplot'

Functions to prepare a figure region for base graphics

Description

Function prepplot prepares a figure region according to individual preferences regarding background color, axes, stripes and/or gridlines; optionally, labelling can be done with the function. Function stripes draws the vertical or horizontal stripes for prepplot and can also be used independently.

Usage

prepplot(xlim, ylim,                      
       bg = par("bg"), xaxs=NULL, yaxs=NULL, 
       lwd.axis = 0, col.axis = "grey20",  
       border = ifelse(lwd.axis == 0, bg, col.axis),
       axes = TRUE, xaxt = par("xaxt"), yaxt = par("yaxt"), 
       xticks = NULL, yticks = NULL, 
       xticklabs = xticks, yticklabs = yticks, 
       mgpx = par("mgp"), xaxside = 1, 
       mgpy = mgpx, yaxside = 2,
       xlab = NULL, ylab = NULL, 
       cex = par("cex"), las = 1, lasx = las, lasy = las, 
       gridx = FALSE, gridy = FALSE,
       gridxminor = 0, gridyminor = 0,
       lty.grid = ifelse(max(gridxminor, gridyminor) > 0, 
                         "solid", "dotted"),
       col.grid = "grey50", 
       lwd = par("lwd"), lwd.grid = lwd,
       lty.grid.minor = "dotted", 
       col.grid.minor = col.grid, 
       lwd.grid.minor = 0.5 * lwd.grid,
       stripesx = FALSE, stripesy = FALSE,
       col.stripes = "grey90",
       axis.arrow = FALSE,
       arrow.length = 0.3, arrow.width = 0.2, 
       arrow.code = 2, arrow.type = "triangle", ...)

stripes(stripesx = numeric(0), stripesy = numeric(0), col.stripes = "grey90", 
       usr=NULL, ...)

Arguments

xlim	required; a numeric vector of length 2 or more, whose range will be used for the horizontal axis limits
ylim	required; a numeric vector of length 2 or more, whose range will be used for the vertical axis limits
bg	background color
xaxs	"r" for regular style (4% extended versus range(xlim)), "i" for using unextended range(xlim) NULL for using par("xaxs"), which has default "r"
yaxs	analogous to xaxs
lwd.axis	axis line width; default 0 for no axis line (see below also for lwd and lwd.grid)
col.axis	axis color; also affects ticks, tickmark labels and axis labels
border	border color; default depends on whether or not there is an axis line
axes	logical that determines whether or not axes are to be drawn (only if xaxt and yaxt do not suppress their respective axes); default: TRUE; if FALSE, both tick mark labels and axis labels are suppressed; even if TRUE, an axis line is only drawn, if lwd.axis is set to a positive value; if the default axis positioning of R itself is desired, choose axes=FALSE, and add an axis statement after the preplot call (see also the Examples section)
xaxt	default: par("xaxt"); set to "n" for suppressing the x axis in spite of "axes=TRUE" (you can add a horizontal axis with the axis command later on, see examples section)
yaxt	default: =par("yaxt"); set to "n" for suppressing the y axis in spite of "axes=TRUE" (you can add a vertical axis with the axis command later on, see examples section)
xticks	tick positions for the horizontal axis; default NULL (see Details section)
yticks	tick positions for the vertical axis; default NULL (see Details section)
xticklabs	tick labels for the horizontal axis; default xticks; if explicitly provided, must have the same length as the xticks values derived from xticks, gridx or stripesx (see Details section)
yticklabs	tick labels for the vertical axis; default yticks; if explicitly provided, must have the same length as the yticks values derived from yticks, gridy or stripesy (see Details section)
mgpx	position of the horizontal axis label, tick marks and line in terms of margin lines (default: par("mgp")); see Details section
xaxside	side of the horizontal axis; 1 for bottom (default), 3 for top
mgpy	analogous to mgpx, for vertical axis; default: equal to mgpx
yaxside	side of the vertical axis; 2 for left (default), 4 for right
xlab	label for horizontal axis; default: empty
ylab	label for vertical axis; default: empty
cex	general annotation size; default par("cex"); if specified, it also adapts defaults for cex.main, cex.sub, cex.axis and cex.lab, multiplying them with cex/par("cex"); these can be overruled by explicit specification in ....
las	direction of axis labeling; default: parallel to horizontal axis; you may want to change this to 0 (parallell to axes) in case of longer y-axis labels
lasx	direction of tick labels for horizontal axis; default: equal to las; note that xlab remains parallel to the axis, regardless of the choice for las (can only be changed by adding it later with mtext)
lasy	direction of tick labels for vertical axis; default: equal to las; note that ylab remains parallel to the axis, regardless of the choice for las (can only be changed by adding it later with mtext)
gridx	logical or numeric; if TRUE, draws grid lines at the tick mark positions; if numeric, number of grid lines between the xlim values or numeric vector of grid line positions for horizontal axis; default: FALSE for no grid lines (positive gridxminor implies switch to gridx=TRUE)
gridy	logical or numeric; if TRUE, draws grid lines at the tick mark positions; if numeric, number of grid lines between the ylim values or numeric vector of grid line positions for vertical axis; default: FALSE for no grid lines (positive gridyminor implies switch to gridy=TRUE)
gridxminor	number of minor grid lines between pairs of major grid lines for horizontal axis; default: 0 for no minor grid lines
gridyminor	number of minor grid lines between pairs of major grid lines for vertical axis; default: 0 for no minor grid lines
col.grid	color for grid lines
lty.grid	line type for (major) grid lines; defaults to a dotted line with no minor grid lines and a solid line with minor grid lines (regardless of the direction of the minor grid lines)
lwd	line width (for grid lines), default is from the current par setting
lwd.grid	line width for grid lines, default is lwd
col.grid.minor	color for minor grid lines
lty.grid.minor	line type for minor grid lines; default: dotted line
lwd.grid.minor	line width for minor grid lines (default: 0.5*lwd.grid)
stripesx	logical (default FALSE) or numeric vector of color change positions in striped background (vertical stripes with reference to horizontal axis); see Details section for further information; default: no stripes
stripesy	logical (default FALSE) or numeric vector of color change positions in striped background (horizontal stripes with reference to vertical axis); increasing size is assumed (or ascertained by sorting); see Details section for further information; default: no stripes
col.stripes	color of the stripes
axis.arrow	logical (default FALSE) or numeric vector of two positions at which to draw axis arrows for vertical and horizontal axis (first value: y position for horizontal axis, second value: x position for vertical axis); if set to TRUE, the positions are the values for xaxpos and yaxpos, respectively; for one axis arrow only, use NA for the other element
arrow.length	numeric arrow length for function Arrows; default: 0.3
arrow.width	numeric arrow width for function Arrows; default: 0.2
arrow.type	character arrow type for function Arrows; default: "triangle"
arrow.code	default: 2 (y axis arrow upwards, x axis arrow to the right); for other choices see Details section of Arrows
usr	NULL (default), or a numeric vector with limits of the area within which to draw the stripes; the default amounts to par("usr")
...	further arguments given to functions plot, mtext, stripes, axis and Arrows; these can e.g. include the option tcl for tick length.

Details

prepplot supports the preparation of a customized plot region to which the information carrying graphical elements can be added. It can be used with all functions that allow adding to existing base graphics plots (e.g. points, lines, barplot, rect, symbols, ...). Usage with other functions is also possible, but requires careful application after setting par(new=TRUE).

If an axis is not suppressed (by axes=FALSE or xaxt="n" or xaxt="n"), axis ticks are placed at the positions specified in xticks or yticks; if these are NULL, numeric specifications for gridx or gridy determine the tick positions, and if these are also non-existent, numeric specifications for stripesx or stripesy determine the tick positions. If all these are unspecified, the tick positions are determined from the default axis behavior using function axisTicks (with option log=FALSE). Per default, axis lines (whether visible or width 0) meet at the position (xlim[1], ylim[1]) (assuming 2-element limits, which are determined from longer *lim arguments with the range function, where needed); options mgpx or mgpy can be used for moving the axis line, tick labels and/or axis labels inwards or outwards; they default to the settings in par("mgp"), and it may be convenient to change that setting rather than using the option in several prepplot calls (see also Example section). Instead of specifying the labelling with function prepplot, it can also be handled by subsequent title and/or axis statements.

For grid lines, it is possible to provide minor grid lines (by specifying the number of minor grid lines between major ones); it is also possible to specify major grid lines in complete independence of the tick mark positions, e.g. for displaying information on regulatory limits, target values or specific events (on a time axis).

For stripes, specifying TRUE uses xticks or yticks values for the creation of stripes. Elements of stripes vectors that are outside their respective axis limits are silently moved to the nearest limit of the plot area (i.e. to the suitable element of usr). Note that the sorting of stripe entries should correspond to the sorting of axis limits (i.e., e.g., if xlim[1]>xlim[2], sorting is decreasing instead of increasing); elements of stripesx are sorted to conform to this rule, and duplicates are removed. If the remaining vector stripesx has an even number of elements, length(stripesx/2) vertical stripes are drawn between pairs of neighbouring stripesx elements. Otherwise, the handling depends on the first and last (sorted) element of stripesx: if the first (sorted) element equals xlim[1], a narrow stripe in the beginning is drawn, and the remaining even number of stripesx elements is treated in pairs as before; otherwise, if the last (sorted) element equals xlim[2], a narrow stripe in the end is drawn; if neither the first nor the last element coincides with an element of xlim, the last element of stripesx is simply omitted. stripesy is treated analogously to stripesy. Like gridlines, stripes can be completely independent of tick marks (see e.g. the last example).

Value

The function does not return anything; it is called for its side effects.

Author(s)

Ulrike Groemping

References

Murrell, P. (2011). R graphics. CRC, Boca Raton. https://www.stat.auckland.ac.nz/~paul/RG2e/

Rahlf, T. (2017). Data visualisation with R. Springer International Publishing AG, Cham.

See Also

See also Arrows for arrows.

Examples

## default
prepplot(0:10, -5:5)
prepplot(0:10, -5:5, xaxs="i", yaxs="i")
## with stripes and grid based on default tick positions
prepplot(0:10, -5:5, stripesy=TRUE, gridx=TRUE)

## with white background, 
## axis lines and small ticks,
## major and minor grid for y,
## and plot area defined by axis limits 
##    instead of default usr coordinates
## (border is drawn because of lwd.axis)
## mgpx moves tick position labels closer to axes
prepplot(0:10, -5:5, bg="white", xaxs="i", yaxs="i",
    lwd.axis = 1, 
    gridy=c(-5,0,5), gridyminor=4, 
    tcl=-0.2, mgpx=c(3,0.5,0))

## without axis lines but with default background
## looks better with bg.area="lim"
## unless actual data points extend to the limits
prepplot(0:10, -5:5, yticks=seq(-5,5,5), 
         gridy=-5:5, gridx=TRUE,
         xaxs="i", yaxs="i")
         
## with axis arrows
## narrower margins
## small tick marks
## tick annotations close to axis
par(mar=c(3,3,2,1), mgp=c(2,0.35,0))
prepplot(0:10, -5:5, yticks=seq(-5,5,5), 
         gridy=-5:5, gridx=TRUE, lwd.axis=1, tcl=-0.2,
         border="grey92", axis.arrow=TRUE)
dev.off()  ## eliminates modified par settings

## xaxs and yaxs set in par
## labeling subsequently or in prepplot
## mgp or mgpx used for moving labeling closer to axis
par(mfrow=c(1,2), xaxs="i", yaxs="i")
  ## adding labeling subsequently
  par(mgp=c(2.25,0.75,0))
  prepplot(0:10, -5:5, yticks=seq(-5,5,5), 
           gridy=-5:5, gridx=TRUE)
  title(xlab="x axis label", ylab="y axis label", 
  sub="Labeling added subsequently", main="mgp set in par")
  ## adding labeling subsequently
  par(mgp=c(3,1,0)) # back to default
  ## adding labeling within the function
  prepplot(0:10, -5:5, yticks=seq(-5,5,5), 
           gridy=-5:5, gridx=TRUE,
           xlab="x axis label", ylab="y axis label", 
           mgpx=c(2.25,0.75,0), 
           main="mgpx set in prepplot",
           sub="Labeling added within prepplot")
  ## the difference: sub reacts to mgp, not to mgpx
dev.off()   ## eliminates modified par settings

## further examples in the pdf vignette
## access with vignette("prepplotOverview")

---