Set or Return Options

DESCRIPTION:

Provides a means to control certain aspects of S-PLUS behavior such as the number of digits printed, the maximum number of characters to place on a line, and strategies for memory management.

USAGE:

options(...)
getOption(x)

REQUIRED ARGUMENTS:

x
a character string giving an option name.

OPTIONAL ARGUMENTS:

...
a list or vector of character strings may be given as the only argument, or any number of arguments may be in name=value form. In addition, no arguments at all may be given. See the VALUE and SIDE EFFECTS sections for explanation.

COMMON OPTIONS:

While any option name can be used in a call to options, the ones listed here have special meaning.

OPTIONS CONCERNING THE SESSION ENVIRONMENT

contrasts

a vector of two character strings naming the default contrasts to use for factors and for ordered factors, respectively. This is primarily used in analysis of variance models.

echo
a logical flag: if TRUE, each complete expression is echoed before it is evaluated.
width
the width (in characters) of an output page. In the GUI application, if width is set to (or the current value has an attribute of) "auto", it automatically changes to reflect the width of the current output window. Otherwise, width remains the same regardless of the size of the current output window. You can also set width to "auto", or the width of the current output window, by using the function.
length
the length (in lines) of an output page. In the GUI application, if length is set to (or the current value has an attribute of) "auto", it automatically changes to reflect the length of the current output window. Otherwise, length remains the same regardless of the size of the current output window. You can also set length to "auto", or the length of the current output window, by using the function.
prompt
the string to be printed by the S-PLUS parser to prompt for an expression.
continue
the string to be printed by the S-PLUS parser to prompt for the continuation of an expression.
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.
help.pager
a character string naming the pager to use when displaying HTML text in a terminal window (as opposed to the GUI). This should be an HTML-aware viewer, such as the default slynx browser. See the pager argument to help for other possibilities.
help.browser
This option is currently ignored.
editor
a character string naming the command used to open a text editor. This is used in the history function, for example. The editor you choose must be invoked in the style of the S-PLUS functions ed and vi. That is, it must be invoked by a command of the form ed filename, followed by the reading of editing commands from the terminal. Do not supply editors that expect a different invocation or a different form of user interaction.
pager
a character string naming the default pager program. This is used in various places, including the help and page functions. Examples of pagers are the UNIX programs more and view. The pager you choose is invoked as pager filename and should read from the filename specified. The default for pager is the value of environment variable S_PAGER, which in turn defaults to the value of PAGER, or "less" if PAGER is not set.
interactive
a logical flag: if TRUE, S-PLUS runs interactively. The S-PLUS process itself normally decides whether it is running interactively. You can test its decision within a function by calling . Occasionally, you might need to run a normally interactive function like in a non-interactive way. If so, use this option, but with extreme caution. Many side effects such as prompting for expressions depend on whether S-PLUS is running interactively.
keep
This option is currently ignored.
verify
the level of internal verification for objects. At level 1 (the default), objects are verified on permanent assignment to be consistent with the representations for their classes. Setting verify=0 suppresses this verification; this is sometimes needed when changing class definitions.
completions
a logical flag that controls name completion in copies of functions within the evaluator. If completions=T, the evaluator completes partially matched names in its copy of the function. In this case, partial matching occurs only on the first call, which speeds up subsequent function calls. If completions=F (the default), this completion is turned off.
conflicts.ok
a logical flag that controls the warnings which occur when two definitions exist in different libraries for the same function. Setting conflicts.ok=T suppresses the normal warnings that S-PLUS issues in this situation.
indentation
a character string used as the normal indent when formatting function definitions. The default value is a tab character "\t".
stringsAsFactors
a logical flag that provides the default value for the argument of the same name in the data.frame, read.table, and importData functions. If stringsAsFactors=TRUE, character input is converted to factors in newly-created data frames.
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.
sequence.tol
a number specifying the tolerance for converting numeric vectors to numeric sequences. If a numeric vector is an arithmetic sequence to within sequence.tol, it can be converted to a sequence.
time.in.format
a character string specifying the format for reading timeDate objects from character strings using the as and timeDate functions. The default value is "%m[/][.]%d[/][,]%y [%H[:%M[:%S[.%N]]][%p][[(]%3Z[)]]]", which will read a wide variety of date strings. To use the European day/month/year format, set this to "%d[/][.]%m[/][,]%y [%H[:%M[:%S[.%N]]][%p][[(]%3Z[)]]]" . The elements of this format string are described in the documentation for the timeDate class ( ).
time.out.format
a character string specifying the format for printing timeDate objects to character strings. The default value is "%02m/%02d/%04Y %02H:%02M:%02S.%03N". To use the European day/month/year format, set this to "%02d/%02m/%04Y %02H:%02M:%02S.%03N" . The elements of this format string are described in the documentation for the timeDate class ( ).
time.out.format.notime
a character string specifying the format for printing timeDate objects when the time.zone option is set to GMT and the time of every element of the timeDate object is midnight. See for more information.
time.month.name
a 12-element character vector giving the names of the months.
time.month.abb
a 12-element character vector giving the abbreviations for the names of the months.
time.day.name
a 7-element character vector giving the names of the days of the week, starting with Sunday.
time.day.abb
a 7-element character vector giving the abbreviations for the names of the days of the week, starting with Sunday.
time.century
an integer indicating the first year of a 100-year span. This value is used to interpret and print two-digit years. For example, if time.century=1950, the year 50 is interpreted as 1950 and the year 49 is interpreted as 2049. If time.century=1900, the year 0 means 1900 and the year 99 means 1999.
time.am.pm
a 2-element character vector giving strings for printing "AM" and "PM" in time objects.
time.zone
a character string specifying the default time zone when none is given in a time object.
tspan.in.format
a character string specifying the format for reading timeSpan objects from character strings using the as and timeSpan functions.
tspan.out.format
a character string specifying the format for printing timeSpan objects to character strings.
pkgType
a character string indicating the type of package to download, install or update. Used by several functions in the pkgutils library.
repos
a URL that points to a specific data repository. Used by several functions in the pkgutils library. Default is "http://spotfire.tibco.com/csan".

