par(...)
name=value
.
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.
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 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.
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
.
"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.
"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.)
"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.
xlim
.
The following parameters can be used in any graphical functions,
including
par
.
0
means left justify,
1
means right justify,
.5
means to center the text.
Other numbers are a corresponding distance between the extremes.
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.
"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
= 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
.
1
.
1
.
1.5
.
1
.
"#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.
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
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
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
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.
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.
cex
--
setting either changes both parameters.
-1
means to not print graphics
error messages (points out of bounds, etc.),
0
means to print messages (the default).
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
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.
postscript
)
allow this parameter to affect the font in which text is displayed.
The default is
1
.
c(5,5,7)
.
0
= always parallel to axis (the default),
1
= always horizontal,
2
= always perpendicular to axis.
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.
1
is the standard width for the device.
Many devices cannot change line width.
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
is a period,
a centered-plotting dot is used.
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
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
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
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
.
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
).
"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"
.
"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).
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.
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.
xaxp
.
xaxs
.
xaxt
.
xlog
.
The following parameters can be used only in the function
par
,
because they change the overall layout of plots or figures.
mfrow
and
mfcol
.
"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.
mai
and
mar
specify
the same quantities in different units.
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
.
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.
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
.
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
.
TRUE
, the current plot is assumed to have no
previous plotting on it.
Any points, lines, or text will set
new
to
FALSE
.
oma
,
omd
and
omi
specify the same quantities in different units.
The outer margin is the region surrounding a set of multiple plots.
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.
"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.
c(0,1,0,1)
.
This is reset during each high level graphics command.
See also the
xlim
and
ylim
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.
usr
coordinates for the current font
(and
cex
).
usr
coordinates.
frame
and by high-level graphics functions.
FALSE
.
tsp
attribute of the last argument
to
tsplot
.
usr
unit.
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.
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.
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.
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 .
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.
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.
Refer to the S-PLUS document Guide to Graphics.
CSS3 Color Module specification:
http://www.w3.org/TR/css3-color/
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:...
.
# 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")