Using options

In R, options allow the user to set and examine a variety of global options which affect the way in which R computes and displays its results. For instance, for the usethis package, the usethis.quiet option can control whether usethis is chatty¹. Users either:

• write options(usethis.quiet = TRUE) at the beginning of a script or directly in the console;

• or write that same line in their .Rprofile that’s loaded before every session, which is more persistent.

Users can use a project-level or more global user-level .Rprofile. The use of a project-level .Rprofile overrides the user-level .Rprofile unless the project-level .Rprofile contains the following lines as mentioned in the blogdown book:

# in .Rprofile of the project
if (file.exists('~/.Rprofile')) {
  base::sys.source('~/.Rprofile', envir = environment())
}
# then set project options

For more startup tweaks, the user could adopt the startup package.

As a package developer in your code you can retrieve options by using getOption() whose second argument is a fallback for when the option hasn’t been set by the user. Note that an option can be any R object.

options(blabla.foo = TRUE)
if (isTRUE(getOption("blabla.foo", FALSE))) {
  message("foo!")
}

## foo!

options(blabla.bar = mean)
getOption("blabla.bar")(c(1:7))

## [1] 4

The use of options in the .Rprofile startup file is great for workflow packages like usethis, blogdown, etc., but shouldn’t be used for, say, arguments influencing the results of a statistical function.

Using environment variables

Environment variables, found via Sys.getenv() rather than getOption(), are often used for storing secrets (like GITHUB_PAT for the gh package) or the path to secrets on disk (like TWITTER_PAT for rtweet), or not secrets (e.g. the browser to use for chromote).

Similar to using options() in the console or at the top of a script the user could use Sys.setenv(). Obviously, secrets should not be written at the top of a script that’s public. To make environment variables persistent they need to be stored in a startup file, .Renviron. .Renviron does not contain R code like .Rprofile, but rather key-value pairs that are only called via Sys.getenv().

As a package developer, you probably want to at least document how to set persistent variables or provide a link to such documentation; and you could even provide helper functions like what rtweet does.

Using credential stores for secrets

Although say API keys are often stored in .Renviron, they could also be stored in a standard and more secure location depending on the operating system. The keyring package allows to interact with such credential stores. You could either take it on as a dependency like e.g. gh, or recommend the user of your package to use keyring and to add a line like

Sys.setenv(SUPERSECRETKEY = keyring::key_get("myservice"))

in their scripts.

Using a config file

The batchtools package expect its users to setup a config file somewhere if they don’t want to use the defaults. That somewhere can be several locations, as explained in the batchtools::findConfFile() manual page. Two of the possibilities are rappdirs::user_config_dir("batchtools", expand = FALSE) and rappdirs::site_config_dir("batchtools") which refer to standard locations that are different depending on the operating system.

The golem package offers its users the possibility to use a config file based on the config package.

A good default experience

Obviously, on top of letting users set their own preferences, you probably want your package functions to have sensible defaults. :grin:

Asking or guessing?

For basic information such as username, email, GitHub username, the whoami package does pretty well.

whoami::whoami()

##                       username                       fullname 
##                 "jimmy.briggs"                 "Jimmy Briggs" 
##                  email_address                    gh_username 
## "jimmy.briggs@oliverwyman.com"                      "jimbrig"

whoami::email_address()

## [1] "jimmy.briggs@oliverwyman.com"

In particular, for the email address, if the R environment variable EMAIL isn’t set, whoami uses a call to git to find Git’s global configuration. Similarly, the gert package can find and return Git’s preferences via gert::git_config_global()².

In these cases where packages guess something, their guessing is based on the use of standard locations for such information on different operating systems. Unsurprisingly, in the next section, we’ll recommend using such standard locations when caching data.

rappdirs or not

To use an app directory from within your package you can use rappdirs as mentioned earlier, but also other tools.

• Package developers might also like the hoardr package that basically creates an R6 object building on rappdirs with a few more methods (directory creation, deletion).

Lots of pkgs already roll their own version of this, some use {rappdirs}. I roll my own in {R.cache} for memoization to file. In {startup}, I use it for optional anacron-like hourly,daily,weekly, ... startup scripts

— Henrik Bengtsson (@henrikbengtsson) February 28, 2020

• Some package authors “roll their own” like Henrik Bengtsson in R.cache.

Oh là là! R-devel just gained support for OS-agile user-specific #rstats cache/config/data folders:

> tools::R_user_dir("aPkg", "cache")
[1] "/home/alice/.cache/R/aPkg"

> tools::R_user_dir("aPkg", "config")
[1] "/home/alice/.config/R/aPkg"

This is big!https://t.co/sfH87AwGZX

— Henrik Bengtsson (@henrikbengtsson) February 28, 2020

