par                 package: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 variable '.Pars'. '.Pars.readonly'
     contains the names of the 'par' arguments which are _readonly_.

     _*R.O.*_ indicates _*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 just 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.

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 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.*_; 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.

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

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

     '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.  The default is
          'c(5, 5, 7)'. _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 argument 'srt'
          to 'par') 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(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.

     'lwd' The line width, a _positive_ number, 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 '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. 

     '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 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 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' 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.  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,
          'par("usr")[1:2]'.  See 'axTicks()' for more details.

     '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' 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 axis type. Specifying '"n"'
          causes an axis to be set up, but not plotted.

     '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', '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'.

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.

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

     plot(1:2, xaxs = "i") # 'inner axis' w/o extra space
     stopifnot(par("xaxp")[1:2] == 1:2 &&
               par("usr") [1:2] == 1:2)

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

