Options Settings

Description

Allow the user to set and examine a variety of globaloptionswhich affect the way in whichR computes and displays its results.

Usage

options(...)getOption(x, default = NULL).Options

Arguments

Details

Invokingoptions() with no arguments returns a list with thecurrent values of the options. Note that not all options listed beloware set initially. To access the value of a single option, one shoulduse, e.g.,getOption("width") rather thanoptions("width") which is alist of length one.

Value

ForgetOption, the current value set for optionx, ordefault (which defaults toNULL) if the option is unset.

Foroptions(), a list of all set options sorted by name. Foroptions(name), a list of length one containing the set value,orNULL if it is unset. For uses setting one or more options,a list with the previous values of the options changed (returnedinvisibly).

Options used in baseR

add.smooth:

typically logical, defaulting toTRUE. Could also be set to an integer for specifying howmany (simulated) smooths should be added. This is currently onlyused byplot.lm.

askYesNo:

a function (typically set by a front-end)to ask the user binary response functions in a consistent way,or a vector of strings used byaskYesNo to useas default responses for such questions.

browserNLdisabled:

logical: whether newline isdisabled as a synonym for"n" in the browser.

checkPackageLicense:

logical, not set by default. Iftrue,loadNamespace asks a user to accept anynon-standard license at first load of the package.

check.bounds:

logical, defaulting toFALSE. Iftrue, a warning is produced whenever avector (atomic orlist) is extended, by somethinglikex <- 1:3; x[5] <- 6.

CBoundsCheck:

logical, controlling whether.C and.Fortran make copies to check forarray over-runs on the atomic vector arguments.

Initially set from value of the environment variableR_C_BOUNDS_CHECK (set toyes to enable).

conflicts.policy:

character string or list controllinghandling of conflicts found in calls tolibrary orrequire. Seelibrary for details.

continue:

a non-empty string setting the prompt usedfor lines which continue over one line.

defaultPackages:

the packages that are attached bydefault whenR starts up. Initially set from value of theenvironment variableR_DEFAULT_PACKAGES, or if that is unsettoc("datasets", "utils", "grDevices", "graphics", "stats", "methods"). (SetR_DEFAULT_PACKAGES toNULL ora comma-separated list of package names.) It will not work to setthis in a ‘.Rprofile’ file, as its value is consulted beforethat file is read.

deparse.cutoff:

integer value controlling theprinting of language constructs which aredeparsed.Default60.

deparse.max.lines:

controls the number of lines usedwhen deparsing inbrowser, upon entry to a functionwhose debugging flag is set, and if optiontraceback.max.linesis unset, oftraceback(). Initially unset, and onlyused if set to a positive integer.

traceback.max.lines:

controls the number of lines usedwhen deparsing intraceback, if set.Initially unset, and only used if set to a positive integer.

digits:

controls the number ofsignificant (seesignif) digits toprint when printing numeric values. It is a suggestion only.Valid values are 1...22 with default 7. See the note inprint.default about values greater than 15.

digits.secs:

controls the maximum number of digits toprint when formatting time values in seconds. Valid valuesare 0...6 with default 0. Seestrftime.

download.file.extra:

Extra command-line argument(s) fornon-default methods: seedownload.file.

download.file.method:

Method to be used fordownload.file. Currently download methods"internal","wininet" (Windows only),"libcurl","wget" and"curl" are available.If not set,method = "auto"is chosen: seedownload.file.

echo:

logical. Only used in non-interactive mode,when it controls whether input is echoed. Command-line option--no-echo sets this toFALSE, but otherwiseit starts the session asTRUE.

encoding:

The name of an encoding, default"native.enc". Seeconnections.

error:

either a function or an expression governingthe handling of non-catastrophic errors such as those generated bystop as well as by signals and internally detectederrors. If the option is a function, a call to that function,with no arguments, is generated as the expression. By defaultthe option is not set: seestop for the behaviour inthat case. The functionsdump.frames andrecover provide alternatives that allow post-mortemdebugging. Note that these need to specified ase.g.options(error = utils::recover) in startupfiles such as ‘.Rprofile’.

expressions:

