Cache method that accommodates environments, S4 methods, Rasters

Cache method that accommodates environments, S4 methods, Rasters

Cache(FUN, ..., notOlderThan = NULL, objects = NULL, outputObjects = NULL,
  algo = "xxhash64", cacheRepo = NULL, compareRasterFileLength = 1e+06,
  userTags = c(), digestPathContent = FALSE, omitArgs = NULL,
  classOptions = list(), debugCache = character(), sideEffect = FALSE,
  makeCopy = FALSE, quick = FALSE)

# S4 method for ANY
Cache(FUN, ..., notOlderThan = NULL, objects = NULL,
  outputObjects = NULL, algo = "xxhash64", cacheRepo = NULL,
  compareRasterFileLength = 1e+06, userTags = c(),
  digestPathContent = FALSE, omitArgs = NULL, classOptions = list(),
  debugCache = character(), sideEffect = FALSE, makeCopy = FALSE,
  quick = FALSE)

Arguments

FUN	A function to be called.
...	Arguments of FUN function .
notOlderThan	load an artifact from the database only if it was created after notOlderThan.
objects	Character vector of objects to be digested. This is only applicable if there is a list, environment or simList with named objects within it. Only this/these objects will be considered for caching, i.e., only use a subset of the list, environment or simList objects.
outputObjects	Optional character vector indicating which objects to return. This is only relevant for simList objects
algo	The algorithms to be used; currently available choices are md5, which is also the default, sha1, crc32, sha256, sha512, xxhash32, xxhash64 and murmur32.
cacheRepo	A repository used for storing cached objects. This is optional if Cache is used inside a SpaDES module.
compareRasterFileLength	Numeric. Optional. When there are Rasters, that have file-backed storage, this is passed to the length arg in digest when determining if the Raster file is already in the database. Note: uses digest for file-backed Raster. Default 1e6. Passed to .prepareFileBackedRaster.
userTags	A character vector with Tags. These Tags will be added to the repository along with the artifact.
digestPathContent	Logical. Should arguments that are of class Path (see examples below) have their name digested (FALSE; default), or their file contents (TRUE).
omitArgs	Optional character string of arguments in the FUN to omit from the digest.
classOptions	Optional list. This will pass into .robustDigest for specific classes. Should be options that the .robustDigest knows what to do with.
debugCache	Character or Logical. Either "complete" or "quick" (uses partial matching, so "c" or "q" work). TRUE is equivalent to "complete". If "complete", then the returned object from the Cache function will have two attributes, debugCache1 and debugCache2, which are the entire list(...) and that same object, but after all .robustDigest calls, at the moment that it is digested using fastdigest, respectively. This attr(mySimOut, "debugCache2") can then be compared to a subsequent call and individual items within the object attr(mySimOut, "debugCache1") can be compared. If "quick", then it will return the same two objects directly, without evalutating the FUN(...).
sideEffect	Logical. Check if files to be downloaded are found locally in the cacheRepo prior to download and try to recover from a copy (makeCopy must have been set to TRUE the first time Cache was run). Default is FALSE. NOTE: this argument is experimental and may change in future releases.
makeCopy	Logical. If sideEffect = TRUE, and makeCopy = TRUE, a copy of the downloaded files will be made and stored in the cacheRepo to speed up subsequent file recovery in the case where the original copy of the downloaded files are corrupted or missing. Currently only works when set to TRUE during the first run of Cache. Default is FALSE. NOTE: this argument is experimental and may change in future releases.
quick	Logical. If sideEffect = TRUE, setting this to TRUE, will hash the file's metadata (i.e., filename and file size) instead of hashing the contents of the file(s). If set to FALSE (default), the contents of the file(s) are hashed. NOTE: this argument is experimental and may change in future releases.

Value

As with cache, returns the value of the function call or the cached version (i.e., the result from a previous call to this same cached function with identical arguments).

Details

Caching R objects using cache has four important limitations:

1. the archivist package detects different environments as different;

2. it also does not detect S4 methods correctly due to method inheritance;

