par {graphics} | R Documentation

## 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

`...` | 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.

### 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 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"`,
- `"fig"`, `"fin"`,
- `"lheight"`,
- `"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.

The meaning of ‘character size’ is not well-defined: this is set up for the device taking `pointsize` into account but often not the actual font family in use. It can be considered to be an estimate of the size of character `M` in a proportionally-spaced font.

### 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 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.

### 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 calling `plot.default` do not annotate the plots they produce with axis titles 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. When called from `par()` it also sets `new=FALSE`. A description of how colors are specified is given below. Note that some graphics functions such as `plot.default` and `points` have an argument of this name with a different meaning.
`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. Note that some graphics functions such as `plot.default` have an argument of this name which multiplies this graphical parameter.
`cex.axis`
  The magnification to be used for axis annotation relative to the current setting of `cex`. (Some functions such as `points` accept a vector of values which are recycled. Other uses will take just the first value if a vector of length greater than one is supplied.)
`cex.lab`
  The magnification to be used for x and y labels relative to the current setting of `cex`.
`cex.main`
  The magnification to be used for main titles relative to the current setting of `cex`.
`cex.sub`
  The magnification to be used for sub-titles relative to the current setting of `cex`.
`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. (Some functions such as `lines` accept a vector of values which are recycled. Other uses will take just the first value if a vector of length greater than one is supplied.)
`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, `(width,height)`, in inches.
`err`
  (Unimplemented; R is silent when points outside the plot region are not plotted.) The degree of error reporting desired.
`family`
  The name of a font family for drawing text. The maximum allowed length is 200 bytes. This name gets mapped by each graphics device to device-specific font descriptions. The default value is `""` 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. As from R 2.3.0 this can be specified inline for `text`.
`fg`
  The color to be used for the foreground of plots. This is the default color used for things like axes and boxes around plots. When called from `par()` this also sets parameter `col` to the same value.

  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. If you set this, unlike S, you start a new plot, so to add to an existing plot use `new=TRUE` as well.
`fin`
  The figure region dimensions, `(width,height)`, in inches. If you set this, unlike S, you start a new plot.
`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. Also, font 5 is expected to be the symbol font, in Adobe symbol encoding. On some devices font families can be selected by `family` to choose different sets of 5 fonts.
`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`. 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`
  A numerical vector of the form `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`
  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.

`lend`
  The line end style. This can be specified as an integer or string:
  `0`
    and `"round"` mean rounded line caps [default];
  `1`
    and `"butt"` mean butt line caps;
  `2`
    and `"square"` mean square line caps.

  As from R 2.3.0 this can be specified inline.

`lheight`
  The line height multiplier. The height of a line of text (used to vertically space multi-line text) is found by multiplying the current font size both by the current character expansion and by the line height multiplier. Default value is 1.
`ljoin`
  The line join style. This can be specified as an integer or string:
  `0`
    and `"round"` mean rounded line joins [default];
  `1`
    and `"mitre"` mean mitred line joins;
  `2`
    and `"bevel"` mean bevelled line joins.

  As from R 2.3.0 this can be specified inline.

`lmitre`
  The line mitre limit. This controls when mitred line joins are automatically converted into bevelled line joins. The value must be larger than 1 and the default is 10. Not all devices will honour this setting.

  As from R 2.3.0 this can be specified inline.

`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(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.

  Some functions such as `lines` accept a vector of values which are recycled. Other uses will take just the first value if a vector of length greater than one is supplied.

`lwd`
  The line width, a positive number, defaulting to `1`. The interpretation is device-specific, and some devices do not implement line widths less than one. (Some functions such as `lines` accept a vector of values which are recycled. Other uses will take just the first value if a vector of length greater than one is supplied.)
`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 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`
  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.

  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`
  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. See `points` for possible values and their interpretation.
`pin`
  The current plot dimensions, `(width,height)`, 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 (but not symbols). Unlike the `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`
  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. See the comment about `crt`.
`tck`
  The length of tick marks as a fraction of the smaller of the width or height of the plotting region. If `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`
  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`
  Currently unused: defaults to `1.2`.
`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, `10 ^ par("usr")[1:2]`. (The `"usr"` coordinates are log10-transformed here!)
  n=1
    will produce tick marks at 10^j for integer j,
  n=2
    gives marks k 10^j with k in {1, 5},
  n=3
    gives marks k 10^j with k in {1, 2, 5}.

  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`
  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 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`
  A character which specifies the x axis type. Specifying `"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`
  A 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 y axis type. Specifying `"n"` suppresses plotting.
`ylog`
  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 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 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 ‘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`.

Currently zero hex digits are accepted and handled in a device-dependent way, e.g. `X11()` maps them to one, `pdf()` regards zero as terminating the string and `windows()` gives a zero-length stretch. Do not rely on such behaviour, which will change in R 2.4.0.

### 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.

### 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`; `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
    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()

[Package graphics version 2.3.1 Index]