sets a limit on the number of nestedexpressions that will be evaluated. Valid values are25...500000 with default 5000. If you increase it, you mayalso want to startR with a larger protection stack;see--max-ppsize inMemory. Note too thatyou may cause a segfault from overflow of the C stack, and on OSeswhere it is possible you may want to increase that. Once thelimit is reached an error is thrown. The current number underevaluation can be found by callingCstack_info.

interrupt:

a function taking no arguments to be calledon a user interrupt if the interrupt condition is not otherwisehandled.

keep.parse.data:

When internally storing source code(keep.source is TRUE), also store parse data. Parse data canthen be retrieved withgetParseData() and used e.g. forspell checking of string constants or syntax highlighting. The valuehas effect only when internally storing source code (seekeep.source). The default isTRUE.

keep.parse.data.pkgs:

As forkeep.parse.data, usedonly when packages are installed. Defaults toFALSE unless theenvironment variableR_KEEP_PKG_PARSE_DATA is set toyes.The space overhead of parse data can be substantial even aftercompression and it causes performance overhead when loading packages.

keep.source:

WhenTRUE, the source code forfunctions (newly defined or loaded) is stored internallyallowing comments to be kept in the right places. Retrieve thesource by printing or usingdeparse(fn, control = "useSource").

The default isinteractive(), i.e.,TRUE forinteractive use.

keep.source.pkgs:

As forkeep.source, used onlywhen packages are installed. Defaults toFALSE unless theenvironment variableR_KEEP_PKG_SOURCE is set toyes.

matprod:

a string selecting the implementation ofthe matrix products%*%,crossprod, andtcrossprod for double and complex vectors:

"internal"

uses an unoptimized 3-loop algorithmwhich correctly propagatesNaN andInf values and is consistent in precision withother summation algorithms insideR likesum orcolSums (which now means that it uses along double accumulator for summation if available and enabled,seecapabilities).

"default"

uses BLAS to speed up computation, butto ensure correct propagation ofNaN andInfvalues it uses an unoptimized 3-loop algorithm for inputs that maycontainNaN orInf values. When deemedbeneficial for performance,"default" may call the3-loop algorithm unconditionally, i.e., without checking theinput forNaN/Inf values. The 3-loop algorithm uses(only) adouble accumulator for summation, which isconsistent with the reference BLAS implementation.

"blas"

uses BLAS unconditionally without anychecks and should be used with extreme caution. BLASlibraries do not propagateNaN orInf values correctly and for inputs withNaN/Inf values the results may be undefined.

"default.simd"

is experimental and will likely beremoved in future versions ofR. It provides the same behavioras"default", but the check whether the input containsNaN/Inf values is faster on some SIMD hardware.On older systems it will run correctly, but may be much slower than"default".

max.print:

integer, defaulting to99999.print orshow methods can make use ofthis option, to limit the amount of information that is printed,to something in the order of (and typically slightly less than)max.printentries.

OutDec:

character string containing a singlecharacter. The preferred character to be used as the decimalpoint in output conversions, that is in printing, plotting,format andas.character but not whendeparsing nor bysprintf norformatC(which are sometimes used prior to printing.)

pager:

the command used for displaying text files byfile.show, details depending on the platform:

On a unix-alike

defaults to ‘R_HOME/bin/pager’, which is a shellscript running the command-line specified by the environmentvariablePAGER whose default is set at configuration,usually toless.

On Windows

defaults to"internal", which uses a pager similar to theGUI console. Another possibility is"console" to use theconsole itself.

Can be a character string or anR function, in which case itneeds to accept the arguments(files, header,title, delete.file) corresponding to the first four arguments offile.show.

papersize:

the default paper format used bypostscript; set by environment variableR_PAPERSIZE whenR is started: if that is unset or invalidit defaults platform dependently

on a unix-alike

to a value derived from the locale categoryLC_PAPER, or if that is unavailable to a default setwhenR was built.

on Windows

to"a4", or"letter" in US andCanadian locales.

PCRE_limit_recursion:

Logical: shouldgrep(perl = TRUE) and similar limit the maximalrecursion allowed when matching? Only relevant for PCRE1 andPCRE2 <= 10.23.

