Create a new cache or load a previously created cache.

Given a unique name for an R object, and instructions for how to make that object, use the simpleCache function to create and cache or load the object. This should be used for computations that take a long time and generate a table or something used repeatedly (in other scripts, for example). Because the cache is tied to the object name, there is some danger of causing troubles if you misuse the caching system. The object should be considered static.

simpleCache(cacheName, instruction = NULL, buildEnvir = NULL,
  reload = FALSE, recreate = FALSE, noload = FALSE,
  cacheDir = getCacheDir(), cacheSubDir = NULL, timer = FALSE,
  buildDir = getOption("RBUILD.DIR"), assignToVariable = NULL,
  loadEnvir = parent.frame(),
  searchEnvir = getOption("SIMPLECACHE.ENV"), nofail = FALSE,
  batchRegistry = NULL, batchResources = NULL, pepSettings = NULL,
  ignoreLock = FALSE, lifespan = NULL)

Arguments

cacheName	A character vector for a unique name for the cache. Be careful.
instruction	R expression (in braces) to be evaluated. The returned value of this code is what will be cached under the cacheName.
buildEnvir	An environment (or list) providing additional variables necessary for evaluating the code in instruction.
reload	Logical indicating whether to force re-loading the cache, even if it exists in the env.
recreate	Logical indicating whether to force reconstruction of the cache
noload	Logical indicating whether to create but not load the cache. noload is useful for: you want to create the caches, but not load (like a cache creation loop).
cacheDir	Character vector specifying the directory where caches are saved (and loaded from). Defaults to the variable set by setCacheDir().
cacheSubDir	Character vector specifying a subdirectory within the cacheDir variable. Defaults to NULL.
timer	Logical indicating whether to report how long it took to create the cache.
buildDir	Location of Build files (files with instructions for use If the instructions argument is not provided). Defaults to RBUILD.DIR global option.
assignToVariable	Character vector for a variable name to load the cache into. By default, simpleCache assigns the cache to a variable named cacheName; you can overrule that here.
loadEnvir	An environment. Into which environment would you like to load the variable? Defaults to parent.frame.
searchEnvir	a vector of environments to search for the already loaded cache.
nofail	By default, simpleCache throws an error if the instructions fail. Use this option to convert this error into a warning. No cache will be created, but simpleCache will not then hard-stop your processing. This is useful, for example, if you are creating a bunch of caches (for example using lapply) and it's ok if some of them do not complete.
batchRegistry	A batchtools registry object (built with makeRegistry). If provided, this cache will be created on the cluster using your batchtools configuration
batchResources	A list of variables to provide to batchtools for cluster resource managers. Used as the res argument to batchMap
pepSettings	Experimental untested feature.
ignoreLock	Internal parameter used for batch job submission; don't touch.
lifespan	Numeric specifying the maximum age of cache, in days, to allow before automatically triggering recreate=TRUE.

Details

You should pass a bracketed R code snippet like rnorm(500) as the instruction, and simpleCache will create the object. Alternatively, if the code to create the cache is large, you can put an R script called object.R in the RBUILD.DIR (the name of the file *must* match the name of the object it creates *exactly*). If you don't provide an instruction, the function sources RBUILD.DIR/object.R and caches the result as the object. This source file *must* create an object with the same name of the object. If you already have an object with the name of the object to load in your current environment, this function will not try to reload the object; instead, it returns the local object. In essence, it assumes that this is a static object, which you will not change. You can force it to load the cached version instead with "reload".

Because R uses lexical scope and not dynamic scope, you may need to pass some environment variables you use in your instruction code. You can use this using the parameter buildEnvir (just provide a list of named variables).

Examples

# choose location to store caches
cacheDir = tempdir()
cacheDir
#> [1] "/tmp/RtmpnwNyJo"
setCacheDir(cacheDir)

# build some caches
simpleCache("normSample", { rnorm(5e3, 0,1) }, recreate=TRUE, timer=TRUE)
#> ::Creating cache::	/tmp/RtmpnwNyJo/normSample.RData
#> <00h 00m 0.0s>
simpleCache("normSample", { rnorm(5e3, 0,1) })
#> ::Loading cache::	/tmp/RtmpnwNyJo/normSample.RData
simpleCache("normSample", { rnorm(5e3, 0,1) }, reload=TRUE)
#> ::Loading cache::	/tmp/RtmpnwNyJo/normSample.RData

# storing a cache after-the-fact
normSample2 = rnorm(10, 0, 1)
storeCache("normSample2")
#> ::Object does not exist::	normSample2
#> NULL

# what's available?
listCaches()
#> [1] "normSample.RData"

# load a cache
simpleCache("normSample")
#> ::Loading cache::	/tmp/RtmpnwNyJo/normSample.RData

# load multiples caches
loadCaches(c("normSample", "normSample2"), reload=TRUE)
#> ::Loading cache::	/tmp/RtmpnwNyJo/normSample.RData
#> ::Creating cache::	/tmp/RtmpnwNyJo/normSample2.RData
#> Error in doTryCatch(return(expr), name, parentenv, handler): ::Error:: If you do not provide an instruction argument, you must setglobal option RBUILD.DIR with setCacheBuildDir, or specify a buildDirparameter directly to simpleCache().