options
Set or Return Options

Description

Provides a means to control certain aspects of Spotfire Enterprise Runtime for R behavior, such as the number of digits printed, the maximum number of characters to place on a line, or strategies for memory management.

Usage

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

Arguments

x a character string giving an option name.
... the arguments in either the form of name=value, or of character strings specifying option names. Alternatively, it can be a single list argument with elements in the form of name=value.
default used as return value if the specified option is not set.

Details

The special options listed in this help file are driven by the object .Options in the package:base enviroment. The options function provides the best and most convenient way to set and reset the components of this object. To set options temporarily in a function, call options as you normally would from the command line. Note that this changes options on a global level in your session, however, and not simply in the frame of the function. To ensure that your function finishes cleanly and produces no side effects, use on.exit with the return value from your call to options.
There might be special options that do not exist by default but are recognized by various functions when they are set.
If there are particular options or values that you want to remain defined from session to session, call options in a .First function.
Value
Common options
While any option name can be used in a call to options, the ones listed here have special meaning.
browser
specifies the default HTML browser, used as the default value for the browser argument to help.start and browseURL.
continue
the string printed by the console to prompt for the continuation of an incomplete expression. The default is "+ ". See also the options prompt and continueString.
continueString
the string printed by the console to prompt for the continuation of an incomplete string. The default is "Continue string: ". See also the options prompt and continue.
contrasts
a vector of two character strings naming the default contrasts to use for unordered factors and for ordered factors, respectively. This is primarily used in analysis of variance models.
dateformat.lenient
specifies whether date/time parsing should be lenient in as.Date.character. If this is TRUE (the default), some date/time strings may be accepted even if the text does not match exactly the date format string. If this is FALSE, date/time strings that do not exactly match the date format string will produce an NA value.

For example, if this option is FALSE, the expression as.Date("12/2/1") will produce an NA date object, since the date string does not match the default format string "yyyy.MM.dd". However, if this option is TRUE, this expression will produce the date "2012-02-01".