3. it does not detect objects that have file-base storage of information (specifically RasterLayer-class objects);

4. the default hashing algorithm is relatively slow.

This version of the Cache function accommodates those four special, though quite common, cases by:

1. converting any environments into list equivalents;

2. identifying the dispatched S4 method (including those made through inheritance) before hashing so the correct method is being cached;

3. by hashing the linked file, rather than the Raster object. Currently, only file-backed Raster* objects are digested (e.g., not ff objects, or any other R object where the data are on disk instead of in RAM);

4. using fastdigest internally when the object is in RAM, which can be up to ten times faster than digest. Note that file-backed objects are still hashed using digest.

If Cache is called within a SpaDES module, then the cached entry will automatically get 3 extra userTags: eventTime, eventType, and moduleName. These can then be used in clearCache to selectively remove cached objects by eventTime, eventType or moduleName. Cache will add a tag to the artifact in the database called accessed, which will assign the time that it was accessed, either read or write. That way, artifacts can be shown (using showCache) or removed (using clearCache) selectively, based on their access dates, rather than only by their creation dates. See example in clearCache. Cache (uppercase C) is used here so that it is not confused with, and does not mask, the archivist::cache function.

Note

As indicated above, several objects require pre-treatment before caching will work as expected. The function .robustDigest accommodates this. It is an S4 generic, meaning that developers can produce their own methods for different classes of objects. Currently, there are methods for several types of classes. See .robustDigest.

See .robustDigest for other specifics for other classes.

Filepaths

If a function has a path argument, there is some ambiguity about what should be done. Possibilities include:

1. hash the string as is (this will be very system specific, meaning a Cache call will not work if copied between systems or directories);

2. hash the basename(path);

3. hash the contents of the file.

If paths are passed in as is (i.e,. character string), the result will not be predictable. Instead, one should use the wrapper function asPath(path), which sets the class of the string to a Path, and one should decide whether one wants to digest the content of the file (using digestPathContent = TRUE), or just the filename ((digestPathContent = FALSE)). See examples.

Stochasticity

In general, it is expected that caching will only be used when stochasticity is not relevant, or if a user has achieved sufficient stochasticity (e.g., via sufficient number of calls to experiment) such that no new explorations of stochastic outcomes are required. It will also be very useful in a reproducible workflow.

See also

cache, .robustDigest

Examples

library(raster)
#> Loading required package: sp
#> 
#> Attaching package: ‘raster’
#> The following object is masked from ‘package:reproducible’:
#> 
#>     init

tmpDir <- file.path(tempdir(), "reproducible_examples", "Cache")

## Example 1: basic cache use
ranNumsA <- Cache(rnorm, 4, cacheRepo = tmpDir, userTags = "objectName:a")
ranNumsB <- Cache(runif, 4, cacheRepo = tmpDir, userTags = "objectName:b")

