03 Using Cache with SpaDES

Eliot J. B. McIntire

May 15 2020

As part of a reproducible work flow, caching of various function calls are a critical component. Down the road, it is likely that an entire work flow from raw data to publication, decision support, report writing, presentation building etc., could be built and be reproducible anywhere, on demand. The reproducible::Cache function is built to work with any R function. However, it becomes very powerful in a SpaDES context because we can build large, powerful applications that are transparent and tied to the raw data that may be many conceptual steps upstream in the workflow. To do this, we have built several customizations within the SpaDES package. Important to this is dealing correctly with the simList, which is an object that has slot that is an environment. But more important are the various tools that can be used at higher levels, i.e., not just for “standard” functions.

1 Caching as part of SpaDES

Some of the details of the simList-specific features of this Cache function include:

In a SpaDES context, there are several levels of caching that can be used as part of a reproducible workflow. Each level can be used to a modeler’s advantage; and, all can be – and are often – used concurrently.

1.1 At the spades level

And entire call to spades can be cached. This will have the effect of eliminating any stochasticity in the model as the output will simply be the cached version of the simList. This is likely most useful in situations where reproducibility is more important than “new” stochasticity (e.g., building decision support systems, apps, final version of a manuscript).

library(magrittr)
library(raster)
library(reproducible)
library(SpaDES.core)

opts <- options("spades.moduleCodeChecks" = FALSE) # turns off syntactic checking of modules
mySim <- simInit(
  times = list(start = 0.0, end = 5.0),
  params = list(
    .globals = list(stackName = "landscape", burnStats = "testStats"),
    randomLandscapes = list(.plotInitialTime = NA),
    fireSpread = list(.plotInitialTime = NA)
  ),
  modules = list("randomLandscapes", "fireSpread"),
  paths = list(modulePath = system.file("sampleModules", package = "SpaDES.core")))
options(opts)

This functionality can be achieved within a spades call.

# compare caching ... run once to create cache
system.time({
  outSim <- spades(Copy(mySim), cache = TRUE, notOlderThan = Sys.time())
})
## 2020-05-15 10:03:02 INFO:: total elpsd: 0.001 secs | 0 checkpoint init 0
## 2020-05-15 10:03:02 INFO:: total elpsd: 0.0035 secs | 0 save init 0
## 2020-05-15 10:03:02 INFO:: total elpsd: 0.006 secs | 0 progress init 0
## 2020-05-15 10:03:02 INFO:: total elpsd: 0.0083 secs | 0 load init 0
## 2020-05-15 10:03:02 INFO:: total elpsd: 0.01 secs | 0 randomLandscapes init 1
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.75 secs | 0 fireSpread init 1
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.76 secs | 1 fireSpread burn 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.78 secs | 1 fireSpread stats 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.78 secs | 2 fireSpread burn 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.8 secs | 2 fireSpread stats 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.8 secs | 3 fireSpread burn 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.82 secs | 3 fireSpread stats 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.83 secs | 4 fireSpread burn 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.84 secs | 4 fireSpread stats 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.85 secs | 5 fireSpread burn 5
## 2020-05-15 10:03:03 INFO:: total elpsd: 0.86 secs | 5 fireSpread stats 5
## simList saved in
##  SpaDES.core:::.pkgEnv$.sim 
## It will be deleted at next spades() call.
##    user  system elapsed 
##   1.440   0.017   1.865

Note that if there were any visualizations (here we turned them off with .plotInitialTime = NA above) they will happen the first time through, but not the cached times.

# vastly faster 2nd time
system.time({
  outSimCached <- spades(Copy(mySim), cache = TRUE)
})
##   ...(Object to retrieve (45fa06ef340f7bdd.rds))
##      loaded cached result from previous spades call,
##    user  system elapsed 
##   0.542   0.008   0.534
all.equal(outSim, outSimCached) 
## [1] TRUE

1.2 Module-level caching

If the parameter .useCache in the module’s metadata is set to TRUE, then every event in the module will be cached. That means that every time that module is called from within a spades call, Cache will be called. Only the objects inside the simList that correspond to the inputObjects or the outputObjects from the module metadata will be assessed for caching. For general use, module-level caching would be mostly useful for modules that have no stochasticity, such as data-preparation modules, GIS modules etc.

In this example, we will use the cache on the randomLandscapes module. This means that each subsequent call to spades will result in identical outputs from the randomLandscapes module (only!). This would be useful when only one random landscape is needed simply for trying something out, or putting into production code (e.g., publication, decision support, etc.).

