Set or Query Graphical Parameters

Description

par can be used to set or query graphical parameters. Parameters can be set by specifying them as arguments to par in tag = value form, or by passing them as a list of tagged values.

Usage

par(..., no.readonly = FALSE)

<highlevel plot> (..., <tag> = <value>)

Arguments

Details

Parameters are queried by giving one or more character vectors to par.

par() (no arguments) or par(no.readonly=TRUE) is used to get all the graphical parameters (as a named list). Their names are currently taken from the variable .Pars. .Pars.readonly contains the names of the par arguments which are readonly.

R.O. indicates read-only arguments: These may only be used in queries, i.e., they do not set anything.

All but these R.O. and the following low-level arguments can be set as well in high-level and mid-level plot functions, such as plot, points, lines, axis, title, text, mtext:

• "ask"

• "fig", "fin"

• "mai", "mar", "mex"

• "mfrow", "mfcol", "mfg"

• "new"

• "oma", "omd", "omi"

• "pin", "plt", "ps", "pty"

• "usr"

• "xlog", "ylog"

Value

When parameters are set, their former values are returned in an invisible named list. Such a list can be passed as an argument to par to restore the parameter values. Use par(no.readonly = TRUE) for the full list of parameters that can be restored.

When just one parameter is queried, the value is a character string. When two or more parameters are queried, the result is a list of character strings, with the list names giving the parameters.

Note the inconsistency: setting one parameter returns a list, but querying one parameter returns a vector.

Graphical Parameters

adj

The value of adj determines the way in which text strings are justified. A value of 0 produces left-justified text, 0.5 centered text and 1 right-justified text. (Any value in [0, 1] is allowed, and on most devices values outside that interval will also work.) Note that the adj argument of text also allows adj = c(x, y) for different adjustment in x- and y- direction.

ann

If set to FALSE, high-level plotting functions do not annotate the plots they produce with axis and overall titles. The default is to do annotation.

ask

logical. If TRUE, the user is asked for input, before a new figure is drawn.

bg

The color to be used for the background of plots. A description of how colors are specified is given below.

bty

A character string which determined the type of box which is drawn about plots. If bty is one of "o", "l", "7", "c", "u", or "]" the resulting box resembles the corresponding upper case letter. A value of "n" suppresses the box.

cex

A numerical value giving the amount by which plotting text and symbols should be scaled relative to the default.

cex.axis

The magnification to be used for axis annotation relative to the current.

cex.lab

The magnification to be used for x and y labels relative to the current.

cex.main

The magnification to be used for main titles relative to the current.

cex.sub

The magnification to be used for sub-titles relative to the current.

cin

R.O.; character size (width,height) in inches.

col

A specification for the default plotting color. A description of how colors are specified is given below.

col.axis

The color to be used for axis annotation.

col.lab

The color to be used for x and y labels.

col.main

The color to be used for plot main titles.

col.sub

The color to be used for plot sub-titles.

cra

R.O.; size of default character (width,height) in “rasters” (pixels).

crt

A numerical value specifying (in degrees) how single characters should be rotated. It is unwise to expect values other than multiples of 90 to work. Compare with srt which does string rotation.

csi

R.O.; height of (default sized) characters in inches.

cxy

R.O.; size of default character (width,height) in user coordinate units. par("cxy") is par("cin")/par("pin") scaled to user coordinates. Note that c(strwidth(ch), strheight(ch)) for a given string ch is usually much more precise.

din

R.O.; the device dimensions in inches.

err

(Unimplemented; R is silent when points outside the plot region are not plotted.) The degree of error reporting desired.

fg

The color to be used for the foreground of plots. This is the default color is used for things like axes and boxes around plots. A description of how colors are specified is given below.

fig

A numerical vector of the form c(x1, x2, y1, y2) which gives the (NDC) coordinates of the figure region in the display region of the device.

fin

A numerical vector of the form c(x, y) which gives the size of the figure region in inches.

font

An integer which specifies which font to use for text. If possible, device drivers arrange so that 1 corresponds to plain text, 2 to bold face, 3 to italic and 4 to bold italic.

font.axis

The font to be used for axis annotation.

font.lab

The font to be used for x and y labels.

font.main

The font to be used for plot main titles.

font.sub

The font to be used for plot sub-titles.

gamma

the gamma correction, see argument gamma to hsv.

lab