defaultPackages
Specifies the packages to be loaded (in addition to "base") on startup. By default, these are "utils", "grDevices", "graphics", "stats", and "methods".
device
The default option, "terrFakeDev", is implemented to provide a stub for graphics compatibility.
digits
the number of significant digits to use in print (and therefore in automatic printing). Setting digits=17 gives the full length of double-precision numbers. A valid value is 1 to 22. The default is 7.
echo
a logical flag. If TRUE, prompt strings are printed, and each complete expression is echoed before it is evaluated when the input is not an interactive tty connection. The default is TRUE.
encoding
the default character encoding when opening input streams with functions like file or source. Used for converting input bytes to characters. The default is "UTF-8".
example.ask
The default value for the ask argument to the example function. This is initially "default".
expressions
the maximum depth to which expressions can be nested. This option exists primarily to catch runaway recursive calls in a function. A valid value is 25 to 500000. The default is 300. Note that this protects against stack overflow and cannot be safely expanded beyond about 300. The precise maximum safe value depends on the platform, whether Java is being used or not, and which C functions are being called recursively.
hashDiagnostics
specifies whether to print diagnostic messages when manipulating hash tables, used in certain internal algorithms. The default is FALSE.
hasHyperThreads
specifies whether the processor should use hyperthreading. Initially, this is 1 if the processor supports hyperthreads, 0 otherwise. Setting this to zero will disable hyperthreading. Setting this to one will enable hyperthreading, if it is supported by the processor. Setting this to a negative integer will reinitialize its value to zero or one, depending on whether the processor supports hyperthreads.
help.ports
a vector of port numbers to be used by startDynamicHelp for the dynamic HTTP help server. If this is NULL (the default), startDynamicHelp will try a set of random port numbers.
help.search.types
the default value to be used for the types argument to help.search. This is initially c("vignette", "demo", "help").
help.try.all.packages
the default value to be used for the try.all.packages argument to help This is initially FALSE.
help_type
the default value to be used for the help_type argument to help. This is initially "html" on Windows platforms and "text" otherwise.
HTTPUserAgent
a character string containing the user agent string for HTTP requests sent via a url connection. If NULL, no user agent string is used.
immediateObjectReuse
specifies whether the memory management system should immediately reuse object storage when an object's reference count goes to zero (if the value is TRUE, the default), or whether it should wait for the garbage collector to reclaim it.
interrupt
if this is a function, it will be called with no arguments if an interrupt condition is not caught. If this function invokes a restart named "resume", the interrupted computation is resumed.
keep.source
the default value to be used for the keep.source argument to source and parse. This is initially TRUE.
keep.source.pkgs
the default value to be used for the keep.source argument to library, require, loadNamespace, and sys.source. This is initially TRUE.
max.print
the maximum number of elements to print by print.default. The default is 5000.
mkl.num.threads
the maximum number of threads used by the Intel MKL numeric library. A negative value means to use the value of the environment variable MKL_NUM_THREADS if it is defined, otherwise it uses the value of the option omp.num.threads. The default is -1.
na.action
the default value to be used for the na.action argument to modeling functions such as lm, glm, etc. This is initially "na.omit".
omp.dynamic.threads
a logical flag. If TRUE, the actual number of threads used by OpenMP-enabled functions is determined by OpenMP, and can be less than the number specified by omp.num.threads. The default is TRUE.
omp.num.threads
the maximum number of threads used by OpenMP-enabled functions. Setting this to a negative value will automatically set it to the value of the environment variable OMP_NUM_THREADS if it is defined, otherwise the number of physical cores. The initial value is set to the number of physical cores.
OutDec
This option is not currently used in Spotfire Enterprise Runtime for R. The default is ".".
pkgType
a character string indicating the type of package to download, install, or update. Used as the default value for the type argument for several functions including available.packages and install.packages. This is initially "win.binary" on Windows platforms, "mac.binary.mavericks" on Mac platforms, and "source" otherwise.
prompt
the string printed by the console to prompt for an expression. The default is "> ". See also the options continue and continueString.
repos
a character vector containing URLs that point to specific packages repositories. Used as the default value for the type argument for several functions including download.packages, install.packages and update.packages.
saveRFormat
a logical flag used for the default of the RFormat argument of save. If this argument is TRUE save writes files using an R compatible format, which is a bit less efficient. The default is FALSE.

scipen
an integer value as penalty to bias towards fixed(positive penalty) or scientific(negative penalty) notation when printing numeric values. The fixed notation will be used when its fixed width is no more than its scientific width plus "scipen" for a real number or pure imaginary.

For a complex number, the fixed notation will be used when its total fixed widths is less than its total scientific widths plus "scipen"*2.

shareDataThreshold
a positive integer or NA. If this is not NA, the memory system will attempt to share vector storage, rather than copying, for vectors whose length is equal or greater than this value. The default is 64L.
sharePartialData
a logical flag. When extracting a subset of a vector, if this option is TRUE and the length of the subset is greater or equal to shareDataThreshold, the memory system will attempt to share vector storage, rather than copying, The default is TRUE.
show.signif.stars
a logical flag used for the default of the signif.stats argument of print.anova, summary.lm, printCoefmat, etc. The default is TRUE.
ssl.ca.bundle
a character string indicating the path to an SSL certificate authority bundle containing the root certificates that should be used by URL connections to SSL-encrypted servers. This is used when creating a connection with url with a URL scheme such as "https". If NULL, use the system provided trusted certificate authority store on platforms where it is available. The default is NULL.
ssl.verify
a logical flag used to control whether SSL verification is performed on SSL connections. The server's certificate is verified to make sure it is issued by a certificate authority in the SSL certificate authority bundle, and that the hostname in the certificate matches the hostname used in the URL. The default is TRUE.
str
a list of options that specify defaults for several arguments of the str function. An appropriate list can be constructed by calling strOptions.
strictNA
a logical flag. If FALSE, then NA and NaN values are considered the same for many functions, which can improve performance. The default is TRUE.
stringsAsFactors
a logical flag that provides the default value for the argument of the same name in the data.frame, and read.table functions (which retrieve this value via the default.stringsAsFactors function). If stringsAsFactors=TRUE, character input is converted to factors in newly-created data frames. The default is FALSE.