showCache(tmpDir, userTags = c("objectName"))
#>                             artifact      tagKey
#>  1: 5d791310603a3579e3a1753f89e4da70      format
#>  2: 5d791310603a3579e3a1753f89e4da70        name
#>  3: 5d791310603a3579e3a1753f89e4da70       class
#>  4: 5d791310603a3579e3a1753f89e4da70        date
#>  5: 5d791310603a3579e3a1753f89e4da70  objectName
#>  6: 5d791310603a3579e3a1753f89e4da70    function
#>  7: 5d791310603a3579e3a1753f89e4da70 object.size
#>  8: 5d791310603a3579e3a1753f89e4da70    accessed
#>  9: 5d791310603a3579e3a1753f89e4da70     cacheId
#> 10: decbe2d8d61894d086362ed4536cf4df      format
#> 11: decbe2d8d61894d086362ed4536cf4df        name
#> 12: decbe2d8d61894d086362ed4536cf4df       class
#> 13: decbe2d8d61894d086362ed4536cf4df        date
#> 14: decbe2d8d61894d086362ed4536cf4df  objectName
#> 15: decbe2d8d61894d086362ed4536cf4df    function
#> 16: decbe2d8d61894d086362ed4536cf4df object.size
#> 17: decbe2d8d61894d086362ed4536cf4df    accessed
#> 18: decbe2d8d61894d086362ed4536cf4df     cacheId
#>                             tagValue         createdDate
#>  1:                              rda 2017-09-05 16:33:22
#>  2:                            Cache 2017-09-05 16:33:22
#>  3:                          numeric 2017-09-05 16:33:22
#>  4:              2017-09-05 16:33:22 2017-09-05 16:33:22
#>  5:                                a 2017-09-05 16:33:22
#>  6:                            rnorm 2017-09-05 16:33:22
#>  7:                              528 2017-09-05 16:33:23
#>  8:              2017-09-05 16:33:22 2017-09-05 16:33:23
#>  9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:23
#> 10:                              rda 2017-09-05 16:33:23
#> 11:                            Cache 2017-09-05 16:33:23
#> 12:                          numeric 2017-09-05 16:33:23
#> 13:              2017-09-05 16:33:23 2017-09-05 16:33:23
#> 14:                                b 2017-09-05 16:33:23
#> 15:                            runif 2017-09-05 16:33:23
#> 16:                              528 2017-09-05 16:33:23
#> 17:              2017-09-05 16:33:23 2017-09-05 16:33:23
#> 18: 9dd2494a488858266cd45d230f45a144 2017-09-05 16:33:23
showCache(tmpDir, userTags = c("^a$")) # regular expression ... "a" exactly
#>                            artifact      tagKey
#> 1: 5d791310603a3579e3a1753f89e4da70      format
#> 2: 5d791310603a3579e3a1753f89e4da70        name
#> 3: 5d791310603a3579e3a1753f89e4da70       class
#> 4: 5d791310603a3579e3a1753f89e4da70        date
#> 5: 5d791310603a3579e3a1753f89e4da70  objectName
#> 6: 5d791310603a3579e3a1753f89e4da70    function
#> 7: 5d791310603a3579e3a1753f89e4da70 object.size
#> 8: 5d791310603a3579e3a1753f89e4da70    accessed
#> 9: 5d791310603a3579e3a1753f89e4da70     cacheId
#>                            tagValue         createdDate
#> 1:                              rda 2017-09-05 16:33:22
#> 2:                            Cache 2017-09-05 16:33:22
#> 3:                          numeric 2017-09-05 16:33:22
#> 4:              2017-09-05 16:33:22 2017-09-05 16:33:22
#> 5:                                a 2017-09-05 16:33:22
#> 6:                            rnorm 2017-09-05 16:33:22
#> 7:                              528 2017-09-05 16:33:23
#> 8:              2017-09-05 16:33:22 2017-09-05 16:33:23
#> 9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:23
showCache(tmpDir, userTags = c("runif")) # show only cached objects made during runif call
#>                            artifact      tagKey
#> 1: decbe2d8d61894d086362ed4536cf4df      format
#> 2: decbe2d8d61894d086362ed4536cf4df        name
#> 3: decbe2d8d61894d086362ed4536cf4df       class
#> 4: decbe2d8d61894d086362ed4536cf4df        date
#> 5: decbe2d8d61894d086362ed4536cf4df  objectName
#> 6: decbe2d8d61894d086362ed4536cf4df    function
#> 7: decbe2d8d61894d086362ed4536cf4df object.size
#> 8: decbe2d8d61894d086362ed4536cf4df    accessed
#> 9: decbe2d8d61894d086362ed4536cf4df     cacheId
#>                            tagValue         createdDate
#> 1:                              rda 2017-09-05 16:33:23
#> 2:                            Cache 2017-09-05 16:33:23
#> 3:                          numeric 2017-09-05 16:33:23
#> 4:              2017-09-05 16:33:23 2017-09-05 16:33:23
#> 5:                                b 2017-09-05 16:33:23
#> 6:                            runif 2017-09-05 16:33:23
#> 7:                              528 2017-09-05 16:33:23
#> 8:              2017-09-05 16:33:23 2017-09-05 16:33:23
#> 9: 9dd2494a488858266cd45d230f45a144 2017-09-05 16:33:23

