\Header{par}{Set or Query Graphical Parameters}
\alias{.Pars}{par}
\alias{.Pars.readonly}{par}
\keyword{iplot}{par}
\keyword{dplot}{par}
\keyword{environment}{par}
\begin{Usage}
\begin{verbatim}
par(..., no.readonly = FALSE)

<highlevel plot> (......, <tag> = <value>)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{no.readonly}] logical; if \texttt{TRUE} and there are no other
arguments,  only parameters are returned which can be set by a
subsequent \texttt{par(.)} call.
\item[\texttt{adj}] The value of \texttt{adj} determines the way in which text
strings are justified.  A value of \texttt{0} produces right
left-justified text, \texttt{0.5} centered text and \texttt{1}
right-justified text.
\item[\texttt{ann}] If set to \texttt{FALSE}, high-level plotting functions do
not annotate the plots they produce with axis and overall titles.
The default is to do annotation.
\item[\texttt{ask}] logical. If \texttt{TRUE}, the user is asked for input,
before a new figure is drawn.
\item[\texttt{bg}] The color to be used for the background of plots.  A
description of how colors are specified is given below.
\item[\texttt{bty}] A character string which determined the type of box which
is drawn about plots.  If \texttt{bty} is one of \texttt{"o"},
\texttt{"l"}, \texttt{"7"}, \texttt{"c"}, or \texttt{"]"} the resulting box
resembles the corresponding upper case letter.  A value of
\texttt{"n"} suppresses the box.
\item[\texttt{cex}] A numerical value giving the amount by which plotting text
and symbols should be scaled relative to the default.
\item[\texttt{cex.axis}] The magnification to be used for axis annotation
relative to the current.
\item[\texttt{cex.lab}] The magnification to be used for x and y labels
relative to the current.
\item[\texttt{cex.main}] The magnification to be used for main titles relative
to the current.
\item[\texttt{cex.sub}] The magnification to be used for sub-titles relative to
the current.
\item[\texttt{cin}] \emph{\bold{R.O.}}. 
\item[\texttt{col}] A specification for the default plotting color.  A
description of how colors are specified is given below.
\item[\texttt{col.axis}] The color to be used for axis annotation.
\item[\texttt{col.lab}] The color to be used for x and y labels.
\item[\texttt{col.main}] The color to be used for plot main titles.
\item[\texttt{col.sub}] The color to be used for plot sub-titles.
\item[\texttt{cra}] \emph{\bold{R.O.}}. 
\item[\texttt{crt}] A numerical value specifying (in degrees) how strings
should be rotated.  It is unwise to expect values other than
multiples of 90 to work.
\item[\texttt{csi}] \emph{\bold{R.O.}}. The height of (default sized) characters in inches.
\item[\texttt{din}] \emph{\bold{R.O.}}. The device dimensions in inches.
\item[\texttt{err}] (\emph{Unimplemented}) The degree of error reporting desired.
\item[\texttt{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.
\item[\texttt{fig}] A numerical vector of the form \texttt{c(x1, x2, y1, y2)}
which gives the (NDC) coordinates of the figure region in the
display region of the device.
\item[\texttt{fin}] A numerical vector of the form \texttt{c(x, y)} which gives
the size of the figure region in inches.
\item[\texttt{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.
\item[\texttt{font.axis}] The font to be used for axis annotation.
\item[\texttt{font.lab}] The font to be used for x and y labels.
\item[\texttt{font.main}] The font to be used for plot main titles.
\item[\texttt{font.sub}] The font to be used for plot sub-titles.
\item[\texttt{gamma}] the gamma correction, see \texttt{\Link{hsv}(.., gamma)}.
\item[\texttt{lab}] A numerical vector of the form \texttt{c(x, y, len)} which
modifies the way that axes are annotated.
The values of \texttt{x} and \texttt{y} give the (approximate) number of
tickmarks on the x and y axes and
\texttt{len} specifies the label size.
\emph{Currently}, \texttt{len} \emph{is unimplemented}.
\item[\texttt{las}] numeric in \{0,1,2\}; the style of axis labels.
0 = always parallel to the axis [\emph{default}],
1 = always horizontal,
2 = always perpendicular to the axis,
3 = always vertical.

\item[\texttt{lty}] The line type.
Line types can either be specified as an integer (1=solid, 2=dashed,
3=dotted 4=dotdashed) or as one of the character strings
\texttt{"solid"}, \texttt{"dashed"}, \texttt{"dotted"} or
\texttt{"dotdashed"}.
Alternatively, a string of up to 8 characters may be given, giving
the length (in points) of line segments which are alternatively
drawn and skipped.  For example, \texttt{"44"} is dashed and
\texttt{"13"} is dotted.
\item[\texttt{lwd}] The line width, a \emph{positive} numerical, defaulting to
\texttt{1}.
\item[\texttt{mai}] A numerical vector of the form \texttt{c(bottom, left, top, right)}
which gives the margin size specified in inches.
\item[\texttt{mar}] A numerical vector of the form \texttt{c(bottom, left, top, right)}
which gives the lines of margin to be specified on the four sides of
the plot.  The default is \texttt{c(5, 4, 4, 2) + 0.1}.
\item[\texttt{mex}] \texttt{mex} is a character size expansion factor which is
used to describe coordinates in the margins of plots.
\item[\texttt{mfcol, mfrow}] A vector of the form \texttt{c(nr, nc)}.
Subsequent figures will be drawn in an \texttt{nr}-by-\texttt{nc}
array on the device by \emph{columns} (\texttt{mfcol}), or
\emph{rows} (\texttt{mfrow}), respectively.

Consider the alternatives, \texttt{\Link{layout}(..)} and
\texttt{\Link{split.screen}(..)}.

\item[\texttt{mfg}] A numerical vector of the form \texttt{c(i, j, nr, nc)} where
\texttt{i} and \texttt{j} indicate which figure in an
\texttt{nr}-by-\texttt{nc} array of figures is currently being drawn.
\item[\texttt{mgp}] The margin line for the axis title, axis labels and axis
line.  The default is \texttt{c(3, 1, 0)}.
\item[\texttt{mkh}] The height in inches of symbols to be drawn when the value
of \texttt{pch} is an integer.
\item[\texttt{new}] logical, defaulting to \texttt{FALSE}.  If set to
\texttt{TRUE}, the next high-level plotting command (actually
\texttt{\Link{plot.new}(.)} should \emph{not clean} the frame before
drawing ``as if it was on a \bold{new} device''.
\item[\texttt{oma}] A vector of the form \texttt{c(bottom, left, top, right)} giving the
size of the outer margins in lines of text.
\item[\texttt{omd}] A vector of the form \texttt{c(x1, x2, y1, y2)} giving the
NDC coordinates of the region where (multiple) figures will appear
on the device.
\item[\texttt{omi}] A vector of the form \texttt{c(bottom, left, top, right)} giving the
size of the outer margins in inches.
\item[\texttt{pch}] Either an integer specifying a symbol or a single character
to be used as the default in plotting.
\item[\texttt{pin}] The width and height of the current plot in inches.
\item[\texttt{plt}] A vector of the form \texttt{c(x1, x2, y1, y2)} giving the
the coordinates of the plot region as fractions of the current
figure region.
\item[\texttt{ps}] integer; the pointsize of text and symbols.
\item[\texttt{pty}] A character specifying the type of plot region to be used;
\texttt{"s"} generates a square plotting region and \texttt{"m"}
generates the maximal plotting region.
\item[\texttt{smo}] (\emph{Unimplemented}) a value which indicates how smooth
circles and circular arc should be.
\item[\texttt{srt}] The string rotation in degrees.  Causes \texttt{srt} to be
set to the same value.
\item[\texttt{tck}] The length of tick marks as a fraction of the smaller of
the width or height of the plotting region.
If \texttt{tck=1}, grid lines are drawn. The default setting is
to use \texttt{tcl=-0.5} (see below).
\item[\texttt{tcl}] The length of tick marks as a fraction of the height
of a line of text.  The default value is \texttt{-0.5}.
\item[\texttt{tmag}] A number specifying the enlargement of text of the main
title relative to the other annotating text of the plot.
\item[\texttt{type}] character;  the default plot type desired, see
\texttt{\Link{plot.default}(type=...)}, defaulting to \texttt{"p"}.
\item[\texttt{usr}] A vector of the form \texttt{c(x1, x2, y1, y2)} giving the
extremes of the user coordinates of the plotting region.
\item[\texttt{xaxp}] A vector of the form \texttt{c(x1, x2, n)} giving the
coordinates of the extreme tick marks and the number of intervals
between tick-marks.
\item[\texttt{xaxs}] (\emph{Unimplemented}) The style of axis interval
calculation to be used for the x-axis.
\item[\texttt{xaxt}] A character which specifies the axis type.
Specifying \texttt{"n"} causes an axis to be set up, but not plotted.
\item[\texttt{xlog}] \emph{\bold{R.O.}}.  A logical value (see \texttt{log} in
\texttt{\Link{plot.default}}).
If \texttt{TRUE} a logarithmic scale is in use. For a new device, it
defaults to \texttt{FALSE}, i.e., linear scale.
\item[\texttt{xpd}] A logical value or NA.
If \texttt{FALSE}, all plotting is clipped to the plot region, if
\texttt{TRUE}, all plotting is clipped to the figure region, and if
\texttt{NA}, all plotting is clipped to the device region.
\item[\texttt{yaxp}] A vector of the form \texttt{c(y1, y2, n)} giving
the coordinates of the extreme tick marks and the number of
intervals between tick-marks.
\item[\texttt{yaxs}] (\emph{Unimplemented}) The style of axis interval
calculation to be used for the y-axis.
\item[\texttt{yaxt}] A character which specifies the axis type.
Specifying \texttt{"n"} causes an axis to be set up, but not plotted.
\item[\texttt{ylog}] \emph{\bold{R.O.}}.  A logical value (see \texttt{log} in
\texttt{\Link{plot.default}}).  See \texttt{xlog} above.
\end{ldescription}
\end{Arguments}
\begin{Description}
\texttt{par} can be used to set or query graphical parameters.
Parameters can be set by specifying them as arguments to \texttt{par} in
\texttt{tag = value} form, or by passing them as a list of tagged values.\end{Description}
\begin{Details}
The previous values are returned in an
invisible tagged list.  Such a list can be passed as an argument to
\texttt{par} to restore the parameter values.

Parameters are queried by giving vectors of character strings to
\texttt{par}.  In this case, the values are returned in a tagged list.

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

\emph{\bold{R.O.}} Arguments := \bold{Read-only arguments}:
These may only be used in queries, i.e.,  they do \emph{not} set anything.

All but these \emph{\bold{R.O.}} and the following \bold{low-level
arguments} can be set as well in high-level and mid-level plot
functions, such as \texttt{\Link{plot}}, \texttt{\Link{points}},
\texttt{\Link{lines}}, \texttt{\Link{axis}}, \texttt{\Link{title}},
\texttt{\Link{text}}, \texttt{\Link{mtext}}:
\Itemize{
\item \texttt{"ask"}
\item \texttt{"fig"}, \texttt{"fin"}
\item \texttt{"mai"}, \texttt{"mar"}, \texttt{"mex"}
\item \texttt{"mfrow"}, \texttt{"mfcol"}, \texttt{"mfg"}
\item \texttt{"new"}
\item \texttt{"oma"}, \texttt{"omd"}, \texttt{"omi"}
\item \texttt{"pin"}, \texttt{"plt"}, \texttt{"ps"}, \texttt{"pty"}
\item \texttt{"usr"}
\item \texttt{"xlog"}, \texttt{"ylog"}
}\end{Details}
\begin{Section}{Color Specification}
Colors can be specified in several
different ways.  The simplest way is with a character string giving
the color name (e.g., \texttt{"red"}).  A list of the possible colors
can be obtained with the function \texttt{\Link{colors}}.
Alternatively, colors can be specified directly in terms of there RGB
components with a string of the form \texttt{"\#RRGGBB"} where each of
the pairs \texttt{RR}, \texttt{GG}, \texttt{BB} consist of two hexadecimal
digits giving a value in the range \texttt{00} to \texttt{FF}.  Colors can
also be specified by giving an index into a small table of colors.
This provides compatibility with S.

The functions \texttt{rgb}, \texttt{hsv}, \texttt{gray} and \texttt{rainbow}
provide additional ways of generating colors.\end{Section}
\begin{Section}{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, 3=dotted) or directly as the lengths of on/off stretches of
line.  This is done with a string of up to eight characters which give
the lengths in consecutive positions in the string.  For example, the
string \texttt{"33"} specifies three pixels on followed by three off and
\texttt{"3313"} specifies three pixels on followed by three off followed
by one on and finally three off.\end{Section}
\begin{SeeAlso}
\texttt{\Link{plot.default}} for some high-level plotting parameters;
\texttt{\Link{colors}}, \texttt{\Link{gray}}, \texttt{\Link{rainbow}},
\texttt{\Link{rgb}};
\texttt{\Link{options}} for other setup parameters;
graphic devices \texttt{\Link{x11}}, \texttt{\Link{postscript}} and
setting up device regions by \texttt{\Link{layout}} and
\texttt{\Link{split.screen}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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)

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

( 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()
\end{ExampleCode}
\end{Examples}