# Module-level
params(mySim)$randomLandscapes$.useCache <- TRUE
system.time({
  randomSim <- spades(Copy(mySim), .plotInitialTime = NA,
                      notOlderThan = Sys.time(), debug = TRUE)
})
## 2020-05-15 10:03:05 INFO::This is the current event, printed as it is happening:
## 2020-05-15 10:03:05 INFO::eventTime moduleName eventType eventPriority
## 2020-05-15 10:03:05 INFO::0         checkpoint init      0
## 2020-05-15 10:03:05 INFO::0         save       init      0
## 2020-05-15 10:03:05 INFO::0         progress   init      0
## 2020-05-15 10:03:05 INFO::0         load       init      0
## 2020-05-15 10:03:05 INFO::0         randomLandscapes init      1
## 2020-05-15 10:03:06 INFO::0         fireSpread       init      1
## 2020-05-15 10:03:06 INFO::1         fireSpread       burn      5
## 2020-05-15 10:03:06 INFO::1         fireSpread       stats     5
## 2020-05-15 10:03:06 INFO::2         fireSpread       burn      5
## 2020-05-15 10:03:06 INFO::2         fireSpread       stats     5
## 2020-05-15 10:03:06 INFO::3         fireSpread       burn      5
## 2020-05-15 10:03:06 INFO::3         fireSpread       stats     5
## 2020-05-15 10:03:06 INFO::4         fireSpread       burn      5
## 2020-05-15 10:03:06 INFO::4         fireSpread       stats     5
## 2020-05-15 10:03:06 INFO::5         fireSpread       burn      5
## 2020-05-15 10:03:06 INFO::5         fireSpread       stats     5
## simList saved in
##  SpaDES.core:::.pkgEnv$.sim 
## It will be deleted at next spades() call.
##    user  system elapsed 
##   1.387   0.051   1.774
# vastly faster the second time
system.time({
  randomSimCached <- spades(Copy(mySim), .plotInitialTime = NA, debug = TRUE)
})
## 2020-05-15 10:03:07 INFO::This is the current event, printed as it is happening:
## 2020-05-15 10:03:07 INFO::eventTime moduleName eventType eventPriority
## 2020-05-15 10:03:07 INFO::0         checkpoint init      0
## 2020-05-15 10:03:07 INFO::0         save       init      0
## 2020-05-15 10:03:07 INFO::0         progress   init      0
## 2020-05-15 10:03:07 INFO::0         load       init      0
## 2020-05-15 10:03:07 INFO::0         randomLandscapes init      1
## 2020-05-15 10:03:07 INFO::  ...(Object to retrieve (15f8be3b5d068e0d.rds))
## 2020-05-15 10:03:07 INFO::  Using cached copy of randomLandscapes module adding to memoised copy
## 2020-05-15 10:03:07 INFO::0         fireSpread       init      1
## 2020-05-15 10:03:07 INFO::1         fireSpread       burn      5
## 2020-05-15 10:03:07 INFO::1         fireSpread       stats     5
## 2020-05-15 10:03:07 INFO::2         fireSpread       burn      5
## 2020-05-15 10:03:07 INFO::2         fireSpread       stats     5
## 2020-05-15 10:03:07 INFO::3         fireSpread       burn      5
## 2020-05-15 10:03:07 INFO::3         fireSpread       stats     5
## 2020-05-15 10:03:07 INFO::4         fireSpread       burn      5
## 2020-05-15 10:03:07 INFO::4         fireSpread       stats     5
## 2020-05-15 10:03:08 INFO::5         fireSpread       burn      5
## 2020-05-15 10:03:08 INFO::5         fireSpread       stats     5
## simList saved in
##  SpaDES.core:::.pkgEnv$.sim 
## It will be deleted at next spades() call.
##    user  system elapsed 
##   0.918   0.008   0.877

Test that only layers produced in randomLandscapes are identical, not fireSpread.

layers <- list("DEM", "forestAge", "habitatQuality", "percentPine", "Fires")
same <- lapply(layers, function(l)
  identical(randomSim$landscape[[l]], randomSimCached$landscape[[l]]))
names(same) <- layers
print(same) # Fires is not same because all non-init events in fireSpread are not cached
## $DEM
## [1] TRUE
## 
## $forestAge
## [1] TRUE
## 
## $habitatQuality
## [1] TRUE
## 
## $percentPine
## [1] TRUE
## 
## $Fires
## [1] FALSE

1.3 Event-level caching

If the parameter .useCache in the module’s metadata is set to a character or character vector, then that or those event(s), identified by their name, will be cached. That means that every time the event is called from within a spades call, Cache will be called. Only the objects inside the simList that correspond to the inputObjects or the outputObjects as defined in the module metadata will be assessed for caching inputs or outputs, respectively. The fact that all and only the named inputObjects and outputObjects are cached and returned may be inefficient (i.e., it may cache more objects than are necessary) for individual events.