clearCache(tmpDir, userTags = c("runif")) # remove only cached objects made during runif call
showCache(tmpDir) # only those made during rnorm call
#>                            artifact      tagKey
#> 1: 5d791310603a3579e3a1753f89e4da70      format
#> 2: 5d791310603a3579e3a1753f89e4da70        name
#> 3: 5d791310603a3579e3a1753f89e4da70       class
#> 4: 5d791310603a3579e3a1753f89e4da70        date
#> 5: 5d791310603a3579e3a1753f89e4da70  objectName
#> 6: 5d791310603a3579e3a1753f89e4da70    function
#> 7: 5d791310603a3579e3a1753f89e4da70 object.size
#> 8: 5d791310603a3579e3a1753f89e4da70    accessed
#> 9: 5d791310603a3579e3a1753f89e4da70     cacheId
#>                            tagValue         createdDate
#> 1:                              rda 2017-09-05 16:33:22
#> 2:                            Cache 2017-09-05 16:33:22
#> 3:                          numeric 2017-09-05 16:33:22
#> 4:              2017-09-05 16:33:22 2017-09-05 16:33:22
#> 5:                                a 2017-09-05 16:33:22
#> 6:                            rnorm 2017-09-05 16:33:22
#> 7:                              528 2017-09-05 16:33:23
#> 8:              2017-09-05 16:33:22 2017-09-05 16:33:23
#> 9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:23

clearCache(tmpDir)

## Example 2: using the "accessed" tag
ranNumsA <- Cache(rnorm, 4, cacheRepo = tmpDir, userTags = "objectName:a")
ranNumsB <- Cache(runif, 4, cacheRepo = tmpDir, userTags = "objectName:b")

# access it again, but "later"
Sys.sleep(1)
ranNumsA <- Cache(rnorm, 4, cacheRepo = tmpDir, userTags = "objectName:a")
#> loading cached result from previous rnorm call.
wholeCache <- showCache(tmpDir)

# keep only items accessed "recently" (i.e., only objectName:a)
onlyRecentlyAccessed <- showCache(tmpDir, userTags = max(wholeCache[tagKey == "accessed"]$tagValue))

# inverse join with 2 data.tables ... using: a[!b]
# i.e., return all of wholeCache that was not recently accessed
toRemove <- unique(wholeCache[!onlyRecentlyAccessed], by = "artifact")$artifact
clearCache(tmpDir, toRemove) # remove ones not recently accessed
showCache(tmpDir) # still has more recently accessed
#>                             artifact      tagKey
#>  1: 1859dfdf3198d6377afbb546cdc9723c      format
#>  2: 1859dfdf3198d6377afbb546cdc9723c        name
#>  3: 1859dfdf3198d6377afbb546cdc9723c       class
#>  4: 1859dfdf3198d6377afbb546cdc9723c        date
#>  5: 1859dfdf3198d6377afbb546cdc9723c  objectName
#>  6: 1859dfdf3198d6377afbb546cdc9723c    function
#>  7: 1859dfdf3198d6377afbb546cdc9723c object.size
#>  8: 1859dfdf3198d6377afbb546cdc9723c    accessed
#>  9: 1859dfdf3198d6377afbb546cdc9723c     cacheId
#> 10: 1859dfdf3198d6377afbb546cdc9723c    accessed
#>                             tagValue         createdDate
#>  1:                              rda 2017-09-05 16:33:23
#>  2:                            Cache 2017-09-05 16:33:23
#>  3:                          numeric 2017-09-05 16:33:23
#>  4:              2017-09-05 16:33:23 2017-09-05 16:33:23
#>  5:                                a 2017-09-05 16:33:23
#>  6:                            rnorm 2017-09-05 16:33:23
#>  7:                              528 2017-09-05 16:33:23
#>  8:              2017-09-05 16:33:23 2017-09-05 16:33:23
#>  9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:23
#> 10:              2017-09-05 16:33:24 2017-09-05 16:33:24

