par Graphical Parameters

DESCRIPTION

Provides control over the action of the graphics device - layout, color, etc.

USAGE

par(...)

OPTIONAL ARGUMENTS

... a list may be given as the only argument, or one or more vectors of character strings given as arguments, or any number of arguments may be in the name=value form , or no argument at all may be given. When the name=value form or a list is used, the names given should only include the names of changeable graphical parameters. See the VALUE and SIDE EFFECTS sections for explanation.

The graphical parameters are explained below:

THE PARAMETERS CATEGORIZED

Text and Symbols:
adj, cex, crt, csi, exp, font, mex, mkh, pch, smo, srt, type, xlab, ylab.
The Plot Area:
bty, new, pin, plt, pty, uin, usr, xpd, xlim, ylim. Axes and Tickmarks: axes, exp, lab, las, log, mgp, tck, xaxp, xaxs, xaxt, yaxp, yaxs, yaxt.
Margins:
mai, mar, mex, oma, omd, omi.
Figure and Page Areas:
fig, fin, fty, mfg, mfcol, mfrow, oma, omd, omi.
Miscellaneous:
ask, col, err, lty, lwd.
Information Parameters:
"1em", acc, cin, cra, cxy, dev, din, frm, omo, rsz, tsp, uin.

THE PARAMETERS

Some of the most commonly used parameters are: cex= character expansion, log= logarithmic axes, lty= line type, pch= plotting character, type= type of plot, xlab= x axis label, ylab= y axis label, xlim= range for x axis, and ylim= range for y axis.

In the following lists of parameters, the notation "c" denotes one character, i, j, m, and n are integers, L is a logical value, and x is numeric.

Several of the parameters are in (approximate) inches. One inch is equal to 2.54 centimeters.

HIGH-LEVEL PARAMETERS

The following parameters may only be used in high-level graphical functions (those that set up coordinate systems, e.g., plot, qqplot). They are not part of the result of par(), nor may they be set with a call to par.

axes=L if FALSE, suppresses all axis plotting (x, y axes and box). Useful to make a high-level plotting routine generate only the plot portion of the figure.

log="c" controls logarithmic axes. Values "xy", "x", or "y" produce log-log or log-x or log-y axes. (This causes the corresponding usr coordinates to be in units of log base 10.)

type="c" type of plot desired. Values are "p" for points, "l" for lines, "b" for both points and lines (lines miss the points), "o" for overlaid points and lines, "s" or "S" for stairsteps, "n" for no plotting, and "h" for high-density vertical line plot.

xlab="string" label for plotting below the x-axis.

xlim=c(x1,x2) approximate minimum and maximum values to be put on x-axis. These values are automatically rounded to make them "pretty" for axis labeling.

ylab="string" see xlab.

ylim=c(x1,x2) see xlim.

GENERAL PARAMETERS

The following parameters can be used in any graphical functions, including par.

adj=x string justification. 0 means left justify, 1 means right justify, .5 means to center the text. Other numbers are a corresponding distance between the extremes.

ask=L controls whether graphical device will prompt before going on to the next page/screen of output. This is mainly used on interactive devices to prevent plots from being erased before they can be studied.

bty="c" character representing the type of box. Characters "o", "l" (ell), "7", "c" will produce boxes which resemble the corresponding upper-case letters. The value "n" will suppress boxes. The default is "o".

cex=x character expansion relative to device's standard size. For example, when cex = 2, characters are twice as big as normal for the device. Some devices have only a single font, in which case cex has no effect. Other devices allow only a finite number of character sizes. This also controls the size of plotting symbols when mkh is zero (the default) and pch is a number. See also csi.

col=x color, device dependent. The default is 1. Generally, small integers are used to specify pen numbers on pen plotters, color map indices on scope devices, etc. Color 0 is background.

crt=x character rotation in degrees measured counterclockwise from horizontal. When srt is set, crt is automatically set to the same value, unless crt appears later in the command than srt. Many graphics devices ignore crt and only use srt so setting them to different values has no effect on those devices. A few graphics devices cannot rotate text or can only rotate it at multiples of 90 degrees.