Similar to module-level caching, event-level caching would be mostly useful for events that have no stochasticity, such as data-preparation events, GIS events etc. Here, we don’t change the module-level caching for randomLandscapes, but we add to it a cache for only the “init” event for fireSpread.

params(mySim)$fireSpread$.useCache <- "init"
system.time({
  randomSim <- spades(Copy(mySim), .plotInitialTime = NA,
                      notOlderThan = Sys.time(), debug = TRUE)
})
## 2020-05-15 10:03:08 INFO::This is the current event, printed as it is happening:
## 2020-05-15 10:03:08 INFO::eventTime moduleName eventType eventPriority
## 2020-05-15 10:03:08 INFO::0         checkpoint init      0
## 2020-05-15 10:03:08 INFO::0         save       init      0
## 2020-05-15 10:03:08 INFO::0         progress   init      0
## 2020-05-15 10:03:08 INFO::0         load       init      0
## 2020-05-15 10:03:08 INFO::0         randomLandscapes init      1
## 2020-05-15 10:03:09 INFO::0         fireSpread       init      1
## 2020-05-15 10:03:09 INFO::1         fireSpread       burn      5
## 2020-05-15 10:03:09 INFO::1         fireSpread       stats     5
## 2020-05-15 10:03:09 INFO::2         fireSpread       burn      5
## 2020-05-15 10:03:09 INFO::2         fireSpread       stats     5
## 2020-05-15 10:03:09 INFO::3         fireSpread       burn      5
## 2020-05-15 10:03:09 INFO::3         fireSpread       stats     5
## 2020-05-15 10:03:09 INFO::4         fireSpread       burn      5
## 2020-05-15 10:03:10 INFO::4         fireSpread       stats     5
## 2020-05-15 10:03:10 INFO::5         fireSpread       burn      5
## 2020-05-15 10:03:10 INFO::5         fireSpread       stats     5
## simList saved in
##  SpaDES.core:::.pkgEnv$.sim 
## It will be deleted at next spades() call.
##    user  system elapsed 
##   1.374   0.035   1.777
# vastly faster the second time
system.time({
  randomSimCached <- spades(Copy(mySim), .plotInitialTime = NA, debug = TRUE)
})
## 2020-05-15 10:03:10 INFO::This is the current event, printed as it is happening:
## 2020-05-15 10:03:10 INFO::eventTime moduleName eventType eventPriority
## 2020-05-15 10:03:10 INFO::0         checkpoint init      0
## 2020-05-15 10:03:10 INFO::0         save       init      0
## 2020-05-15 10:03:10 INFO::0         progress   init      0
## 2020-05-15 10:03:10 INFO::0         load       init      0
## 2020-05-15 10:03:10 INFO::0         randomLandscapes init      1
## 2020-05-15 10:03:10 INFO::  ...(Object to retrieve (15f8be3b5d068e0d.rds))
## 2020-05-15 10:03:10 INFO::  Using cached copy of randomLandscapes module adding to memoised copy
## 2020-05-15 10:03:10 INFO::0         fireSpread       init      1
## 2020-05-15 10:03:10 INFO::  ...(Object to retrieve (5104885504493ea1.rds))
## 2020-05-15 10:03:10 INFO::  Using cached copy of init event in fireSpread module.
## 2020-05-15 10:03:10 INFO::1         fireSpread       burn      5
## 2020-05-15 10:03:10 INFO::1         fireSpread       stats     5
## 2020-05-15 10:03:10 INFO::2         fireSpread       burn      5
## 2020-05-15 10:03:10 INFO::2         fireSpread       stats     5
## 2020-05-15 10:03:10 INFO::3         fireSpread       burn      5
## 2020-05-15 10:03:10 INFO::3         fireSpread       stats     5
## 2020-05-15 10:03:10 INFO::4         fireSpread       burn      5
## 2020-05-15 10:03:10 INFO::4         fireSpread       stats     5
## 2020-05-15 10:03:10 INFO::5         fireSpread       burn      5
## 2020-05-15 10:03:10 INFO::5         fireSpread       stats     5
## simList saved in
##  SpaDES.core:::.pkgEnv$.sim 
## It will be deleted at next spades() call.
##    user  system elapsed 
##   0.362   0.000   0.305

1.4 Function-level caching

Any function can be cached using: Cache(FUN = functionName, ...).

This will be a slight change to a function call, such as: projectRaster(raster, crs = crs(newRaster)) to Cache(projectRaster, raster, crs = crs(newRaster)).