OPTIONS CONCERNING ERROR HANDLING
check

a logical flag: if TRUE, S-PLUS performs various internal checks during evaluation. This provides more information about warning messages and reloading, and may help track down mysterious bugs (that cause S-PLUS to terminate abnormally, for example). On the other hand, this has been known to introduce strange behavior. Evaluation is substantially slower when this option turned on.

deprecated.warn
an integer controlling the frequency of warnings produced when calling deprecated functions. Calls to a deprecated function containing a call to the function .Deprecated can generate a warning message depending on the value of this option. Possible values are:
   -1 => no warning
    0 or NULL => always warn
    1 => warn only once in a session
The default value is deprecated.warn=NULL.
error
a function with no arguments that should be called when an error or interrupt occurs. S-PLUS provides the functions dump.calls and dump.frames for this purpose; they dump the outstanding function calls and all associated frames, respectively. For more details, see the help file for these functions. Setting error=NULL eliminates all error actions.
interrupt
a function with no arguments that should be called when an interrupt occurs. The function is called in the frame that is active when the interrupt happens. It can be used, for example, to examine current objects, change values, etc. If two interrupts occur in a row, the interrupt action is not executed; instead the error action is carried out. The option interrupt=NULL eliminates all interrupt actions.
warn
the level of strictness at which the system should warn you about non-fatal warnings. At level 0, the first 50 warnings are collected and printed at the end of the evaluation. If there are more than 50 warnings, a notice is printed that gives the total number that was generated. At level 1, warning messages are printed as they happen, however many there may be. At level 2, warnings are converted into errors that terminate evaluation of the expression. Any negative value for warn (i.e., warn=-1) suppresses all warning messages. Fatal errors, like those generated by calling stop, are inescapable and unaffected by the warn option.
warning.expression
a S-PLUS expression to evaluate when there is a warning to report. This augments the warn option. If warn=-1, the warning expression is not invoked; if warn=2, the warning is turned into an error and the error expression is invoked. However, if warn=0 or warn=1, just the warning expression is invoked. The S-PLUS function get.message returns the warning message itself and returns the call stack at the time of the warning. For example,

options(warning.expression=expression(cat("Warning in", substring(deparse(sys.calls()[[sys.nframe()]])[1], 1, 40), ":", get.message(), "\\n")))

is very similar to using options(warn=1) with no warning expression.
expressions
the maximum depth to which expressions can be nested. This exists primarily to catch runaway recursive calls in a function. Note that this protects against stack overflow and cannot be safely expanded beyond about 1000. Precise value depends on platform, using Java or not, and which C functions are being called recursively.
verbose
If TRUE then S-PLUS will print informational messages about what it is doing. E.g., it will print the time it takes to complete each expression and importData will print some information about the imported data.

OPTIONS CONCERNING MEMORY USAGE
audit.size

the maximum size (in characters) for the audit file. If this limit is exceeded at the beginning of a session, a warning message is printed. You should then use the TRUNC_AUDIT utility to reduce the size of the audit file.