csi=x height in inches of the current character set (the interline space). This is equivalent to cex - setting either changes both parameters.

err=x error mode: -1 means to not print graphics error messages (points out of bounds, etc.), 0 means to print messages (the default).

exp=x if exp=0, then axis labels in exponential notation have the "e" and the exponent on a newline. If exp is equal to 1, then such numbers are written all on one line. When exp=2 (the default), then numbers are written in the form 2*10^6.

font=i font number, device dependent. Some devices (e.g., postscript) allow this parameter to affect the font in which text is displayed.

lab=c(x,y,llen) desired number of tick intervals on the x and y axes and the length of labels on both axes. The default is c(5,5,7).

las=x style of axis labels. 0 = always parallel to axis (the default), 1 = always horizontal, 2 = always perpendicular to axis.

lty=x line type, device dependent. Normally type 1 is solid, 2 and up are dotted or dashed. A few devices have only one line type.

lwd=x line width, device dependent. Width 1 is the standard width for the device. Many devices cannot change line width.

mgp=c(x1,x2,x3) margin line for the axis title, axis labels, and axis line in units of mex (see below). The default is c(3,1,0). Larger numbers are farther from the plot region, negative numbers are inside the plot region.

mkh=x height in inches of mark symbols drawn when pch is given as a number. The default value of 0 means that the cex parameter controls the size of symbols when pch is a number (the symbol is approximately the size of a capital letter in this case).

pch="c" the character to be used for plotting points. If pch is a period, a centered plotting dot is used.

pch=n the number of a plotting symbol to be drawn when plotting points. Basic marks are: square (0); octagon (1); triangle (2); cross (3); X (4); diamond (5) and inverted triangle (6). To get superimposed versions of the above use the following arithmetic(!): 7==0+4; 8==3+4; 9==3+5; 10==1+3; 11==2+6; 12==0+3; 13==1+4; 14==0+2. Filled marks are square (15), octagon (16), triangle (17), and diamond (18). Use the mkh graphics parameter to control the size of these marks. See the EXAMPLES section for a display of the plotting symbols. Using the numbers 32 through 126 for pch yields the 95 ASCII characters from space through tilde (see the SPLUS data set font). The numbers between 161 and 252 yield characters, accents, ligatures, or nothing, depending on the font (which is device dependent).

smo=x smoothness of circles and other curves. smo is the number of rasters that the straight-line approximation to the curve is allowed to differ from the exact position of the curve. Large values produce more crude approximations to curves, but allows the curves to be drawn with fewer line segments and hence speeds up output. The minimum number of line segments that will be used for a circle is 8, regardless of smo.

srt=x string rotation in degrees measured counterclockwise from horizontal. When specified, srt sets crt to the same value; a specification of crt later in the command will over-ride this. Many graphics devices ignore crt and only use srt so setting them to different values has no effect on those devices. A few graphics devices cannot rotate text or can only rotate it at multiples of 90 degrees. The functions title and axis also over-ride srt.

tck=x the length of tick marks as a fraction of the smaller of the width or height of the plotting region if less than one-half. When tck is more than one-half, the ticks are drawn across that fraction of the side; thus if tck equals 1, grid lines are drawn. If tck is negative, ticks are drawn outside of the plot region. The default is -.02.

xaxp=c(ul,uh,n) coordinates of lower tick mark ul, upper tick mark uh, and number of intervals n within the range from ul to uh. For log axes if uh>1, uh is the number of decades covered plus 2 and n is the number of tick marks per decade (n may be 1, 2, or 9); if uh==1 then n is the upper tick mark. xaxp and yaxp are set by high level plotting functions, based on the current values in lab (and log) and used by the axis function (which is called implicitly by most high level plotting functions unless you use the argument axes=F).

xaxs="c" style of axis interval calculation. The styles "s" and "e" set up standard and extended axes, where numeric axis labels are more extreme than any data values. Extended axes may be extended another character width so that no data points lie very near the axis limit. Style "i" creates an axis labeled internal to the data values. This style wastes no space, yet still gives pretty labels. Style "r" extends the data range by 4% on each end, and then labels the axis internally. This ensures that all plots take up a fixed percent of the plot region, yet keeps points away from the axes. Style "d" is a direct axis, and axis parameters will not be changed by further high-level plotting routines. This is used to "lock-in" an axis from one plot to the next. The default is "r".

