options {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. 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("ts", "nls", "modreg", "mva", "ctest", "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 `print.coefmat`.
`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 http://cran.r-project.org.
`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.

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.messags` | `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) 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(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')

    ## Don't run:
    ## set contrast handling to be like S
    options(contrasts=c("contr.helmert", "contr.poly"))
    ## End Don't run
    ## Don't run:
    ## on error, terminate the R session with error status 66
    options(error=quote(q("no", status=66, runLast=FALSE)))
    stop("test it")
    ## End Don't run
    ## Don't 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 Don't run

[Package Contents]