clearCache(tmpDir)

## Example 3: using keepCache
ranNumsA <- Cache(rnorm, 4, cacheRepo = tmpDir, userTags = "objectName:a")
ranNumsB <- Cache(runif, 4, cacheRepo = tmpDir, userTags = "objectName:b")

# keep only those cached items from the last 24 hours
oneDay <- 60 * 60 * 24
keepCache(tmpDir, after = Sys.time() - oneDay)
#>                             artifact      tagKey
#>  1: 832ac945443ee5a6db5d0f4f6a7703f1      format
#>  2: 832ac945443ee5a6db5d0f4f6a7703f1        name
#>  3: 832ac945443ee5a6db5d0f4f6a7703f1       class
#>  4: 832ac945443ee5a6db5d0f4f6a7703f1        date
#>  5: 832ac945443ee5a6db5d0f4f6a7703f1  objectName
#>  6: 832ac945443ee5a6db5d0f4f6a7703f1    function
#>  7: 832ac945443ee5a6db5d0f4f6a7703f1 object.size
#>  8: 832ac945443ee5a6db5d0f4f6a7703f1    accessed
#>  9: 832ac945443ee5a6db5d0f4f6a7703f1     cacheId
#> 10: 8f71a97709b2d4630bfc1e9051803cc6      format
#> 11: 8f71a97709b2d4630bfc1e9051803cc6        name
#> 12: 8f71a97709b2d4630bfc1e9051803cc6       class
#> 13: 8f71a97709b2d4630bfc1e9051803cc6        date
#> 14: 8f71a97709b2d4630bfc1e9051803cc6  objectName
#> 15: 8f71a97709b2d4630bfc1e9051803cc6    function
#> 16: 8f71a97709b2d4630bfc1e9051803cc6 object.size
#> 17: 8f71a97709b2d4630bfc1e9051803cc6    accessed
#> 18: 8f71a97709b2d4630bfc1e9051803cc6     cacheId
#>                             tagValue         createdDate
#>  1:                              rda 2017-09-05 16:33:24
#>  2:                            Cache 2017-09-05 16:33:24
#>  3:                          numeric 2017-09-05 16:33:24
#>  4:              2017-09-05 16:33:24 2017-09-05 16:33:24
#>  5:                                b 2017-09-05 16:33:24
#>  6:                            runif 2017-09-05 16:33:24
#>  7:                              528 2017-09-05 16:33:24
#>  8:              2017-09-05 16:33:24 2017-09-05 16:33:24
#>  9: 9dd2494a488858266cd45d230f45a144 2017-09-05 16:33:24
#> 10:                              rda 2017-09-05 16:33:24
#> 11:                            Cache 2017-09-05 16:33:24
#> 12:                          numeric 2017-09-05 16:33:24
#> 13:              2017-09-05 16:33:24 2017-09-05 16:33:24
#> 14:                                a 2017-09-05 16:33:24
#> 15:                            rnorm 2017-09-05 16:33:24
#> 16:                              528 2017-09-05 16:33:24
#> 17:              2017-09-05 16:33:24 2017-09-05 16:33:24
#> 18: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:24

# Keep all Cache items created with an rnorm() call
keepCache(tmpDir, userTags = "rnorm")
#>                            artifact      tagKey
#> 1: 8f71a97709b2d4630bfc1e9051803cc6      format
#> 2: 8f71a97709b2d4630bfc1e9051803cc6        name
#> 3: 8f71a97709b2d4630bfc1e9051803cc6       class
#> 4: 8f71a97709b2d4630bfc1e9051803cc6        date
#> 5: 8f71a97709b2d4630bfc1e9051803cc6  objectName
#> 6: 8f71a97709b2d4630bfc1e9051803cc6    function
#> 7: 8f71a97709b2d4630bfc1e9051803cc6 object.size
#> 8: 8f71a97709b2d4630bfc1e9051803cc6    accessed
#> 9: 8f71a97709b2d4630bfc1e9051803cc6     cacheId
#>                            tagValue         createdDate
#> 1:                              rda 2017-09-05 16:33:24
#> 2:                            Cache 2017-09-05 16:33:24
#> 3:                          numeric 2017-09-05 16:33:24
#> 4:              2017-09-05 16:33:24 2017-09-05 16:33:24
#> 5:                                a 2017-09-05 16:33:24
#> 6:                            rnorm 2017-09-05 16:33:24
#> 7:                              528 2017-09-05 16:33:24
#> 8:              2017-09-05 16:33:24 2017-09-05 16:33:24
#> 9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:24

