par
Set or Query Graphical Parameters
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.
- Keywords
- dplot, environment, iplot
Usage
par(..., no.readonly = FALSE) (..., = )
Arguments
- ...
- arguments in
tag = value
form, or a list of tagged values. The tags must come from the names of graphical parameters described in theGraphical Parameters section. - no.readonly
- logical; if
TRUE
and there are no other arguments, only parameters are returned which can be set by a subsequentpar()
call on the same device.
Details
Each device has its own set of graphical parameters. If the current
device is the null device, par
will open a new device before
querying/setting parameters. (What device is controlled by
options("device")
.)
Parameters are queried by giving one or more character vectors of
parameter names 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
graphics:::.Pars
.
R.O. indicates read-only arguments: These
may only be used in queries and cannot be set. ("cin"
,
"cra"
, "csi"
, "cxy"
, "din"
and
"page"
are always read-only.)
Several parameters can only be set by a call to par()
:
"ask"
,"fig"
,"fin"
,"lheight"
,"mai"
,"mar"
,"mex"
,"mfcol"
,"mfrow"
,"mfg"
,"new"
,"oma"
,"omd"
,"omi"
,"pin"
,"plt"
,"ps"
,"pty"
,"usr"
,"xlog"
,"ylog"
,"ylbias"
...
) 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
, cex
, col
, lty
, lwd
and
pch
which may be taken as arguments to certain plot
functions rather than as graphical parameters. The meaning of pointsize
into account but often
not the actual font family in use. Internally the corresponding pars
(cra
, cin
, cxy
and csi
) are used only to
set the inter-line spacing used to convert mar
and oma
to physical margins. (The same inter-line spacing multiplied by
lheight
is used for multi-line strings in text
and
strheight
.)
Note that graphical parameters are suggestions: plotting functions and
devices need not make use of them (and this is particularly true of
non-default methods for e.g.plot
).
Value
- When parameters are set, their previous values are returned in an
invisible named list. Such a list can be passed as an argument to
par
to restore the parameter values. Usepar(no.readonly = TRUE)
for the full list of parameters that can be restored. However, restoring all of these is not wise: see theNote section.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.
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.
concept
- adj
- ann
- ask
- bg
- bty
- cex.axis
- cex.lab
- cex.main
- cex.sub
- cex
- cin
- col.axis
- col.lab
- col.main
- col.sub
- col
- cra
- crt
- csi
- cxy
- din
- err
- family
- fg
- fig
- fin
- font.axis
- font.lab
- font.main
- font.sub
- font
- lab
- las
- lend
- lheight
- ljoin
- lmitre
- lty
- lwd
- mai
- mar
- mex
- mfcol
- mfg
- mfrow
- mgp
- mkh
- new
- oma
- omd
- omi
- page
- pch
- pin
- plt
- ps
- pty
- smo
- srt
- tck
- tcl
- usr
- xaxp
- xaxs
- xaxt
- xlog
- xpd
- yaxp
- yaxs
- yaxt
- ylog
- color
- colour
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 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
:
indices wrap round so with the default palette of size 8, 10
is
the same as 2
. This provides compatibility with S. Index
0
corresponds to the background color. Note that the palette
(apart from 0
which is per-device) is a per-session setting.
Negative integer colours are errors.
Additionally, "transparent"
is transparent, useful for
filled areas (such as the background!), and just invisible for things
like lines or text. In most circumstances (integer) NA
is equivalent to "transparent"
(but not for
text
and mtext
).
Semi-transparent colors are available for use on devices that support them.
The functions rgb
, hsv
, hcl
,
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 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 lwd
, and with lwd = 1
are in pixels or points or 1/96
inch.
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
.
References
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
Murrell, P. (2005) R Graphics. Chapman & Hall/CRC Press.
See Also
plot.default
for some high-level plotting parameters;
colors
; clip
;
options
for other setup parameters;
graphic devices x11
, postscript
and
setting up device regions by layout
and
split.screen
.
Examples
library(graphics)
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)
## Note this is not in general good practice
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
require(grDevices) # for gray
## '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()
## Line types
showLty <- function(ltys, xoff = 0, ...) {
stopifnot((n <- length(ltys)) >= 1)
op <- par(mar = rep(.5,4)); on.exit(par(op))
plot(0:1, 0:1, type = "n", axes = FALSE, ann = FALSE)
y <- (n:1)/(n+1)
clty <- as.character(ltys)
mytext <- function(x, y, txt)
text(x, y, txt, adj = c(0, -.3), cex = 0.8, ...)
abline(h = y, lty = ltys, ...); mytext(xoff, y, clty)
y <- y - 1/(3*(n+1))
abline(h = y, lty = ltys, lwd = 2, ...)
mytext(1/8+xoff, y, paste(clty,"lwd = 2"))
}
showLty(c("solid", "dashed", "dotted", "dotdash", "longdash", "twodash"))
par(new = TRUE) # the same:
showLty(c("solid", "44", "13", "1343", "73", "2262"), xoff = .2, col = 2)
showLty(c("11", "22", "33", "44", "12", "13", "14", "21", "31"))
Community examples
SP500 <- read.csv('SP500.csv') Date <- as.Date(SP500$Date, '%m/%d/%y') par(mfrow=c(1, 2)) plot(SP500$Date, SP500$Close, xlab='Date', yLab='Value', type='1', main='S&P 500 Index', col='blue', col.axis='blue') # I am not sure this is correct or not