Graphical Parameters

DESCRIPTION:

Provides control over the action of the graphics device; that is, layout, color, and so on.

USAGE:

par(...)

OPTIONAL ARGUMENTS:

...
valid arguments include nothing, a list, one or more vectors of character strings, or any number of arguments of the form name=value.

When the name=value form or a list is used, the names given should include only 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, cex.axis , cex.lab, cex.main , cex.sub, crt , csi, exp , font, font.axis , font.lab, font.main , font.sub, mex , pch, smo , srt, type , xlab, ylab .

Colors:

col, col.axis, col.lab , col.main, col.sub , fg, bg .

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, err, lty, lwd.

Information Parameters:

"1em", acc, cin, cra, cxy, dev, din, frm, omo , rsz, tsp, uin.

THE PARAMETERS:

The most commonly used parameters include:

cex= character expansion
log= logarithmic axes
lty= line type
pch= plotting character
type= type of plot
xlab= x axis label
ylab= y axis label (note that only the first element is used)
xlim= range for x axis
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 can be used only 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 can they be set with a call to par.

ARGUMENTS:

axes=L
"L" = a logical parameter. 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'
"c" = a character parameter. 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'
"c" = a character parameter. 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'
string label for plotting below the x-axis. Only the first element in a vector of length greater than one is used for the label.
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'
string label for plotting below the y-axis. Only the first element in a vector of length greater than one is used for the label.
ylim=c(x1,x2)
see xlim.

GENERAL PARAMETERS:

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

ARGUMENTS:

adj=x
floating point number for 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 used mainly on interactive devices to prevent plots from being erased before they can be studied.
bg=x|'string'
color to use for the background color when a new plot is created. The default value is the RGB value "#FFFFFF" (white). If bg is a numeric value, it is the index into a color palette. If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. "bg" is ignored in the high-level functions axis, barplot, bxp, legend, mtext, pie, plot, points, polygon, segments, text, and usa, but it is is allowed in symbols (where it defines the background color of the symbols and not of the plot). (In other custom S-PLUS functions, bg can be passed; its treatment is defined by that function.) Refer to the COLOR SPECIFICATION section for more information.
bty='c'
character representing the type of box. Characters "o", "lx (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. The default is 1. See also csi.
cex.axis=x
character expansion relative to device's standard size. Used for drawing tick mark labels. The default is 1.
cex.lab=x
character expansion relative to device's standard size. Used for drawing the axis labels. The default is 1.
cex.main=x
character expansion relative to device's standard size. Used for drawing the main title. The default is 1.5.
cex.sub=x
character expansion relative to device's standard size. Used for drawing the subtitle. The default is 1.
col=x|'string'
color to use for the content of the plot, such as points or lines. The default is "#000000" (black). If col is a numeric value, it is the index into a color palette. If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. Refer to the COLOR SPECIFICATION section for more information.
col.axis=x|'string'
color to use for the tick labels (for example, the numbers on an axis). Note: the tick marks and axis lines are drawn with the fg color. The default value is "#000000" (black). If col.axis is a numeric value, it is the index into a color palette. If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. Refer to the COLOR SPECIFICATION section for more information.
col.lab=x|'string'
color to use for x and y axis labels. The default value is "#000000" (black). If col.lab is a numeric value, it is the index into a color palette. If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. Refer to the COLOR SPECIFICATION section for more information.
col.main=x|'string'
color to use for the main title. The default value is "#000000" (black). If col.main is a numeric value, it is the index into a color palette. If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. Refer to the COLOR SPECIFICATION section for more information.
col.sub=x|'string'
color to use for the subtitle. The default value is "#000000" (black). If col.sub is a numeric value, it is the index into a color palette. If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. Refer to the COLOR SPECIFICATION section for more information.
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 use only srt, so setting them to different values has no effect on those devices. A few graphics devices cannot rotate text, or can rotate it only 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.
fg=x|'string'
color to use for the foreground of plots, such as axes, boxes, and tick marks. The default value is the RGB value "#000000" (black). If fg is a numeric value, it is the index into a color palette. If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. Refer to the COLOR SPECIFICATION section for more information.
font=i
font number. Device dependent. Some devices (e.g., postscript) allow this parameter to affect the font in which text is displayed. The default is 1.
font.axis=i
font number. Device dependent. Used for drawing tick mark labels.
font.lab=i
font number. Device dependent. Used for drawing axis labels.
font.main=i
font number. Device dependent. Used for drawing the main title.
font.sub=i
font number. Device dependent. Used for drawing the subtitle.
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, which is device dependent. Type 0 is blank, 1 (the default) is solid, while 2 and higher are dotted, dashed, or a combination of dotted and dashed. See the Guide to Graphics for a detailed description of the lty options for each graphics device.
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.
pch='c'
the character to be used for plotting points. If pch is a period, a centered-plotting dot is used.
pch=n
integer for the number of a plotting symbol to be drawn when plotting points. Basic marks are device-dependent, but usually adhere to the following standards: square (0); circle (or 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), circle (or octagon) (16), triangle (17), and diamond (18). 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 S-PLUS 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 override this. Many graphics devices ignore crt and only use srt so setting them to different values has no effect on those devices. Some graphics devices, such as postscript, ignore srt. A few graphics devices cannot rotate text or can only rotate it at multiples of 90 degrees. The functions title and axis also override srt. The default is 0.
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. Do 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).
xlog=L
logical value (see log in plot.default). If TRUE, a logarithmic scale is in use (e.g., after plot(*, log = "x")). For a new device, it defaults to FALSE , i.e., linear scale.
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.
ylog=L
see xlog.