# Remove all Cache items that happened within a rnorm() call
clearCache(tmpDir, userTags = "rnorm")

showCache(tmpDir) ## empty
#> Empty data.table (0 rows) of 3 cols: md5hash,name,createdDate

## Example 4: searching for multiple objects in the cache

# default userTags is "and" matching; for "or" matching use |
ranNumsA <- Cache(runif, 4, cacheRepo = tmpDir, userTags = "objectName:a")
ranNumsB <- Cache(rnorm, 4, cacheRepo = tmpDir, userTags = "objectName:b")

# show all objects (runif and rnorm in this case)
showCache(tmpDir)
#>                             artifact      tagKey
#>  1: 272069fa0f28e15171fc3970210c7526      format
#>  2: 272069fa0f28e15171fc3970210c7526        name
#>  3: 272069fa0f28e15171fc3970210c7526       class
#>  4: 272069fa0f28e15171fc3970210c7526        date
#>  5: 272069fa0f28e15171fc3970210c7526  objectName
#>  6: 272069fa0f28e15171fc3970210c7526    function
#>  7: 272069fa0f28e15171fc3970210c7526 object.size
#>  8: 272069fa0f28e15171fc3970210c7526    accessed
#>  9: 272069fa0f28e15171fc3970210c7526     cacheId
#> 10: f0832b8cd870cc65eea28f97be3c4f15      format
#> 11: f0832b8cd870cc65eea28f97be3c4f15        name
#> 12: f0832b8cd870cc65eea28f97be3c4f15       class
#> 13: f0832b8cd870cc65eea28f97be3c4f15        date
#> 14: f0832b8cd870cc65eea28f97be3c4f15  objectName
#> 15: f0832b8cd870cc65eea28f97be3c4f15    function
#> 16: f0832b8cd870cc65eea28f97be3c4f15 object.size
#> 17: f0832b8cd870cc65eea28f97be3c4f15    accessed
#> 18: f0832b8cd870cc65eea28f97be3c4f15     cacheId
#>                             tagValue         createdDate
#>  1:                              rda 2017-09-05 16:33:25
#>  2:                            Cache 2017-09-05 16:33:25
#>  3:                          numeric 2017-09-05 16:33:25
#>  4:              2017-09-05 16:33:25 2017-09-05 16:33:25
#>  5:                                b 2017-09-05 16:33:25
#>  6:                            rnorm 2017-09-05 16:33:25
#>  7:                              528 2017-09-05 16:33:25
#>  8:              2017-09-05 16:33:25 2017-09-05 16:33:25
#>  9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:25
#> 10:                              rda 2017-09-05 16:33:25
#> 11:                            Cache 2017-09-05 16:33:25
#> 12:                          numeric 2017-09-05 16:33:25
#> 13:              2017-09-05 16:33:25 2017-09-05 16:33:25
#> 14:                                a 2017-09-05 16:33:25
#> 15:                            runif 2017-09-05 16:33:25
#> 16:                              528 2017-09-05 16:33:25
#> 17:              2017-09-05 16:33:24 2017-09-05 16:33:25
#> 18: 9dd2494a488858266cd45d230f45a144 2017-09-05 16:33:25

# show objects that are both runif and rnorm
# (i.e., none in this case, because objecs are either or, not both)
showCache(tmpDir, userTags = c("runif", "rnorm")) ## empty
#> Empty data.table (0 rows) of 4 cols: artifact,tagKey,tagValue,createdDate

