depcache.options: Caching options

Description

Control how the dependencies are gathered and hashed to locate the determine the file name to load the cached object from.

Usage

depcache.options(
  defaults = getOption("depcache.version", '0.1'),
  skip = getOption("depcache.skip", NULL),
  dir, compress, local.only, format.version
)

Arguments

defaults

A string containing the version of depcache to get other defaults from. If not set, takes the value from the depcache.version option (see options), falling back to the current version of the package.

To make the caching more reproducible against package updates, call options(depcache.version = something) once at the top of your scripts.

Currently, only version 0.1 is accepted. When a new version of the package changes the defaults or adds new settings, the range of the accepted values will expand.

skip

A character vector of variables to omit from automatically-gathered dependencies. Variables carrying unintended or unimportant state, which would otherwise interfere with obtaining a reproducible hash, should be listed here. This may be useful when a symbol encountered in the expression doesn't signify a variable in the evaluation frame (e.g. non-standard evaluation when plotting with lattice), or when the variable is being assigned to as part of the expression.

Defaults to the depcache.skip option, or NULL if unset.

dir

The directory to store the cache files inside. Defaults to the depcache.dir option, or .depcache in depcache version 0.1.

compress

Passed as the compress option to saveRDS when saving the cached objects. Defaults to the depcache.compress option, or TRUE in depcache version 0.1.

local.only

If TRUE, only variables available in the same environment where the caching function has been called from are considered as dependencies; parent environments are ignored. Typically, this means taking local variables as parts of the hash that determines the file name, but not loaded packages or attached datasets. Setting this to FALSE may invalidate the cache next time a package or R itself is updated.

Defaults to the depcache.local.only option, or TRUE in depcache version 0.1.

format.version

Passed as the version argument to saveRDS and also used when serialising any objects to hash them. Only versions 2 and 3 are supported. Defaults to the depcache.format.version option, or 2 in depcache version 0.1.

Value

A list containing the settings to be used by the caching system.

dir

The directory used for storage of the cache files.

compress

Passed to saveRDS.

skip

Variables to skip when hashing the dependencies of the expressions.

local.only

Whether to ignore non-local dependencies.

format.version

Passed to saveRDS as the version argument. Also determines the format version when serialising the variables to hash them.

Details

In all cases, explicitly passed arguments override settings from the options(), which override the defaults. Depending on the defaults argument or the depcache.version option, the defaults may change; setting it explicitly will help your scripts stay forward-compatible.

This function shouldn't be normally called by the user (except, perhaps, to verify the parameters about to be passed to the caching functions), but it is automatically invoked on every call to cache, setCached, or the use of cache-tracking assignment operators %<-% and %->%. Any additional options passed to the functions as … are handled here, and so are the global options.

Examples

Run this code

# NOT RUN {
  
# }
# NOT RUN {
  # The output is affected by the user's use of options(...) and the
  # current version of the package
  options(depcache.local.only = FALSE)
  print(depcache.options(format.version = 3))
  options(depcache.local.only = TRUE)
  print(depcache.options())

  # "skip" makes it possible to avoid mistaking arguments evaluated in a
  # non-standard way for local variables
  speed <- 1
  options(depcache.skip = 'speed')
  x %<-% { message('fitting the model'); lm(dist ~ speed, cars) }
  speed <- 0
  # not fitted again despite change in local variable "speed"
  summary(x)
  
# }