LAYOUT PARAMETERS:

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

ARGUMENTS:

fig=c(x1,x2,y1,y2)
coordinates of the current figure region expressed as a fraction of the device surface. Depends 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.

ARGUMENTS:

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; within a function, it is good programming practice to save the existing par parameters, then use on.exit to restore the old parameters when the function exits. Note, however, that not all parameters are actually saved in the par return list.

Also note the substantial difference between e.g. on.exit(par());par(mfrow=c(2,2)) , which restores all current values, and on.exit(par(mfrow=c(2,2))) , which restores only the mfrow parameter. Restoring all values can be dangerous; e.g. in some circumstances it sets new=T so that the current plot is not erased before a new plot is drawn.

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.

xaxt and yaxt of type 'l' are supported; however, for compatibility with R, using xlog and ylog is recommended.

COLOR SPECIFICATION:

Beginning with S-PLUS 8, values for the color parameters ( col, col.axis, col.lab , col.main, col.sub , bg, fg ) can be specified as either a numeric value or a character string. A numeric value is the index into a color palette. A character string can be either a color name, an RGB value or an RGBA value.

When a color is specified by a numeric value, it is converted to an integer and used as the index into the global color palette. The global color palette is a vector of RGB values that is used by all devices. The current palette can be modified or viewed using the palette function. The default S-PLUS palette contains 16 colors. The palette vector can be any length, and if the index is larger than the number of colors in the palette, the palette colors are replicated to the necessary length. Color 0 is the background color. Instead of the global palette, a device specific color palette can be used by calling either use.device.palette(T) or use.legacy.graphics(T) .

If the color is given as a string, it must be either an RGB value, an RGBA value, or a color name. An RGB value is the hexadecimal representation of the red, green and blue values of a color, "#rrggbb". There are 256 potential values for red, green, and blue. For example, "#483D8B" is the RGB value for dark slate blue. If the device supports transparency, then an RGBA value can be specified, "#rrggbbaa", where the last two hexadecimal digits represent the transparency, or alpha value, ranging from 0 (transparent) to 255 (opaque). For example, a semi-transparent red is specified by "#FF000080".

The color value can also be given by a color name such as "red" or "darkslateblue". The name must be a known color name. Use the function colors to see the known colors. By default, S-PLUS uses the 147 color names and values specified by the CSS3 Color Module. New colors can be added to the color list by calling add.color.values. Color names must not contain spaces. Color names and RGB values are case-insensitive.

For more information, refer to the chapter discussing graphics enhancements in the Guide to Graphics and see the help files for functions and .

PARAMETERS FOR PLOT ANNOTATION:

The parameters described below are used to control the look of the text annotation of a plot: main title, subtitle, axis labels and tick labels.
    cex.main , col.main, font.main : Controls the character size, color and font of the main title.
    cex.sub , col.sub, font.sub : Controls the character size, color and font of the subtitle.
    cex.lab , col.lab, font.lab : Controls the character size, color and font of the axis labels.
    cex.axis , col.axis, font.axis : Controls the character size, color and font of the tick labels.

Note: The parameters srt.axis, srt.lab , srt.main, and srt.sub are included in par but are not fully implemented, so they should not be used.

VECTORIZED PARAMETERS:

Several S-PLUS graphics functions allow some graphics parameters to be given as a vector of values. For example, the points function accepts a vector of values for the col argument allowing multi-color points to be drawn by a single call to points instead of putting the call in a loop with the value of col changing for each call. If the length of the color vector is less than the number of points, the values will be replicated to the appropriate length.

These graphics parameters can be given as vectors: col, cex , font, pch , lty , and lwd. Refer the section "Vectorized Graphics Parameters" in the Guide to Graphics to see a table showing which functions allow vectorized parameters.

NOTE: Vectorized values are not allowed in a call to par when setting the parameters listed above. Vectorized values are only allowed in calls to specific plotting functions.

REFERENCES:

Refer to the S-PLUS document Guide to Graphics.
CSS3 Color Module specification: http://www.w3.org/TR/css3-color/

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:

, , , , , , , , , , , .

EXAMPLES:

# 2x2 array of figures on the page, with 3 lines of margin around each
par(mfrow=c(2, 2), mar=rep(3, 4))  
# plot with specified color and plotting character
plot(x, y, col=3, pch=".")
# permanent change of color and plotting character
par(col="#483D8B", pch=".")
# numeric vector of user coordinates
usr <- par("usr")
# set new values, remember old
oldpar <- par(tck=.02, las=1)
# set parameters back to remembered values
par(oldpar)
# returns all current parameter values
par()
# remember all parameters
allpar <- par() 
# restore parameters
par(allpar)
# returns two current parameter values
par(c("oma", "tck"))
# produce a plot of all the marks using vectorized parameters
par(usr=c(-1, 19, 0, 1))        
points(0:18, rep(.5, 19), pch=0:18, col=1:19)
text(0:18, rep(.35, 19), 0:18)
text(9, .75, 'Samples of "pch=" Parameter')
box(n=5, col="orange")