A numerical vector of the form c(x, y, len) which modifies the way that axes are annotated. The values of x and y give the (approximate) number of tickmarks on the x and y axes and len specifies the label size. The default is c(5, 5, 7). Currently, len is unimplemented.

las

numeric in {0,1,2,3}; the style of axis labels.

0:

always parallel to the axis [default],

1:

always horizontal,

2:

always perpendicular to the axis,

3:

always vertical.

Note that other string/character rotation (via argument srt to par) does not affect the axis labels.

lty

The line type. Line types can either be specified as an integer (0=blank, 1=solid, 2=dashed, 3=dotted, 4=dotdash, 5=longdash, 6=twodash) or as one of the character strings "blank", "solid", "dashed", "dotted", "dotdash", "longdash", or "twodash", where "blank" uses ‘invisible lines’ (i.e., doesn't draw them).

Alternatively, a string of up to 8 characters (from c(0:9, "A":"F")) may be given, giving the length of line segments which are alternatively drawn and skipped. See section 'Line Type Specification' below.

lwd

The line width, a positive number, defaulting to 1.

mai

A numerical vector of the form c(bottom, left, top, right) which gives the margin size specified in inches.

mar

A numerical vector of the form c(bottom, left, top, right) which gives the lines of margin to be specified on the four sides of the plot. The default is c(5, 4, 4, 2) + 0.1.

mex

mex is a character size expansion factor which is used to describe coordinates in the margins of plots.

mfcol, mfrow

A vector of the form c(nr, nc). Subsequent figures will be drawn in an nr-by-nc array on the device by columns (mfcol), or rows (mfrow), respectively.

Consider the alternatives, layout and split.screen.

mfg

A numerical vector of the form c(i, j) where i and j indicate which figure in an array of figures is to be drawn next (if setting) or is being drawn (if enquiring). The array must already have been set by mfcol or mfrow.

For compatibility with S, the form c(i, j, nr, nc) is also accepted, when nr and nc should be the current number of rows and number of columns. Mismatches will be ignored, with a warning.

mgp

The margin line (in mex units) for the axis title, axis labels and axis line. The default is c(3, 1, 0).

mkh

The height in inches of symbols to be drawn when the value of pch is an integer. Completely ignored currently.

new

logical, defaulting to FALSE. If set to TRUE, the next high-level plotting command (actually plot.new) should not clean the frame before drawing “as if it was on a new device”.

oma

A vector of the form c(bottom, left, top, right) giving the size of the outer margins in lines of text.

omd

A vector of the form c(x1, x2, y1, y2) giving the outer margin region in NDC (= normalized device coordinates), i.e., as fraction (in [0,1]) of the device region.

omi

A vector of the form c(bottom, left, top, right) giving the size of the outer margins in inches.

pch

Either an integer specifying a symbol or a single character to be used as the default in plotting points.

pin

The width and height of the current plot in inches.

plt

A vector of the form c(x1, x2, y1, y2) giving the coordinates of the plot region as fractions of the current figure region.

ps

integer; the pointsize of text and symbols.

pty

A character specifying the type of plot region to be used; "s" generates a square plotting region and "m" generates the maximal plotting region.

smo

(Unimplemented) a value which indicates how smooth circles and circular arcs should be.

srt

The string rotation in degrees.

tck

The length of tick marks as a fraction of the smaller of the width or height of the plotting region. If tck=1, grid lines are drawn. The default setting (tck = NA) is to use tcl = -0.5 (see below).

tcl

The length of tick marks as a fraction of the height of a line of text. The default value is -0.5; setting tcl = NA sets tck = -0.01 which is S' default.

tmag

A number specifying the enlargement of text of the main title relative to the other annotating text of the plot.

type

character; the default plot type desired, see plot.default(type=...), defaulting to "p".

usr

A vector of the form c(x1, x2, y1, y2) giving the extremes of the user coordinates of the plotting region. When a logarithmic scale is in use (i.e., par("xlog") is true, see below), then the x-limits will be 10 ^ par("usr")[1:2]. Similarly for the y-axis.

xaxp

A vector of the form c(x1, x2, n) giving the coordinates of the extreme tick marks and the number of intervals between tick-marks when par("xlog") is false. Otherwise, when log coordinates are active, the three values have a different meaning: For a small range, n is negative, and the ticks are as in the linear case, otherwise, n is in 1:3, specifying a case number, and x1 and x2 are the lowest and highest power of 10 inside the user coordinates, par("usr")[1:2]. See axTicks() for more details.

xaxs

The style of axis interval calculation to be used for the x-axis. Possible values are "r", "i", "e", "s", "d". The styles are generally controlled by the range of data or xlim, if given. Style "r" (regular) first extends the data range by 4 percent and then finds an axis with pretty labels that fits within the range. Style "i" (internal) just finds an axis with pretty labels that fits within the original data range. Style "s" (standard) finds an axis with pretty labels within which the original data range fits. Style "e" (extended) is like style "s", except that it is also ensured that there is room for plotting symbols within the bounding box. Style "d" (direct) specifies that the current axis should be used on subsequent plots. (Only "r" and "i" styles are currently implemented)

xaxt

A character which specifies the axis type. Specifying "n" causes an axis to be set up, but not plotted. The standard value is "s": for compatibility with S values "l" and "e" are accepted but are equivalent to "s".

xlog

R.O.; 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

A logical value or NA. If FALSE, all plotting is clipped to the plot region, if TRUE, all plotting is clipped to the figure region, and if NA, all plotting is clipped to the device region.

yaxp

A vector of the form c(y1, y2, n) giving the coordinates of the extreme tick marks and the number of intervals between tick-marks unless for log coordinates, see xaxp above.

yaxs

The style of axis interval calculation to be used for the y-axis. See xaxs above.

yaxt

A character which specifies the axis type. Specifying "n" causes an axis to be set up, but not plotted.

ylog

R.O.; a logical value; see xlog above.

Color Specification

Colors can be specified in several different ways. The simplest way is with a character string giving the color name (e.g., "red"). A list of the possible colors can be obtained with the function colors. Alternatively, colors can be specified directly in terms of there RGB components with a string of the form "#RRGGBB" where each of the pairs RR, GG, BB consist of two hexadecimal digits giving a value in the range 00 to FF. Colors can also be specified by giving an index into a small table of colors, the palette. This provides compatibility with S. Index 0 corresponds to the background color.

Additionally, "transparent" or (integer) NA is transparent, useful for filled areas (such as the background!), and just invisible for things like lines or text.

The functions rgb, hsv, gray and rainbow provide additional ways of generating colors.

Line Type Specification

Line types can either be specified by giving an index into a small built in table of line types (1 = solid, 2 = dashed, etc, see lty above) or directly as the lengths of on/off stretches of line. This is done with a string of up to eight characters, namely (hexadesimal) digits which give the lengths in consecutive positions in the string. For example, the string "33" specifies three units on followed by three off and "3313" specifies three units on followed by three off followed by one on and finally three off. The ‘units’ here are (on most devices) proportional to lwd, and with lwd = 1 are in pixels or points.

Note

The effect of restoring all the (settable) graphics parameters as in the examples is hard to predict if the device has been resized. Several of them are attempting to set the same things in different ways, and those last in the alphabet will win. In particular, the settings of mai, mar, pin, plt and pty interact, as do the outer margin settings, the figure layout and figure region size.

See Also

plot.default for some high-level plotting parameters; colors, gray, rainbow, rgb; options for other setup parameters; graphic devices x11, postscript and setting up device regions by layout and split.screen.

Examples

op <- par(mfrow = c(2, 2), # 2 x 2 pictures on one plot
          pty = "s")       # square plotting region,
                           # independent of device size

## At end of plotting, reset to previous settings:
par(op)

## Alternatively,
op <- par(no.readonly = TRUE) # the whole list of settable par's.
## do lots of plotting and par(.) calls, then reset:
par(op)

par("ylog") # FALSE
plot(1 : 12, log = "y")
par("ylog") # TRUE

plot(1:2, xaxs = "i") # `inner axis' w/o extra space
stopifnot(par("xaxp")[1:2] == 1:2 &&
          par("usr") [1:2] == 1:2)

( nr.prof <-
  c(prof.pilots=16,lawyers=11,farmers=10,salesmen=9,physicians=9,
    mechanics=6,policemen=6,managers=6,engineers=5,teachers=4,
    housewives=3,students=3,armed.forces=1))
par(las = 3)
barplot(rbind(nr.prof)) # R 0.63.2: shows alignment problem
par(las = 0)# reset to default

ex <- function() {
   old.par <- par(no.readonly = TRUE) # all par settings which
                                      # could be changed.
   on.exit(par(old.par))
   ## ...
   ## ... do lots of par() settings and plots
   ## ...
   invisible() #-- now,  par(old.par)  will be executed
}
ex()