options                 package:base                 R Documentation

_O_p_t_i_o_n_s _S_e_t_t_i_n_g_s

_D_e_s_c_r_i_p_t_i_o_n:

     `options' allows the user to set and examine a variety of global
     ``options'' which affect the way in which R computes and displays
     its results.

_U_s_a_g_e:

     options(...)
     getOption(x)
     .Options

_A_r_g_u_m_e_n_t_s:

     ...: any options can be defined, using `name = value'. However,
          only the ones below are used in ``base R''.

          Further, `options('name') == options()['name']', see the
          example. 

  prompt: a string, used for R's prompt; should usually end in a blank
          (`" "').

continue: a string setting the prompt used for lines which continue
          over one line.

   width: controls the number of characters on a line.  You may want to
          change this if you re-size the window that R is running in.

  digits: controls the number of digits to print when printing numeric
          values.  It is a suggestion only.

  editor: sets the default text editor, e.g., for `edit'. Set from the
          environment variable `VISUAL' on UNIX.

   pager: the (stand-alone) program used for displaying ASCII files on
          R's console. Defaults to `$R_HOME/bin/pager'. 

 browser: default HTML browser used by `help.start()' on UNIX.

  mailer: default mailer used by `bug.report()'. can be `"none"'.

contrasts: the default `contrasts' used in model fitting such as with
          `aov' or `lm'.  A character vector of length two, the first
          giving the function to be used with unordered factors and the
          second the function to be used with ordered factors.

expressions: sets a limit on the number of nested expressions that will
          be evaluated.  This is especially important on the Macintosh
          since stack overflow is likely if this is set too high.

keep.source: When `TRUE', the source code for functions (newly defined
          or loaded) is stored in their `"source"' attribute (see
          `attr') allowing comments to be kept in the right places.

          The default is `interactive()', i.e., `TRUE' for interactive
          use.

keep.source.pkgs: As for `keep.source', for functions in packages
          loaded by `library' or `require'. Defaults to `FALSE' unless
          the environment variable `R_KEEP_PKG_SOURCE' is set to `yes'.

na.action: the name of a function for treating missing values (`NA''s)
          for certain situations.

papersize: the default paper format used by `postscript'; set by
          environment variable `R_PAPERSIZE' when R is started and
          defaulting to `"a4"' if that is unset or invalid.

printcmd: the command used by `postscript' for printing; set by
          environment variable `R_PRINTCMD' when R is started. This
          should be a command that expects either input to be piped to
          `stdin' or to be given a single filename argument.

latexcmd, dvipscmd: character strings giving commands to be used in
          off-line printing of help pages.

show.signif.stars, show.coef.Pvalues: logical, affecting P value
          printing, see `print.coefmat'.

  ts.eps: the relative tolerance for certain time series (`ts')
          computations.

   error: an expression governing the handling of non-catastrophic
          errors such as those generated by `stop' as well as by
          signals and internally detected errors. The default
          expression is `NULL': see `stop' for the behaviour in that
          case. The function `dump.frames' provides one alternative
          that allows post-mortem debugging.

show.error.messages: a logical. Should error messages be printed? 
          Intended for use with `try' or a user-installed error
          handler.

    warn: sets the handling of warning messages.  If `warn' is negative
          all warnings are ignored.  If `warn' is zero (the default)
          warnings are stored until the top-level function returns.  If
          fewer than 10 warnings were signalled they will be printed
          otherwise a message saying how many (max 50) were signalled. 
          A top-level variable called `last.warning' is created and can
          be viewed through the function `warnings'.  If `warn' is one,
          warnings are printed as they occur.  If `warn' is two or
          larger all warnings are turned into errors.

    echo: logical. Only used in non-interactive mode, when it controls
          whether input is echoed. Command-line options `--quiet' and
          `--slave' set this initially to `FALSE'.

 verbose: logical. Should R report extra information on progress? Set
          to `TRUE' by the command-line option `--verbose'.

  device: a character string giving the default device for that
          session. This defaults to the normal screen device (e.g.
          `x11', `windows' or `gtk') for an interactive session, and
          `postscript' in batch use or if a screen is not available.

X11colortype: The default colour type for `X11' devices.

    CRAN: The URL of the preferred CRAN node for use by
          `update.packages'. Defaults to <URL:
          http://cran.r-project.org>.

   unzip: the command used unzipping help files. 

de.cellwidth: integer: the cell widths (number of  characters) to be
          used in the data editor `dataentry'.  If this is unset, 0,
          negative or `NA', variable cell widths are used.

       x: a character string holding one of the above option names.

_D_e_t_a_i_l_s:

     Invoking `options()' with no arguments returns a list with the
     current values of the options.  To access the value of a single
     option, one should use `getOption("width")', e.g., rather than
     `options("width")' which is a list of length one.

     The default settings of some of these options are

       `prompt'             `"> "'     `continue'           `"+ "'
       `width'              `80'       `digits'             `7'
       `expressions'        `500'      `keep.source'        `TRUE'
       `show.signif.stars'  `TRUE'     `show.coef.Pvalues'  `TRUE'
       `na.action'          `na.omit'  `ts.eps'             `1e-5'
       `error'              `NULL'     `warn'               `0'
       `echo'               `TRUE'     `verbose'            `FALSE'

     Others are set from environment variables or are
     platform-dependent.

_V_a_l_u_e:

     A list (in any case) with the previous values of the options
     changed, or all options when no arguments were given.

_E_x_a_m_p_l_e_s:

     options() # printing all current options
     op <- options(); str(op) # nicer printing

     # .Options is the same:
     all(sapply(1:length(op), function(i) all(.Options[[i]] == op[[i]])))

     options('width')[[1]] == options()$width # the latter needs more memory
     options(digits=20)
     pi

     # set the editor, and save previous value
     old.o <- options(editor="nedit")
     old.o

     options(op)     # reset (all) initial options
     options('digits')

     ## set contrast handling to be like S
     options(contrasts=c("contr.helmert", "contr.poly"))

     ## on error, terminate the R session with error status 66
     options(error=quote(q("no", status=66, runLast=FALSE)))
     stop("test it")

     ## set an error action for debugging: see ?debugger.
     options(error=quote(dump.frames()))
     ## A possible setting for non-interactive sessions
     options(error=quote({dump.frames(to.file=TRUE); q()}))

