prepplot: Functions to prepare a figure region for base graphics

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/prepplot.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
prepplot(xlim, ylim,                      
       bg = "grey92", 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 = "grey98",
       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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
## 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")

prepplot documentation built on May 1, 2019, 9:24 p.m.