xaxt="c" axis type. Type "n" (null) can be used to cause an axis to be set up by a high-level routine, but then not plotted. Other types are "s" (standard), "t" (time), and "l" (logarithmic). You can set these after a plot is started, which is handy when you want to add a vector drawn symbol to a plot originally drawn on a log axis and don't want the symbol distorted. Using xaxt="n" with log="x" may cause some difficulties. One should not change xaxt before adding axes to a plot unless you also change xaxp or use the at argument to axes (so that xaxp is not used to choose the tick locations).

xpd=L logical value controlling clipping. FALSE means no points or lines may be drawn outside of the plot region. TRUE means points, lines, and text may be plotted outside of the plot region as long as they are inside the figure region.

yaxp=c(ul,uh,n) see xaxp.

yaxs="c" see xaxs.

yaxt="c" see xaxt.

LAYOUT PARAMETERS

The following parameters may only be used in function par, because they change the overall layout of plots or figures.

fig=c(x1,x2,y1,y2) coordinates of the current figure region expressed as a fraction of the device surface. This is dependent on mfrow and mfcol.

fin=c(w,h) width and height of figure in inches.

fty="c" figure type. This parameter is usually set through some other parameter. Possible values include "r" (figures arranged by rows),"c" (arranged by columns), and "s" (square). The default is "m" (maximal). Note that parameter pty should be used to control the shape of the plot.

The parameters mai and mar specify the same quantities in different units.

mai=c(xbot,xlef,xtop,xrig) margin size specified in inches. Values given for bottom, left, top, and right margins in that order.

mar=c(xbot,xlef,xtop,xrig) lines of margin on each side of plot. Margin coordinates range from 0 at the edge of the box outward in units of mex sized characters. If the margin is respecified by mai or mar, the plot region is re-created to provide the appropriate sized margins within the figure. The default value is c(5,4,4,2)+.1. Problems with lines not appearing on some devices might be remedied by specifying non-integer values in mar.

mex=x the coordinate unit for addressing locations in the margin is expressed in terms of mex. Margin coordinates are measured in terms of characters of size cex equal to mex. mex does not change the font size - it merely states which font is to be used to measure the margins.

mfg=c(i,j,m,n) multiple figure parameters which give the row and column number of the current multiple figure and the number of rows and columns in the current array of multiple figures.

mfcol=c(m,n) subsequent figures will be drawn column-by-column in an m by n matrix on the page. This is not a component of the result of par(). Setting this changes mfg, and fty (and mfrow ). If m or n is greater than 2, then both cex and mex are set to .5. This changes fig and mfg.

mfrow=c(m,n) subsequent figures will be drawn row-by-row in an m by n matrix on the page. This is not a component of the result of par(). Setting this changes mfg, and fty (and mfcol). If m or n is greater than 2, then both cex and mex are set to .5. This changes fig and mfg.

new=L if TRUE, the current plot is assumed to have no previous plotting on it. Any points, lines, or text will set new to FALSE.

the parameters oma, omd and omi specify the same quantities in different units. The outer margin is the region surrounding a set of multiple plots.

oma=c(xbot,xlef,xtop,xrig) outer margin lines of text. oma provides the maximum value for outer margin coordinates on each of the four sides of the multiple figure region. oma causes recreation of the current figure within the confines of the newly specified outer margins. The default is rep(0,4). See mtext to create titles in the outer margin.

omd=c(x1,x2,y1,y2) coordinates of the outer margin region as a fraction of the device surface.

omi=c(xbot,xlef,xtop,xrig) size of outer margins in inches.

pin=c(w,h) width and height of plot, measured in inches.

plt=c(x1,x2,y1,y2) the coordinates of the plot region measured as a fraction of the figure region.