ras <- raster(extent(0, 1e3, 0, 1e3), res = 1)
system.time({
  map <- Cache(gaussMap, ras, cacheRepo = cachePath(mySim),
               notOlderThan = Sys.time())
})
##    user  system elapsed 
##   2.273   0.069   2.534
# vastly faster the second time
system.time({
  mapCached <- Cache(gaussMap, ras, cacheRepo = cachePath(mySim))
})
##   ...(Object to retrieve (904353f34a856ae2.rds) is large: 7.1 Mb)
##      loaded cached result from previous gaussMap call,
##    user  system elapsed 
##   0.125   0.008   0.114
all.equal(map, mapCached) 
## [1] TRUE

1.5 Working with the Cache manually

Since the cache is simply a DBI database table, all DBI functions will work as is. In addition, there are several helpers in the reproducible package, including showCache, keepCache and clearCache, and the more advanced createCache, loadFromCache, rmFromCache, and saveToCache that may be useful. Also, one can access cached items manually (rather than simply rerunning the same Cache function again).

cacheDB <- showCache(mySim)
## Cache size:
##   Total (including Rasters): 2.4 Mb
##   Selected objects (not including Rasters): 2.4 Mb
# examine only the functions that have been cached
cacheDB[tagKey == "function"]
##             cacheId   tagKey tagValue         createdDate
## 1: 45fa06ef340f7bdd function   spades 2020-05-15 10:03:03
## 2: 15f8be3b5d068e0d function   spades 2020-05-15 10:03:09
## 3: 15f8be3b5d068e0d function      FUN 2020-05-15 10:03:09
## 4: 5104885504493ea1 function   spades 2020-05-15 10:03:09
## 5: 5104885504493ea1 function      FUN 2020-05-15 10:03:09
## 6: 904353f34a856ae2 function gaussMap 2020-05-15 10:03:13
# get the RasterLayer that was produced with the gaussMap function:
map <- loadFromCache(cachePath(mySim), cacheId = cacheDB[tagValue == "gaussMap"]$cacheId)

clearPlot()
Plot(map)

2 Reproducible Workflow

In general, we feel that a liberal use of Cache will make a reusable and reproducible work flow. shiny apps can be made, taking advantage of Cache. Indeed, much of the difficulty in managing data sets and saving them for future use, can be accommodated by caching.

2.1 Nested Caching

simInit --> many .inputObjects calls

spades call --> many module calls --> many event calls --> many function calls

Lets say we start to introduce caching to this structure. We start from the “inner” most functions that we could imaging Caching would be useful. Lets say there are some GIS operations, like raster::projectRaster, which operates on an input shapefile. We can Cache the projectRaster call to make this much faster, since it will always be the same result for a given input raster.

If we look back at our structure above, we see that we still have LOTS of places that are not Cached. That means that the spades call will still spawn many module calls, and many event calls, just to get to the one Cache(projectRaster) call which is Cached. This function will likely be called many times. This is good, but Cache does take some time. So, even if Cache(projectRaster) takes only 0.02 seconds, calling it hundreds of times means maybe 4 seconds. If we are doing this for many functions, then this will be too slow for some purposes.

We can start putting Cache all up the sequence of calls. Unfortunately, the way we use Cache at each of these levels is a bit different, so we need a slightly different approach for each.

2.1.0.1 Cache the spades call

spades(cache = TRUE)

This will cache the spades call, causing stochasticity/randomness to be frozen.

2.1.0.2 Cache a whole module

Pass .useCache = TRUE as a parameter to the module, during the simInit

Some modules are inherently non-random, such as GIS modules, or parameter fitting statistical modules. We expect these to be identical results each time, so we can safely cache the entire module.

parameters = list(
  FireModule = list(.useCache = TRUE)
)
mySim <- simInit(..., params = parameters)
mySimOut <- spades(mySim)

The messaging should indicate the caching is happening on every event in that module.

Note: This option REQUIRES that the metadata in inputs and outputs be exactly correct, i.e., all inputObjects and outputObjects must be correctly identified and listed in the defineModule metadata

If the module is cached, and there are errors when it is run, it almost is guaranteed to be a problem with the inputObjects and outputObjects incorrectly specified.

2.1.0.3 Cache individual functions

Cache(<functionName>, <other arguments>)

This will allow fine scale control of individual function calls.

2.2 Data-to-decisions

Once nested Caching is used all the way up to the experiment (see SpaDES.experiment package) level and even further up (e.g., if there is a shiny module), then even very complex models can be put into a complete workflow.

The current vision for SpaDES is that it will allow this type of “data to decisions” complete workflow that allows for deep, robust models, across disciplines, with easily accessible front ends, that are quick and responsive to users, yet can handle data changes, module changes, etc.