

   par {base}                                   R Documentation

   SSeett oorr QQuueerryy GGrraapphhiiccaall PPaarraammeetteerrss

   DDeessccrriippttiioon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Ussaaggee::

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

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

   AArrgguummeenntts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Deettaaiills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Coolloorr SSppeecciiffiiccaattiioon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Liinnee TTyyppee SSppeecciiffiiccaattiioon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Seeee AAllsso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Exxaammppllees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()

