par                   package: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 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.

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

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

_V_a_l_u_e:

     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.

_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' provide
     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 followed 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()

