par {base} | 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

`no.readonly` | logical; if `TRUE` and there are no other arguments, only parameters are returned which can be set by a subsequent `par(.)` call.
`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. Note that the `adj` argument of `text` and `mtext` also allows `adj= c(x,y)` for different adjustment in x- and y- direction.
`ann` | If set to `FALSE`, high-level plotting functions do not annotate the plots they produce with axis 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. A description of how colors are specified is given below.
`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.
`cex.axis` | The magnification to be used for axis annotation relative to the current.
`cex.lab` | The magnification to be used for x and y labels relative to the current.
`cex.main` | The magnification to be used for main titles relative to the current.
`cex.sub` | The magnification to be used for sub-titles relative to the current.
`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.
`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.. The 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 in inches.
`err` | (Unimplemented; R is silent when points outside the plot region are not plotted.) The degree of error reporting desired.
`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.
`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.
`fin` | A numerical vector of the form `c(x, y)` which gives the size of the figure region in inches.
`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.
`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 `hsv(.., gamma)`.
`lab` | A numerical vector of the form `c(x, y, len)` which modifies the 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 size. Currently, `len` is unimplemented.

`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 `par(srt = ..)`) does not affect the axis labels.

`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(0:9, "A":"F")`) may be given, giving the length (typically in points/pixels) of line segments which are alternatively drawn and skipped. For example, `"44"` is dashed and `"13"` is dotted.

`lwd` | The line width, a positive numerical, defaulting to `1`.
`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 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.
`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. 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 `nc` 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.
`pin` | The width and height of the current plot 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 and symbols.
`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 arc should be.
`srt` | The string rotation in degrees.
`tck` | The length of tick marks as a fraction of the smaller of the width or height of the plotting region. If `tck=1`, grid lines are drawn. The default setting 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`.
`tmag` | A number specifying the enlargement of text of the main title relative to the other annotating text of the plot.
`type` | character; the default plot type desired, see `plot.default(type=...)`, defaulting to `"p"`.
`usr` | A vector of the form `c(x1, x2, y1, y2)` giving the extremes of the user coordinates of the plotting region.
`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.

`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 ensured 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 axis type. Specifying `"n"` causes an axis to be set up, but not plotted. The standard value is `"s"`: for compatibility with S values `"l"` and `"e"` are accepted but are equivalent to `"s"`.
`xlog` | R.O.. A logical value (see `log` in `plot.default`). If `TRUE` a logarithmic scale is in use. 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.
`yaxs` | The style of axis interval calculation to be used for the y-axis. See `xaxs` above.
`yaxt` | A character which specifies the axis type. Specifying `"n"` causes an axis to be set up, but not plotted.
`ylog` | R.O.. A logical value (see `log` in `plot.default`). See `xlog` above.

### 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 named list). Their names are currently taken from the variable `.Pars`. `.Pars.readonly` contains the names of the `par` arguments which are readonly.

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

All but these R.O. and the following low-level arguments can be set as well in high-level and mid-level plot functions, such as `plot`, `points`, `lines`, `axis`, `title`, `text`, `mtext`:

- `"ask"`
- `"fig"`, `"fin"`
- `"mai"`, `"mar"`, `"mex"`
- `"mfrow"`, `"mfcol"`, `"mfg"`
- `"new"`
- `"oma"`, `"omd"`, `"omi"`
- `"pin"`, `"plt"`, `"ps"`, `"pty"`
- `"usr"`
- `"xlog"`, `"ylog"`

### 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 one parameter is queried, the value is a character string. When two or more parameters are queried, the result is a list of character strings, with the list names giving the parameters.

Note the inconsistency: setting one parameter returns a list, but querying one parameter returns a vector.

### 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 there 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. This provides compatibility with S.

The functions `rgb`, `hsv`, `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, 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 `"33"` specifies three pixels on followed by three off and `"3313"` specifies three pixels on followed by three off followed by one on and finally three off.

### See Also

`plot.default` for some high-level plotting parameters; `colors`, `gray`, `rainbow`, `rgb`; `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

    ( 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()

[Package Contents]