

par {base}                                   R Documentation

_S_e_t _o_r _Q_u_e_r_y _G_r_a_p_h_i_c_a_l _P_a_r_a_m_e_t_e_r_s

_D_e_s_c_r_i_p_t_i_o_n_:

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

_U_s_a_g_e_:

     par(..., no.readonly = FALSE)

     <highlevel plot> (..., <tag> = <value>)

_A_r_g_u_m_e_n_t_s_:

no.readonly: logical; if `TRUE' and there are no other argu-
          ments,  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' pro-
          duces 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 annota-
          tion.

     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"', 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 plot-
          ting 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 rela-
          tive to the current.

 cex.sub: The magnification to be used for sub-titles rela-
          tive 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 sin-
          gle 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.

     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=dot-
          ted, 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 code{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 fig-
          ures 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 warn-
          ing.

     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 plot-
          ting region.

    xaxp: A vector of the form `c(x1, x2, n)' giving the
          coordinates of the extreme tick marks and the num-
          ber 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 con-
          trolled 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.  Speci-
          fying `"n"' causes an axis to be set up, but not
          plotted.

    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 num-
          ber 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.  Speci-
          fying `"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.

_D_e_t_a_i_l_s_:

     The former values are returned in an invisible tagged
     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 in that
     case.

     Parameters are queried by giving vectors of character
     strings to `par'.  In this case, the values are
     returned in a tagged list.

     `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 vari-
     able `.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 argu-
     ments 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"'

_C_o_l_o_r _S_p_e_c_i_f_i_c_a_t_i_o_n_:

     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' pro-
     vide additional ways of generating colors.

_L_i_n_e _T_y_p_e _S_p_e_c_i_f_i_c_a_t_i_o_n_:

     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 fol-
     lowed by three off followed by one on and finally three
     off.

_S_e_e _A_l_s_o_:

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

_E_x_a_m_p_l_e_s_:

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