PCRE can be built not to use a recursion stack (seepcre_config), but it uses recursion by default witha recursion limit of 10000000 which potentially needs a very largeC stack: see the discussion athttps://www.pcre.org/original/doc/html/pcrestack.html. Iftrue, the limit is reduced usingR's estimate of the C stack sizeavailable (if known), otherwise 10000. IfNA, the limit isimposed only if any input string has 1000 or more bytes. Thelimit has no effect when PCRE's Just-in-Time compiler is used.

PCRE_study:

Logical or integer: shouldgrep(perl = TRUE) and similar ‘study’ thepatterns? Either logical or a numerical threshold for the minimumnumber of strings to be matched for the pattern to be studied (thedefault is10)). Missing values and negative numbers aretreated as false. This option is ignored with PCRE2 (PCRE version >=10.00) which does not have a separate study phase and patterns areautomatically optimized when possible.

PCRE_use_JIT:

Logical: shouldgrep(perl =TRUE),strsplit(perl = TRUE) and similar make useof PCRE's Just-In-Time compiler if available? (This applies only tostudied patterns with PCRE1.) Default: true. Missing values aretreated as false.

pdfviewer:

default PDF viewer.The default is set from the environment variableR_PDFVIEWER,the default value of which

on a unix-alike

is set whenR is configured, and

on Windows

is the full path toopen.exe, a utilitysupplied withR.

printcmd:

the command used bypostscriptfor printing; set by environment variableR_PRINTCMD whenR is started. This should be a command that expects either inputto be piped to ‘stdin’ or to be given a single filenameargument. Usually set to"lpr" on a Unix-alike.

prompt:

a non-empty string to be used forR's prompt;should usually end in a blank (" ").

rl_word_breaks:

(Unix only:) Used for the readline-based terminalinterface. Default value" \t\n\"\\'`><=%;,|&{()}".

This is the set of characters use to break the input line intotokens for object- and file-name completion. Those who do not usespaces around operators may prefer
" \t\n\"\\'`><=+-*%;,|&{()}"

save.defaults,save.image.defaults:

seesave.

scipen:

integer. A penalty to be appliedwhen deciding to print numeric values in fixed or exponentialnotation. Positive values bias towards fixed and negative towardsscientific notation: fixed notation will be preferred unless it ismore thanscipen digits wider.

setWidthOnResize:

a logical. If set andTRUE,Rrun in a terminal using a recentreadline library will setthewidth option when the terminal is resized.

showWarnCalls,showErrorCalls:

a logical.Should warning and error messages show a summary of the callstack? By default error calls are shown in non-interactivesessions.

showNCalls:

integer. Controls how long the sequenceof calls must be (in bytes) before ellipses are used. Defaults to40 and should be at least 30 and no more than 500.

show.error.locations:

Should source locations oferrors be printed? If set toTRUE or"top", thesource location that is highest on the stack (the most recentcall) will be printed."bottom" will print the locationof the earliest call found on the stack.

Integer values can select other entries. The value0corresponds to"top" and positive values count down thestack from there. The value-1 corresponds to"bottom" and negative values count up from there.

show.error.messages:

a logical. Should error messagesbe printed? Intended for use withtry or auser-installed error handler.

stringsAsFactors:

The default setting fordefault.stringsAsFactors, which inR < 4.1.0 wasused to provide the default values of thestringsAsFactorsargument ofdata.frame andread.table.

texi2dvi:

used by functionstexi2dvi andtexi2pdf in packagetools.

unix-alike only:

Set at startup from the environment variableR_TEXI2DVICMD,which defaults first to the value of environment variableTEXI2DVI, and then to a value set whenR was installed (thefull path to atexi2dvi script if one was found). Ifnecessary, that environment variable can be set to"emulation".

timeout:

positive integer. The timeout for someInternet operations, in seconds. Default 60 (seconds) but can beset from environment variableR_DEFAULT_INTERNET_TIMEOUT. (Invalid values of the option orthe variable are silently ignored: non-integer numeric values willbe truncated.) Seedownload.file andconnections.

