options                 package:base                 R Documentation

Options Settings

Description:

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

Usage:

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

Arguments:

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

       x: a character string holding an option name.

Details:

     Invoking 'options()' with no arguments returns a list with the
     current values of the options.  Note that not all options listed
     below are set initially.  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.

     '.Options' also always contains the 'options()' list, for S
     compatibility.  You must use it "read only" however.

Value:

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

Options used in base R:

     '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.  Valid values are 10...10000 with default normally 80. 
          (The valid values are in file 'Print.h' and can be changed by
          re-compiling R.)

     'digits': controls the number of digits to print when printing
          numeric values.  It is a suggestion only.  Valid values are
          1...22 with default 7.  See 'print.default'.

     '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, also used by 'file.show' and sometimes
          'help'. Defaults to '$R_HOME/bin/pager'.


     'browser': default HTML browser used by 'help.start()' on UNIX, or
          a non-default browser on Windows.

     'pdfviewer': default PDF viewer.  Set from the environment
          variable 'R_PDFVIEWER'.

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

     'defaultPackages': the packages that are attached by default when
          R starts up.  Initially set from value of the environment
          variables 'R_DefaultPackages', or if that is unset to
          'c("utils", "stats", "graphics", "methods")'.  (Set
          'R_DEFAULT_PACKAGES' to 'NULL' or a comma-separated list of
          package names.)  A call to 'options' should be in your
          '.Rprofile' file to ensure that the change takes effect
          before the base package is initialized (see 'Startup').

     'expressions': sets a limit on the number of nested expressions
          that will be evaluated. Valid values are 25...100000 with
          default 500.

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

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

     'error': either a function or an expression governing the handling
          of non-catastrophic errors such as those generated by 'stop'
          as well as by signals and internally detected errors.  If the
          option is a function, a call to that function, with no
          arguments, is generated as the expression.  The default value
          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.

     'warning.length': sets the truncation limit for error and warning
          messages.  A non-negative integer, with allowed values
          100-8192, default 1000.

     'warning.expression': an R code expression to be called if a
          warning is generated, replacing the standard message.  If
          non-null is called irrespective of the value of option
          'warn'.

     'check.bounds': logical, defaulting to 'FALSE'.  If true, a
          warning is produced whenever a "generalized vector" (atomic
          or 'list') is extended, by something like 'x <- 1:3; x[5] <-
          6'.

     'echo': logical.  Only used in non-interactive mode, when it
          controls whether input is echoed.  Command-line option
          '-slave' sets 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>.

     'repositories': A function that when evaluated returns a named
          vector of URLs which can be used to specify the set and order
          of any online repositories the user would like used in
          functions such as 'packageDepends'.  The default return value
          for the function is a vector with two components, one the 
          value of 'contrib.url(getOption("CRAN"))' and the second
          'contrib.url(getOption("BIOC"))'.

     'download.file.method': Method to be used for 'download.file'. 
          Currently download methods '"internal"', '"wget"' and
          '"lynx"' are available. There is no default for this option,
          when 'method = "auto"' is chosen: see 'download.file'.

     'unzip': the command used for unzipping help files. Defaults to
          the value of 'R_UNZIPCMD', which is set in 'etc/Renviron' if
          an 'unzip' command was found during configuration.

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

     'encoding': An integer vector of length 256 holding an input
          encoding.  Defaults to 'native.enc' (= '0:255'). See
          'connections'.

     'timeout': integer.  The timeout for some Internet operations, in
          seconds.  Default 60 seconds. See 'download.file' and
          'connections'.

     'internet.info': The minimum level of information to be printed on
          URL downloads etc.  Default is 2, for failure causes. Set to
          1 or 0 to get more information.

     'scipen': integer.  A penalty to be applied when deciding to print
          numeric values in fixed or exponential notation.  Positive
          values bias towards fixed and negative towards scientific
          notation: fixed notation will be preferred unless it is more
          than 'scipen' digits wider.

     'locatorBell': logical.  Should selection in 'locator' and
          'identify' be confirmed by a bell.  Default 'TRUE'. Honoured
          at least on 'X11' and 'windows' devices.

     'X11fonts': character vector of length 2. See 'X11'.

     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'     'show.error.messages'  'TRUE'
       'warn'               '0'        'warning.length'       '1000'
       'echo'               'TRUE'     'verbose'              'FALSE'
       'scipen'             '0'        'locatorBell'          'TRUE'

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

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

Examples:

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

     # .Options is the same:
     all(sapply(1:length(op), function(i) if(is.atomic(op[[i]]))
                              {all(.Options[[i]] == op[[i]])} else TRUE))

     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(check.bounds = TRUE)
     x <- NULL; x[4] <- "yes" # gives a warning

     options(digits=5)
     print(1e5)
     options(scipen=3); print(1e5)

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

     ## Not run: 
     ## set contrast handling to be like S
     options(contrasts=c("contr.helmert", "contr.poly"))
     ## End(Not run)
     ## Not run: 
     ## on error, terminate the R session with error status 66
     options(error=quote(q("no", status=66, runLast=FALSE)))
     stop("test it")
     ## End(Not run)
     ## Not run: 
     ## set an error action for debugging: see ?debugger.
     options(error=dump.frames)
     ## A possible setting for non-interactive sessions
     options(error=quote({dump.frames(to.file=TRUE); q()}))
     ## End(Not run)

