The options mechanism in R

[This article was first published on Burns Statistics » R language, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Customization in R.


Several features benefit from being customizable — either because of personal taste or specifics of the environment.

The way R implements this flexibility is through the options function.  This both sets and reports options.  For example, we can see the names of the options that are set by default:

> names(options())
 [1] "add.smooth"            "browser"              
 [3] "browserNLdisabled"     "check.bounds"         
 [5] "continue"              "contrasts"            
 [7] "defaultPackages"       "demo.ask"             
 [9] "device"                "device.ask.default"   
[11] "digits"                "echo"                 
[13] "editor"                "encoding"             
[15] "example.ask"           "expressions"          
[17] ""     "help.try.all.packages"
[19] "help_type"             "HTTPUserAgent"        
[21] ""         "keep.source"          
[23] "keep.source.pkgs"      "locatorBell"          
[25] "mailer"                "max.print"            
[27] ""         "na.action"            
[29] "nwarnings"             "OutDec"               
[31] "pager"                 "papersize"            
[33] "pdfviewer"             "pkgType"              
[35] "prompt"                "repos"                
[37] "scipen"                "show.coef.Pvalues"    
[39] "show.error.messages"   "show.signif.stars"    
[41] "str"                   "str.dendrogram.last"  
[43] "stringsAsFactors"      "timeout"              
[45] "ts.eps"                "ts.S.compat"          
[47] "unzip"                 "useFancyQuotes"       
[49] "verbose"               "warn"                 
[51] "warning.length"        "width"                
[53] "windowsTimeouts"

options returns a list.  Most of the options are not especially interesting — we’ll highlight a few of the most useful.


The digits option controls how many digits are printed (by default):

> 100/998
[1] 0.1002004
> options("digits")
[1] 7

The default value is 7.  We can change it:

> options(digits=4, prompt="R> ")
R> 100/998
[1] 0.1002
R> getOption("digits")
[1] 4
R> options(digits=20)
R> 100/998
[1] 0.10020040080160320939

Notice that the last few digits are noise (as per Circle 1 of The R Inferno).

A sort of related option is scipen — this controls which numbers are printed in scientific notation.


The width option says how many characters R should put on a line.  Adjusting this can be useful, for instance, if you write a blog and paste code into a place that doesn’t want many characters on a line.

If you get responses from R that look messy, it could be that width is larger than it should be.


If you experience R trauma, the warn option can be useful.  This takes the values:

  • 0: (the default) warnings are saved up until the top-level prompt is returned
  • 1: warnings are issued as soon as possible
  • 2: warnings are converted into errors (useful in combination with the error option)
  • -1(actually any negative number): do not issue warnings


This was not in the list above because its default value is NULL.  That is the wrong value for almost all people almost all of the time.  There are (at least) two better values.

The first better value is dump.frames:

R> options(error=dump.frames)
R> stop("here is an error")
Error: here is an error
R> debugger()
Message:  Error: here is an error
Available environments had calls:
1: stop("here is an error")

Enter an environment number, or 0 to exit  

The second better value is recover:

R> options(error=recover)
R> stop("here is a second errrrror")
Error: here is a second errrrror
No suitable frames for recover()

The (important) difference is that with recover you are thrown into the debugger automatically (if possible) when you encounter an error.  In contrast you need to call debugger yourself if you use dump.frames.

Of course in the examples here there is nothing to debug, but if this were a real emergency, then you would be presented with a stack of frames any of which you could enter and explore.

If you want to automatically change this option at startup, then you’ll want to specify the namespace (because not everything will be in place):

R> options(error=utils::dump.frames)
R> options(error=utils::recover)


If you intend to change an option but misspell it, then you have added a new option instead of changing the old one.  Page 45 of S Poetry has a function that warns you if you are adding any options.  That function would almost work in R except withVisible would be used instead of .Auto.print.


You are not restricted to the existing options.  You can use a new option of your choosing.  Options are usually not necessary for things that only impact one function — an argument with a default suffices in that setting.

Suppose we want to use a new option called leave.  This will obviously not be set in most people’s options.  A typical idiom is:

leave <- getOption("leave")
if(is.null(leave)) leave <- "drop off key"

In most cases the test should be more strict than just testing for NULL.

Deep End

In an R-devel thread started by Charles Geyer, Thomas Lumley offered the following function:

withOptions <- function(optlist, expr)
  oldopt <- options(optlist)
  expr <- substitute(expr)

This is an easy way to temporarily change one or more options while an expression is evaluated.

It is used like:

 R> print((1:10)^-1)
 [1] 1.0000000 0.5000000 0.3333333 0.2500000 0.2000000
 [6] 0.1666667 0.1428571 0.1250000 0.1111111 0.1000000
 R> withOptions(list(digits=3), print((1:10)^-1))
 [1] 1.000 0.500 0.333 0.250 0.200 0.167 0.143 0.125
 [9] 0.111 0.100

Extra credit for understanding:

 R> withOptions(list(digits=3), (1:10)^-1)
 [1] 1.0000000 0.5000000 0.3333333 0.2500000 0.2000000
 [6] 0.1666667 0.1428571 0.1250000 0.1111111 0.1000000


Make a new plan, Stan

from “50 Ways to Leave Your Lover” by Paul Simon


Other R language posts are:

The post The options mechanism in R appeared first on Burns Statistics.

To leave a comment for the author, please follow the link and comment on their blog: Burns Statistics » R language. offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)