Note that as of version 5.2 of Spotfire Enterprise Runtime for R, default.stringsAsFactors() returns FALSE instead of the previous TRUE unless the user has execututed options(stringsAsFactors=TRUE) earlier in the session. This matches the same change in version 4.0.0 of open-source R.

timeout
an integer. The timeout for connecting to and reading from URL connections, in seconds. The default is 60.
ts.eps
a small number specifying the time series comparison tolerance. This is used throughout the time series functions for frequency comparisons. Frequencies are considered equal if they differ in absolute value by less than ts.eps. The default value is 1e-05.
url.debug
a character value that specifies a filename to verbosely log information about the setup of URL connections to as they are initalized, or NULL to disable verbose logging of URL connections. The default is NULL.
url.method
a character string specifying the default method used to create URL connections via the url() function when no method= argument is given. It can have any valid value for url(method=...). Acceptable values are "default", "wininet", "libcurl", and "internal". The "wininet" method is supported on only Windows systems.
useFancyQuotes
specifies which quote characters are used by sQuote and dQuote. The default is FALSE, which says to use unidirectional ASCII quote characters.
vectorizeRNG
a logical flag specifying whether to use vectorized versions of the Intel MKL random number generators, which are more efficient at generating many random numnbers at once. The default is TRUE.
verbose
a logical flag specifying whether verbose messages should be printed. This option provides the default value for the argument of the same name in several functions including source, library, data, gc, etc. The default is FALSE.
warn
specifies how the system should handle warnings generated by calling the warning function or from internal system warnings.
  • warn=-1: Warning messages are ignored.
  • warn=0 (the default): Warnings are collected and printed at the end of the evaluation. The maximum number of unique warnings that are collected is controlled by the warning.save option, which defaults to 50. If more unique warnings are generated, they are turned into a single warning such as "warning dropped (123 times)" giving the number of warnings dropped. The function warnings will return the stored messages.
  • warn=1: Warning messages are printed as they happen, no matter how many there may be.
  • warn=2: Warnings are converted into errors that terminate evaluation of the expression.
Fatal errors, like those generated by calling stop, are unaffected by the warn option.
warning.length
the length (in characters) of error and warning messages. Anything longer than that value is truncated. A valid value is 100 to 7170, and the default is 1000. This option is not currently used in Spotfire Enterprise Runtime for R.
warning.save
the number of distinct warnings that are saved when the warn option is 0. The default value is 50.
width
the width (in characters) of an output page. A valid value is 10 to 10000. The default value is 80.

Side Effects
When options are set, the options function changes a list named .Options in the package:base enviroment. The components of .Options are all of the currently-defined options. If options is called with either a list as the single argument, or with one or more arguments in name=value form, the options specified are changed or created.
Examples
# Set the maximum length of lines to 50 characters
# and return a list of length one.
width.old <- options(width=50)
1:100 # print with width of 50
# Restore old width
options(width.old)
getOption("width")
1:100 # print with original width

# View two particular options.
options("width", "warn")

# Set the prompt and the continuation prompt.
prompts.old <- options(prompt="Say something! ", continue="\t")
# Perform some computations and then restore 
# both the prompt and continue prompts.
options(prompts.old)

# define silent.eval to temporarily silence warnings,
silent.eval <- function(x) {
	old <- options(warn=-1)
	on.exit(options(old))
	return(x)
}
# call silent.eval to avoid warning "NAs introduced by coercion"
silent.eval(as.integer(c("1","xyz")))
Package base version 6.1.4-13
Package Index