par {graphics} | R Documentation |
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.
par(..., no.readonly = FALSE) <highlevel plot> (..., <tag> = <value>)
... |
arguments in tag = value form, or a list of tagged
values. The tags must come from the graphical parameters described
below. |
no.readonly |
logical; if TRUE and there are no other
arguments, only parameters are returned which can be set by a
subsequent par() call. |
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 unexported variable .Pars
.
R.O. indicates read-only arguments: These
may only be used in queries and cannot be set. ("cin"
,
"cra"
, "csi"
, "cxy"
and "din"
are always
read-only, and "gamma"
is on most devices.)
There are several parameters can only be set by a call to par()
:
"ask"
"family"
, "fig"
, "fin"
"lend"
, "lheight"
, "ljoin"
, "lmitre"
"mai"
, "mar"
, "mex"
,
"mfcol"
, "mfrow"
, "mfg"
"new"
"oma"
, "omd"
, "omi"
"pin"
, "plt"
, "ps"
, "pty"
"usr"
"xlog"
, "ylog"
The remaining parameters can also be set as arguments (often via
...
) to high-level plot functions such as
plot.default
, plot.window
,
points
, lines
, abline
,
axis
, title
, text
,
mtext
, segments
, symbols
,
arrows
, polygon
, rect
,
box
, contour
, filled.contour
and image
. Such settings will be active during the
execution of the function, only. However, see the comments on
bg
and cex
, which may be taken as arguments to certain
plot functions rather than as graphical parameters.
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 of that parameter
is returned as (atomic) vector. When two or more parameters are
queried, their values are returned in a list, with the list names
giving the parameters.
Note the inconsistency: setting one parameter returns a list, but
querying one parameter returns a vector.
adj
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
FALSE
, high-level plotting
functions calling plot.default
do not annotate the
plots they produce with axis titles and overall titles. The
default is to do annotation.ask
TRUE
, the user is asked for
input, before a new figure is drawn.bg
plot.default
and points
have an
argument of this name with a different meaning.bty
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
plot.default
have an argument of this name
which multiplies this graphical parameter.cex.axis
cex
.cex.lab
cex
.cex.main
cex
.cex.sub
cex
.cin
(width,height)
in inches.col
col.axis
col.lab
col.main
col.sub
cra
(width,height)
in “rasters” (pixels).crt
srt
which does string rotation.csi
cxy
(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
(width,height)
, in inches.err
family
""
which means that the
default device fonts will be used.
Standard values are "serif"
, "sans"
,
"mono"
, and "symbol"
and the Hershey
font families are also available. Different devices
may define others. Some devices will ignore this setting
completely.fg
par()
this also sets
parameter col
to the same value.
A description of how colors are specified is given below.
fig
c(x1, x2, y1,
y2)
which gives the (NDC) coordinates of the figure region in
the display region of the device. If you set this, unlike S, you
start a new plot, so to add to an existing plot use
new=TRUE
as well.fin
(width,height)
, in inches. If you set this, unlike S, you
start a new plot.font
family
to choose different sets of 5 fonts.font.axis
font.lab
font.main
font.sub
gamma
gamma
to hsv
. This is only accepted if the current device
has support for changing the gamma correction: currently only
windows
and quartz
do. (X11
has support for
setting the gamma correction when opening the device, but not for
changing it.)lab
c(x, y, len)
which modifies the default 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 length. The
default is c(5, 5, 7)
. Note that this only affects the way
the parameters xaxp
and yaxp
are set when the user
coordinate system is set up, and is not consulted when axes are drawn.
len
is unimplemented in R.las
Note that other string/character rotation (via argument srt
to par
) does not affect the axis labels.
lend
"round"
mean rounded line caps;
1 and "butt"
mean butt line caps;
2 and "square"
mean square line caps.
lheight
ljoin
"round"
mean rounded line joins;
1 and "mitre"
mean mitred line joins;
2 and "bevel"
mean bevelled line joins.lmitre
lty
"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(1: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
1
. The interpretation is device-specific,
and some devices do not implement line widths less than one.
mai
c(bottom,
left, top, right)
which gives the margin size specified in
inches.mar
c(bottom,
left, top, right)
which gives the number of 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.
Note that this does not change the font size, rather specifies the
size of font used to convert between mar
and mai
,
and between oma
and omi
.
mfcol, mfrow
c(nr, nc)
.
Subsequent figures will be drawn in an nr
-by-nc
array on the device by columns (mfcol
), or
rows (mfrow
), respectively.
In a layout with exactly two rows and columns the base value of
"cex"
is reduced by a factor of 0.83: if there are three or
more of either rows or columns, the reduction factor is 0.66.
Consider the alternatives, layout
and
split.screen
.
mfg
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
mex
units) for the axis
title, axis labels and axis line.
The default is c(3, 1, 0)
.mkh
pch
is an integer.
Completely ignored currently.
new
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
c(bottom, left, top,
right)
giving the size of the outer margins in lines of text.omd
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
c(bottom, left, top,
right)
giving the size of the outer margins in inches.pch
points
for possible values and their interpretation.
pin
(width,height)
,
in inches.plt
c(x1, x2, y1, y2)
giving the coordinates of the plot region as fractions of the
current figure region.ps
pointsize
argument of most devices, this does not change
the relationship between mar
and mai
(nor oma
and omi
), but it does scale cin
and csi
.
What is meant by ‘pointsize’ is device-specific, but most devices mean a multiple of 1bp, that is 1/72 of an inch.
pty
"s"
generates a square plotting region and
"m"
generates the maximal plotting region.smo
srt
crt
.
tck
tck >= 0.5
it is interpreted as a fraction of the
relevant side, so if
tck = 1
grid lines are drawn. The default setting
(tck = NA
) is to use tcl = -0.5
(see below).tcl
-0.5
;
setting tcl = NA
sets tck = -0.01
which is S' default.tmag
1.2
.type
plot.default(type=...)
, defaulting to "p"
.
NB: This is currently used – the default for
plot.default
does not depend on this par.usr
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
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, 10 ^ par("usr")[1:2]
. (The
"usr"
coordinates are log10-transformed here!)
See axTicks()
for a pure R implementation of this.
This parameter is reset when a user coordinate system is set up,
for example by starting a new page or by calling
plot.window
or setting par("usr")
: n
is taken from par("lab")
. It affects the default behaviour
of subsequent calls to axis
for sides 1 or 3.
xaxs
"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 ensures 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
"n"
suppresses plotting of the axis. The
standard value is "s"
: for compatibility with S values
"l"
and "t"
are accepted but are equivalent to
"s"
: any value other than "n"
implies plotting.xlog
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
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
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
xaxs
above.yaxt
"n"
suppresses plotting.ylog
xlog
above.
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 their 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
, hcl
,
gray
and rainbow
provide additional ways of generating colors.
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 an even number (up to eight)
of characters, namely non-zero
(hexadecimal) 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.
The five standard dash-dot line types (lty = 2:6
) correspond to
c("44", "13", "1343", "73", "2262")
.
Note that NA
is not a valid value for lty
.
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.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
plot.default
for some high-level plotting parameters;
colors
;
options
for other setup parameters;
graphic devices x11
, postscript
and
setting up device regions by layout
and
split.screen
.
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 par(c("usr", "xaxp")) ( 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 ## 'fg' use: plot(1:12, type = "b", main="'fg' : axes, ticks and box in gray", fg = gray(0.7), bty="7" , sub=R.version.string) 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()