# show objects that are either runif or rnorm ("or" search)
showCache(tmpDir, userTags = "runif|rnorm")
#>                             artifact      tagKey
#>  1: 272069fa0f28e15171fc3970210c7526      format
#>  2: 272069fa0f28e15171fc3970210c7526        name
#>  3: 272069fa0f28e15171fc3970210c7526       class
#>  4: 272069fa0f28e15171fc3970210c7526        date
#>  5: 272069fa0f28e15171fc3970210c7526  objectName
#>  6: 272069fa0f28e15171fc3970210c7526    function
#>  7: 272069fa0f28e15171fc3970210c7526 object.size
#>  8: 272069fa0f28e15171fc3970210c7526    accessed
#>  9: 272069fa0f28e15171fc3970210c7526     cacheId
#> 10: f0832b8cd870cc65eea28f97be3c4f15      format
#> 11: f0832b8cd870cc65eea28f97be3c4f15        name
#> 12: f0832b8cd870cc65eea28f97be3c4f15       class
#> 13: f0832b8cd870cc65eea28f97be3c4f15        date
#> 14: f0832b8cd870cc65eea28f97be3c4f15  objectName
#> 15: f0832b8cd870cc65eea28f97be3c4f15    function
#> 16: f0832b8cd870cc65eea28f97be3c4f15 object.size
#> 17: f0832b8cd870cc65eea28f97be3c4f15    accessed
#> 18: f0832b8cd870cc65eea28f97be3c4f15     cacheId
#>                             tagValue         createdDate
#>  1:                              rda 2017-09-05 16:33:25
#>  2:                            Cache 2017-09-05 16:33:25
#>  3:                          numeric 2017-09-05 16:33:25
#>  4:              2017-09-05 16:33:25 2017-09-05 16:33:25
#>  5:                                b 2017-09-05 16:33:25
#>  6:                            rnorm 2017-09-05 16:33:25
#>  7:                              528 2017-09-05 16:33:25
#>  8:              2017-09-05 16:33:25 2017-09-05 16:33:25
#>  9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:25
#> 10:                              rda 2017-09-05 16:33:25
#> 11:                            Cache 2017-09-05 16:33:25
#> 12:                          numeric 2017-09-05 16:33:25
#> 13:              2017-09-05 16:33:25 2017-09-05 16:33:25
#> 14:                                a 2017-09-05 16:33:25
#> 15:                            runif 2017-09-05 16:33:25
#> 16:                              528 2017-09-05 16:33:25
#> 17:              2017-09-05 16:33:24 2017-09-05 16:33:25
#> 18: 9dd2494a488858266cd45d230f45a144 2017-09-05 16:33:25