• R-devel “just gained support for OS-agile user-specific #rstats cache/config/data folders” which is big (but if you use the base R implementation available after R 4.x.y, unless your package depends on R above that version you’ll need to backport the functionality ³).

Caching results within an R session

To cache results within an R session, you could use a temporary directory for data. For any function call you could use memoise that supports, well memoization which is best explained with an example.

time <- memoise::memoise(Sys.time)
time()

## [1] "2020-09-16 23:20:45 EDT"

Sys.sleep(1)
time()

## [1] "2020-09-16 23:20:45 EDT"

Only the first call to time() actually calls Sys.time(), after that the results is saved for the entire session unless memoise::forget() is called. It is great for speeding up code, and for not abusing internet resources which is why the polite package wraps memoise.

Providing a ready-to-use dataset in a non-CRAN package

If your package depends on the use of a huge dataset, the same for all users, that is by definition too huge for CRAN, you can use a setup like the one presented by Brooke Anderson and Dirk Eddelbuettel in which the data is packaged up in a separate package not on CRAN, that the user will install therefore saving the data on disk somewhere where you can find it easily.⁴

My Setup

• RProfile

• Dotfiles and Preferences

• Cache Utils

• R Setup Script

if (interactive()) {
  suppressMessages(suppressWarnings(require(devtools)))
  suppressMessages(suppressWarnings(require(testthat)))
}

# cran mirror
options(repos = c(CRAN='https://cran.rstudio.com/'))
# or
# options(repos = c(CRAN='https://cloud.r-project.org'))

# install packages in parallel via 'Ncpus' argument
# https://www.jumpingrivers.com/blog/speeding-up-package-installation/
# parallel::detectCores() == 8 (8 total cores, 4 physical, 4 hyper-threading, ~6 max)
options(Ncpus = 6L)

# turn on completion of installed package names
utils::rc.settings(ipck = TRUE)

# usethis / devtools
options(
  usethis.protocol = "ssh",
  usethis.description = list(
    `Authors@R` = '
          person("Jimmy", "Briggs",
          email = "jimmy.briggs@oliverwyman.com",
          role = c("aut", "cre"))',
    License = "MIT + file LICENSE",
    Language =  "es"
  )
)

# addinit
options(
  "addinit" = list(
    author = "Jimmy Briggs <jimmy.briggs@oliverwyman.com>",
    project = list(
      folders = list(
        default = c("R", "inst", "man", "data-raw", "data", "tests", "vignettes"),
        selected = c("R", "man")
      ),
      packages = list(
        default = rownames(utils::installed.packages()),
        selected = "shiny"
      )
    )
  )
)

# dev and old libraries
options(
  "dev_lib" = "C:/Users/jimmy.briggs/Computer/Program Files/R/win-library/Dev",
  "old_lib" = "C:/Users/jimmy.briggs/Computer/Program Files/R/win-library/Old"
)

# map network drives - runs a batch/vbs script file
if (!dir.exists("H:/")) {
  cmd_path <- normalizePath("C:\\windows\\OWGLocalLoginScript.vbs")
  cmd <- paste0("WScript ", '"', cmd_path, '"')
  system(command = cmd, wait = TRUE)
  if (dir.exists("H:/") && dir.exists("G:/")) {
    usethis::ui_info("Successfully mapped H:/ and G:/ Drives!")
  }
  rm(cmd_path, cmd)
  invisible(gc())
}

# timezone
TZ=UTC

# environment paths
R_HOME="C:\Users\jimmy.briggs\Documents"
R_LIBS_USER="C:\Users\jimmy.briggs\Computer\Program Files\R\win-library\4.0"
R_USERDATA_DIR="C:\Users\jimmy.briggs\AppData\Roaming\R\data\R"
RSTUDIO_MSYS_SSH="C:\Program Files/RStudio/bin/msys-ssh-1000-18"
RSTUDIO_PANDOC="C:/Program Files/RStudio/bin/pandoc"
MYSQL_HOME="C:/Users/jimmy.briggs/sql/"
JAVA_HOME="C:/java/jdk-11"
# Ghostscript
# qpdf
# etc.

# add Rtools and Rterm/R.exe to sys path
PATH="${RTOOLS40_HOME}\usr\bin;${PATH}"
PATH="C:/Program Files/R/bin/x64/"

# specs
R_ARCH=x64
RSTUDIO_SESSION_PORT=24886
RSTUDIO_USER_IDENTITY=jimmy.briggs
GITHUB_USERNAME=jimbrig

# credentials
GITHUB_PAT=<secret>
TODOIST_API_TOKEN=<secret>
TMETRIC_API_TOKEN=<secret>
GOOGLEDRIVE_API_TOKEN=<secret>

# and more...