pty="c" the type of plotting region currently in effect. Values: "s" generates a square plotting region; "m" (the default) generates a maximal size plotting region, which, with the margins, completely fills the figure region. Resizing a graphics window (e.g., when using X11) will cause the "s" option to fail, even if the plot is replotted..

usr=c(x1,x2,y1,y2) user coordinate min and max on the x- and y-axes. The default, when device is initialized, is c(0,1,0,1). This is reset during each high level graphics command. See also the xlim and ylim parameters.

INFORMATION PARAMETERS

These parameters may not be set by the user, but may be queried with par. It is an error to attempt to specify values for only information parameters.

"1em"=c(x1,y1) the size (width and height) of an "m" in the usr coordinates for the current font (and cex).

acc=x label accuracy.

cin=c(x1,y1) character size (width and height) in inches.

cra=c(x1,y1) character size (width and height) in rasters.

cxy=c(x1,y1) character size (width and height) in usr coordinates.

dev=n device code.

din=c(x1,y1) size of the current device surface in inches.

frm=n the number of graphical "pages" produced so far by the current device. This is incremented by frame and by high-level graphics functions.

omo=L logical flag: is the outer margin on? This always queries to FALSE.

rsz=c(x1,y1) raster size (width and height) in inches.

tsp=c(x1,x2,x3) the tsp attribute of the last argument to tsplot.

uin=c(x1,y1) inches per usr unit.

VALUE

if the only argument was a character string, then an atomic vector is returned which is the value of the graphical parameter named by the string.

Otherwise, a list is returned giving the values of the parameters named in the arguments. The names attribute of the list gives the names of the parameters. Such a list may be given as input to a later invocation of par. If parameter values were set, then the returned list, which is invisible, gives the previous values of the parameters that were changed. If par is given no argument, it returns a list of all current parameter values.

SIDE EFFECTS

if either a single list is given as the argument or there are any number of arguments in the name=value form, then the graphical parameters with names given in the argument(s) are changed. An error will occur if only information parameters are given in either of these forms.

The change is only for the current graphics device; there is no effect on the graphics parameters for any other active device.

DETAILS

Default par values are reset each time a graphics device is activated. The parameter values are (potentially) device dependent.

Graphical parameters can be divided into four groups: Information, High-level, General and Layout. Information parameters provide information about the current state of the current graphics device. High-level parameters can only be used in graphics functions, not in par.

General graphical parameters may be set by the par function or by giving them as named arguments to other graphics functions. When given through par, the graphical parameters are set until changed or until a new call to a device; otherwise, they are reset at the end of the function call in which they were specified.

Layout parameters can only be used in par, using them in graphics functions has no effect.

The object gr.state is a character vector giving the names of the graphical parameters that can be changed.

REFERENCES

The "Customizing Your Graphics" chapter of the S-PLUS User's Manual.

BUGS

Graphical parameters cannot have any attributes, such as dims or levels or class. You may strip the attributes of x with as.vector(x).

If you set oma to a value other than its default, and then reset all the graphics parameters in a single call to par, you will get the warning message `Graphics error: Figure specified in inches too large (in zzfigz) in:...'.

SEE ALSO

options, axis, box, frame, title, text, mtext, plot, hist.

EXAMPLES

par(mfrow=c(2,2),mar=rep(3,4))  # 2x2 array of figures
   # on the page, with 3 lines of margin around each
plot(x,y,col=3,pch=".")  # plot with specified color 
   # and plotting character
par(col=3,pch=".")  # permanent change of color and
   # plotting character
usr <- par("usr")   # numeric vector of user coordinates

oldpar <- par(tck=.02,las=1)  # set new values, remember old
par(oldpar)   # set parameters back to remembered values

par()   # returns all current parameter values
allpar <- par() # remember all parameters

par(allpar) # restore parameters
par(c("oma","tck")) # returns two current parmeter values

# a personalized device function

my.X11 <- function( )
{
        X11()
        invisible(par(mfrow = c(2, 2), col = 3))
}
# produce a plot of all the marks
par(usr=c(-1,19,0,1))	
for(i in 0:18) {
      points(i, .5, pch=i); text(i, .35, i) }
text(9, .75, 'Samples of "pch=" Parameter')
box()