topLevelEnvironment:

seetopenv andsys.source.

url.method:

character string: the default method forurl. Normally unset, which is equivalent to"default", which is"internal" except on Windows.

useFancyQuotes:

controls the use ofdirectional quotes insQuote,dQuote and inrendering text help (seeRd2txt in packagetools). Can beTRUE,FALSE,"TeX" or"UTF-8".

verbose:

logical. ShouldR report extra informationon progress? Set toTRUE by the command-line option--verbose.

warn:

integer value to set the handling of warning messages. Ifwarn is negative all warnings are ignored. Ifwarnis zero (the default) warnings are stored until the top–levelfunction returns. If 10 or fewer warnings were signalled theywill be printed otherwise a message saying how many weresignalled. An object calledlast.warning iscreated and can be printed through the functionwarnings. Ifwarn is one, warnings areprinted as they occur. Ifwarn is two (or larger, coercibleto integer), all warnings are turned into errors.

warnPartialMatchArgs:

logical. If true, warns ifpartial matching is used in argument matching.

warnPartialMatchAttr:

logical. If true, warns ifpartial matching is used in extracting attributes viaattr.

warnPartialMatchDollar:

logical. If true, warns ifpartial matching is used for extraction by$.

warning.expression:

anR code expression to be calledif a warning is generated, replacing the standard message. Ifnon-null it is called irrespective of the value of optionwarn.

warning.length:

sets the truncation limit in bytes for errorand warning messages. A non-negative integer, with allowed values100...8170, default 1000.

nwarnings:

the limit for the number of warnings keptwhenwarn = 0, default 50. This will discard messages ifcalled whilst they are being collected. If you increase thislimit, be aware that the current implementation pre-allocatesthe equivalent of a named list for them, i.e., do not increase it tomore than say a million.

width:

controls the maximum number of columns on aline used in printing vectors, matrices and arrays, and whenfilling bycat.

Columns are normally the same as characters except in East Asianlanguages.

You may want to change this if you re-size the window thatR isrunning in. Valid values are 10...10000 with default normally80. (The limits on valid values are in file ‘Print.h’ and can bechanged by re-compilingR.) SomeR consoles automatically changethe value when they are resized.

See the examples on Startup for one way to set thisautomatically from the terminal width whenR is started.

The ‘factory-fresh’ default settings of some of these options are

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

Options set in package grDevices

These will be set when packagegrDevices (or its namespace)is loaded if not already set.

bitmapType:

(Unix only, incl. macOS) character. Thedefault type for thebitmap devices such aspng. Defaults to"cairo" on systems where that is available, or to"quartz" on macOS where that is available.

device:

a character string givingthe name of a function, or the function object itself,which when called creates a new graphics device of the defaulttype for that session. The value of this option defaults to thenormal screen device (e.g.,X11,windows orquartz) for an interactive session, andpdfin batch use or if a screen is not available. If set to the nameof a device, the device is looked for first from the globalenvironment (that is down the usual search path) and then in thegrDevices namespace.

The default values in interactive and non-interactive sessions areconfigurable via environment variablesR_INTERACTIVE_DEVICE andR_DEFAULT_DEVICErespectively.

The search logic for ‘the normal screen device’ is thatthis iswindows on Windows, andquartz if availableon macOS (running at the console, and compiled into the build).OtherwiseX11 is used if environment variableDISPLAYis set.

device.ask.default:

logical. The default fordevAskNewPage("ask") when a device is opened.

locatorBell:

logical. Should selection inlocatorandidentify be confirmed by a bell? DefaultTRUE.Honoured at least onX11 andwindows devices.

windowsTimeout:

(Windows-only) integer vector of length 2representing two times in milliseconds. These control thedouble-buffering ofwindows devices when that isenabled: the first is the delay after plotting finishes(default 100) and the second is the update interval duringcontinuous plotting (default 500). The values at the time thedevice is opened are used.

Other options used by package graphics

max.contour.segments:

positive integer, defaulting to25000 if not set. A limit on the number ofsegments in a single contour line incontour orcontourLines.

Options set in package stats