compact
This option is currently ignored.
memory
the maximum size (in bytes) for all in-memory data. If this limit is exceeded, the session is terminated to avoid runaway computations that may slow down or crash the computing system. You may want to check for memory growth by calling the function ; if things get out of hand, quit and re-invoke S-PLUS.
object.size
the maximum size (in bytes) for any single S-PLUS object. If this limit is exceeded, an error is generated and the session continues.
bigdata.threshold
the minimum file size which triggers alert dialogs to appear in the GUI when you do file import. The default setting for this option is 10,000,000 (or about 10 MB). If the file you are trying to import has a size that is greater than this value, an alert dialog is displayed.
suppress.graphics.warnings
a logical flag: if TRUE, any new graphics device is initialized with par(err=-1) . This has the effect of suppressing graphics warning messages such "points out of bounds" by default. To enable graphics warning messages, set par(err=0).

DEFAULT VALUES:

The default values for some of the common options listed above are as follows. Options that have never been set have the value NULL.

   audit.size=5e5
   check=FALSE
   compact=1e5
   completions=FALSE
   conflicts.ok=FALSE            
   continue="+ "
   contrasts=c("contr.treatment", "contr.poly")
   deprecated.warn=NULL
   digits=7                      
   echo=FALSE
   editor="vi"                   
   error=expression(dump.calls())
   expressions=256               
   verbose=F
   gui=NULL
   indentation="\t"              
   interrupt=NULL
   help.browser="netscape"       
   help.pager="slynx"
   keep="function"               
   length=48
   memory=2147483647             
   object.size=Inf
   pager="less"                  
   pkgType="source"
   prompt="> "
   repos="http://spotfire.tibco.com/csan"
   sequence.tol=1e-6             
   show=TRUE
   stringsAsFactors=TRUE
   time.am.pm=c("AM", "PM")      
   time.century=1930
   time.in.format="[%m[/][.]%d[/][,]%y] [%H[:%M[:%S[.%N]]][%p][[(]%3Z[)]]]"
   time.out.format="%02m/%02d/%Y %02H:%02M:%02S.%03N"
   time.day.abb=c("Sun", "Mon", ..., "Sat")
   time.day.name=c("Sunday", "Monday", ..., "Saturday")
   time.month.abb=c("Jan", "Feb", ..., "Dec")
   time.month.name=c("January", "February", ..., "December")
   time.zone="GMT"
   tspan.in.format=paste("[%yy[ear[s]][,]] [%dd[ay[s]][,]]",
     "[%Hh[our[s]][,]] [%Mm[in[ute][s]][,]] [%Ss[ec[ond][s]][,]]",
     "[%NM[s][S]]")
   tspan.out.format="%dd %Hh %Mm %Ss %NMS",
   ts.eps=1e-5                      
   verify=1
   warn=0                           
   width=80

VALUE:

The options function always returns a list, even if the list of length 1; it differs from the function in this respect. If no arguments are given, options returns a list of current values for all options. If a character vector is given as the only argument, a list of current values for the options named in the character vector is returned. If an object of mode "list" is given as the only argument, its components become the values for options with the corresponding names. S-PLUS returns a list of the option values before they were modified. Generally, the list given as an argument is the return value of a previous call to options. If arguments are given in name=value form, S-PLUS changes the values of the specified options and returns a list of the option values before they were modified.

The getOption function returns the value of a single argument, so it may be a character string, a numeric value, a logical value, etc.

SIDE EFFECTS:

When options are set, the options function changes a list named .Options in the session frame (frame 0). 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.

DETAILS:

The special options listed in this help file are driven by the object .Options. 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 S-PLUS 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 does not produce any side effects, use with the return value from your call to options. See the chapter "Writing Functions in S-PLUS" in the Programmer's Guide for additional details.

There may be special options that do not exist by default but are recognized by various functions when set. For example, setting options(core.dump=T) causes S-PLUS to create a file named core if S-PLUS terminates abnormally. The core.dump option does not exist by default, but is nevertheless recognized by S-PLUS.

If there are particular options or values that you wish to remain defined from session to session, call options in a function.

The getOption function was added for compatibility with R.

SEE ALSO:

, , , , , , , , , , , , , .

EXAMPLES:

# Set the maximum length of lines to 50 characters
# and return a list of length one.
width.old <- options(width=50)
width.old
# Set width to 80
if (getOption("width") < 80) options(width=80)
getOption("width")
# View two particular options.
options(c("object.size", "indentation"))  
# Set the S-PLUS prompt and the continuation prompt.
temp <- options(prompt="Say something! ", continue="\t")
# Perform some computations and then restore 
# both the S-PLUS and continue prompts.
options(temp) 
silent.eval <- function(expr) {
        old <- options(warn=(-1))
        on.exit(options(old))
        return(expr)
}
silent.log <- function(x) {
        old <- options(warn=(-1))
        on.exit(options(old))
        return(log(x))
}
silent.log(-3)