# keep only objects that are either runif or rnorm ("or" search)
keepCache(tmpDir, userTags = "runif|rnorm")
#>                             artifact      tagKey
#>  1: 272069fa0f28e15171fc3970210c7526      format
#>  2: 272069fa0f28e15171fc3970210c7526        name
#>  3: 272069fa0f28e15171fc3970210c7526       class
#>  4: 272069fa0f28e15171fc3970210c7526        date
#>  5: 272069fa0f28e15171fc3970210c7526  objectName
#>  6: 272069fa0f28e15171fc3970210c7526    function
#>  7: 272069fa0f28e15171fc3970210c7526 object.size
#>  8: 272069fa0f28e15171fc3970210c7526    accessed
#>  9: 272069fa0f28e15171fc3970210c7526     cacheId
#> 10: f0832b8cd870cc65eea28f97be3c4f15      format
#> 11: f0832b8cd870cc65eea28f97be3c4f15        name
#> 12: f0832b8cd870cc65eea28f97be3c4f15       class
#> 13: f0832b8cd870cc65eea28f97be3c4f15        date
#> 14: f0832b8cd870cc65eea28f97be3c4f15  objectName
#> 15: f0832b8cd870cc65eea28f97be3c4f15    function
#> 16: f0832b8cd870cc65eea28f97be3c4f15 object.size
#> 17: f0832b8cd870cc65eea28f97be3c4f15    accessed
#> 18: f0832b8cd870cc65eea28f97be3c4f15     cacheId
#>                             tagValue         createdDate
#>  1:                              rda 2017-09-05 16:33:25
#>  2:                            Cache 2017-09-05 16:33:25
#>  3:                          numeric 2017-09-05 16:33:25
#>  4:              2017-09-05 16:33:25 2017-09-05 16:33:25
#>  5:                                b 2017-09-05 16:33:25
#>  6:                            rnorm 2017-09-05 16:33:25
#>  7:                              528 2017-09-05 16:33:25
#>  8:              2017-09-05 16:33:25 2017-09-05 16:33:25
#>  9: 6c02ed3587ff36e0f232dc296099540b 2017-09-05 16:33:25
#> 10:                              rda 2017-09-05 16:33:25
#> 11:                            Cache 2017-09-05 16:33:25
#> 12:                          numeric 2017-09-05 16:33:25
#> 13:              2017-09-05 16:33:25 2017-09-05 16:33:25
#> 14:                                a 2017-09-05 16:33:25
#> 15:                            runif 2017-09-05 16:33:25
#> 16:                              528 2017-09-05 16:33:25
#> 17:              2017-09-05 16:33:24 2017-09-05 16:33:25
#> 18: 9dd2494a488858266cd45d230f45a144 2017-09-05 16:33:25

clearCache(tmpDir)

## Example 5: using caching to speed up rerunning expensive computations
ras <- raster(extent(0, 100, 0, 100), res = 1,
              vals = sample(1:5, replace = TRUE, size = 1e4),
              crs = "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +ellps=WGS84")

# A slow operation, like GIS operation
notCached <- suppressWarnings(
  # project raster generates warnings when run non-interactively
  projectRaster(ras, crs = crs(ras), res = 5, cacheRepo = tmpDir)
)

cached <- suppressWarnings(
  # project raster generates warnings when run non-interactively
  Cache(projectRaster, ras, crs = crs(ras), res = 5, cacheRepo = tmpDir)
)

# second time is much faster
reRun <- suppressWarnings(
  # project raster generates warnings when run non-interactively
  Cache(projectRaster, ras, crs = crs(ras), res = 5, cacheRepo = tmpDir)
)
#> loading cached result from previous projectRaster call.

# recovered cached version is same as non-cached version
all.equal(notCached, reRun) ## TRUE
#> [1] TRUE

## Example 6: working with file paths

# if passing a character string, it will take 2 complete passes to before
#  a cached copy is used when it is a save event (read or load is different)
obj <- 1:10
fname <- tempfile(fileext = ".RData")
Cache(saveRDS, obj, file = fname, cacheRepo = tmpDir)
#> NULL
Cache(saveRDS, obj, file = fname, cacheRepo = tmpDir)
#> NULL
Cache(saveRDS, obj, file = fname, cacheRepo = tmpDir) # cached copy is loaded
#> loading cached result from previous saveRDS call.
#> [1] "NULL"
#> attr(,"tags")
#> [1] "cacheId:46db9ac49c0d1d44463ac3c5dfe3119a"
#> attr(,"call")
#> [1] ""

# however, using asPath(), cached version retrieved after being run once
fname1 <- tempfile(fileext = ".RData")
Cache(saveRDS, obj, file = asPath(fname1), cacheRepo = tmpDir)
#> NULL
Cache(saveRDS, obj, file = asPath(fname1), cacheRepo = tmpDir) # cached copy is loaded
#> loading cached result from previous saveRDS call.
#> [1] "NULL"
#> attr(,"tags")
#> [1] "cacheId:e41f2fe323f8a5fa2ca2002f099a7976"
#> attr(,"call")
#> [1] ""

clearCache(tmpDir)

## cleanup
unlink(c("filename.rda", "filename1.rda"))
unlink(dirname(tmpDir), recursive = TRUE)