These will be set when packagestats (or its namespace)is loaded if not already set.

contrasts:

the defaultcontrasts used inmodel fitting such as withaov orlm.A character vector of length two, the first giving the function tobe used with unordered factors and the second the function to beused with ordered factors. By default the elements are namedc("unordered", "ordered"), but the names are unused.

na.action:

the name of a function for treating missingvalues (NA's) for certain situations, seena.action andna.pass.

show.coef.Pvalues:

logical, affecting whether Pvalues are printed in summary tables of coefficients. SeeprintCoefmat.

show.nls.convergence:

logical, shouldnlsconvergence messages be printed for successful fits?

show.signif.stars:

logical, should stars be printed onsummary tables of coefficients? SeeprintCoefmat.

ts.eps:

the relative tolerance for certain time series(ts) computations. Default1e-05.

ts.S.compat:

logical. Used to select S compatibilityfor plotting time-series spectra. See the description of argumentlog inplot.spec.

Options set (or used) in package utils

These will be set (apart fromNcpus) when packageutils(or its namespace) is loaded if not already set.

BioC_mirror:

The URL of a Bioconductor mirrorfor use bysetRepositories,e.g. the default"https://bioconductor.org"or the European mirror"https://bioconductor.statistik.tu-dortmund.de". Can be setbychooseBioCmirror.

browser:

The HTML browser to be used bybrowseURL. This sets the default browser on UNIX ora non-default browser on Windows. Alternatively, anR functionthat is called with a URL as its argument. SeebrowseURL for further details.

ccaddress:

default Cc: address used bycreate.post (and hencebug.report andhelp.request). Can beFALSE or"".

citation.bibtex.max:

default 1; the maximal number ofbibentries (bibentry) in acitation forwhich the bibtex version is printed in addition to the text one.

de.cellwidth:

integer: the cell widths (number ofcharacters) to be used in the data editordataentry.If this is unset (the default), 0, negative orNA, variablecell widths are used.

demo.ask:

default for theask argument ofdemo.

editor:

a non-empty character string or anR functionthat sets the default text editor, e.g., foreditandfile.edit. Set from the environment variableEDITOR on UNIX, or if unsetVISUAL orvi.As a string it should specify the name of or path to an externalcommand.

example.ask:

default for theask argument ofexample.

help.ports:

optional integer vector for setting portsof the internal HTTP server, seestartDynamicHelp.

help.search.types:

default types of documentationto be searched byhelp.search and??.

help.try.all.packages:

default for an argument ofhelp.

help_type:

default for an argument ofhelp, used also as the help type by?.

HTTPUserAgent:

string used as the ‘user agent’ inHTTP(S) requests bydownload.file,urlandcurlGetHeaders, orNULL when requests willbe made without a user agent header. The default isR (<version> <platform> <arch> <os>)except whenlibcurl is used when it islibcurl/7.<xx>.<y> for thelibcurl version in use.

install.lock:

logical: should per-directory packagelocking be used byinstall.packages? Most usefulfor binary installs on macOS and Windows, but can be used in astartup file for source installsviaR CMD INSTALL. For binary installs, can also bethe character string"pkglock".

internet.info:

The minimum level of information to beprinted on URL downloads etc, using the"internal" and"libcurl" methods.Default is 2, for failure causes. Set to 1 or 0 to get moredetailed information (for the"internal" method 0 providesmore information than 1).

install.packages.check.source:

Used byinstall.packages (and indirectlyupdate.packages) on platforms which support binarypackages. Possible values"yes" and"no", withunset being equivalent to"yes".

install.packages.compile.from.source:

Used byinstall.packages(type = "both") (and indirectlyupdate.packages) on platforms whichsupport binary packages. Possible values are"never","interactive" (which means ask in interactive use and"never" in batch use) and"always". The default istaken from environment variableR_COMPILE_AND_INSTALL_PACKAGES, with default"interactive" if unset. However,install.packagesuses"never" unless amake program is found,consulting the environment variableMAKE.

mailer:

default emailing method used bycreate.post and hencebug.report andhelp.request.

menu.graphics:

Logical: should graphical menus be usedif available?. Defaults toTRUE. Currently applies toselect.list,chooseCRANmirror,setRepositories and to select from multiple (text)help files inhelp.

Ncpus:

an integern >= 1, used ininstall.packages as default for the number of cpusto use in a potentially parallel installation, asNcpus = getOption("Ncpus", 1L), i.e., when unset isequivalent to a setting of 1.

pkgType:

The default type of packages to be downloadedand installed – seeinstall.packages.Possible values are platform dependently

on Windows

"win.binary","source" and"both" (the default).

on Unix-alikes

"source" (the default except under aCRAN macOS build),"mac.binary" and"both" (the default for CRAN macOS builds).("mac.binary.el-capitan","mac.binary.mavericks","mac.binary.leopard"and"mac.binary.universal" are no longer in use.)

Value"binary" is a synonym for the native binary type (ifthere is one);"both" is used byinstall.packages to choose between source and binaryinstalls.

repos:

URLs of the repositories for use byupdate.packages. Defaults toc(CRAN="@CRAN@"), a value that causes some utilities toprompt for a CRAN mirror. To avoid this do set the CRAN mirror,by something likelocal({r <- getOption("repos"); r["CRAN"] <- "http://my.local.cran"; options(repos = r)}).

Note that you can add more repositories (Bioconductor,R-Forge, Rforge.net ...)usingsetRepositories.

SweaveHooks,SweaveSyntax:

seeSweave.

unzip:

a character string used byunzip:the path of the external programunzip or"internal".Defaults (platform dependently)

on unix-alikes

to the value ofR_UNZIPCMD, which is set in‘etc/Renviron’ to the path of theunzip command foundduring configuration and otherwise to"".

on Windows

to"internal" when the internal unzipcode is used.

Options set in package parallel

These will be set when packageparallel (or its namespace)is loaded if not already set.

mc.cores:

a integer giving the maximum allowed numberofadditionalR processes allowed to be run in parallel tothe currentR process. Defaults to the setting of theenvironment variableMC_CORES if set. Most applicationswhich use this assume a limit of2 if it is unset.

Options used on Unix only

dvipscmd:

character string giving a command to be used inthe (deprecated) off-line printing of help pagesviaPostScript. Defaults to"dvips".

Options used on Windows only

warn.FPU:

logical, by default undefined. If true,a warning is produced whenever dyn.load repairs thecontrol word damaged by a buggy DLL.

Note

For compatibility with S there is a visible object.Options whosevalue is a pairlist containing the currentoptions() (in noparticular order). Assigning to it will make a local copy and notchange the original. (Using it however is faster than callingoptions()).

An option set toNULL is indistinguishable from a non existingoption.

References

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

Examples

op <- options(); utils::str(op) # op is a named listgetOption("width") == options()$width # the latter needs more memoryoptions(digits = 15)pi# set the editor, and save previous valueold.o <- options(editor = "nedit")old.ooptions(check.bounds = TRUE, warn = 1)x <- NULL; x[4] <- "yes" # gives a warningoptions(digits = 5)print(1e5)options(scipen = 3); print(1e5)options(op)     # reset (all) initial optionsoptions("digits")## Not run: ## set contrast handling to be like Soptions(contrasts = c("contr.helmert", "contr.poly"))## End(Not run)## Not run: ## on error, terminate the R session with error status 66options(error = quote(q("no", status = 66, runLast = FALSE)))stop("test it")## End(Not run)## Not run: ## Set error actions for debugging:## enter browser on error, see ?recover:options(error = recover)## allows to call debugger() afterwards, see ?debugger:options(error = dump.frames)## A possible setting for non-interactive sessionsoptions(error = quote({dump.frames(to.file = TRUE); q()}))## End(Not run)  # Compare the two ways to get an option and use it  # acconting for the possibility it might not be set.if(as.logical(getOption("performCleanp", TRUE)))   cat("do cleanup\n")## Not run:   # a clumsier way of expressing the above w/o the default.tmp <- getOption("performCleanup")if(is.null(tmp))  tmp <- TRUEif(tmp)   cat("do cleanup\n")## End(Not run)