SpaDES.core (version 0.2.4)

spades: Run a spatial discrete event simulation

Description

Here, we implement a simulation in a more modular fashion so it's easier to add submodules to the simulation. We use S4 classes and methods, and use `data.table` instead of `data.frame` to implement the event queue (because it is much faster).

Usage

spades(sim, debug = getOption("spades.debug"), progress = NA, cache,
  .plotInitialTime = NULL, .saveInitialTime = NULL,
  notOlderThan = NULL, ...)
# S4 method for simList,ANY,ANY,missing
spades(sim,
  debug = getOption("spades.debug"), progress = NA, cache,
  .plotInitialTime = NULL, .saveInitialTime = NULL,
  notOlderThan = NULL, ...)
# S4 method for ANY,ANY,ANY,logical
spades(sim,
  debug = getOption("spades.debug"), progress = NA, cache,
  .plotInitialTime = NULL, .saveInitialTime = NULL,
  notOlderThan = NULL, ...)

Arguments

sim

A simList simulation object, generally produced by simInit.

debug

Optional logical flag or character vector indicating what to print to console at each event. See details. Default is to use the value in getOption("spades.debug").

progress

Logical (TRUE or FALSE show a graphical progress bar), character ("graphical", "text") or numeric indicating the number of update intervals to show in a graphical progress bar.

cache

Logical. If TRUE, then the spades call will be cached. This means that if the call is made again with the same simList, then `spades`` will return the return value from the previous run of that exact same simList. Default FALSE. See Details. See also the vignette on caching for examples.

.plotInitialTime

Numeric. Temporarily override the .plotInitialTime parameter for all modules. See Details.

.saveInitialTime

Numeric. Temporarily override the .plotInitialTime parameter for all modules. See Details.

notOlderThan

Date or time. Passed to reproducible::Cache to update the cache. Default is NULL, meaning don't update the cache. If Sys.time() is provided, then it will force a recache, i.e., remove old value and replace with new value. Ignored if cache is FALSE.

...

Any. Can be used to make a unique cache identity, such as "replicate = 1". This will be included in the Cache call, so will be unique and thus spades will not use a cached copy as long as anything passed in ... is unique, i.e., not cached previously.

Value

Invisibly returns the modified simList object.

<code>debug</code>

debug can be a logical, character vector or a numeric scalar (currently 1 or 2). If debug is specified and is not FALSE, 2 things could happen: 1) there can be messages sent to console, such as events as they pass by, and 2) if options("spades.browserOnError" = TRUE) (experimental still) if there is an error, it will attempt to open a browser in the event where the error occurred. You can edit, and then press c to continue or Q to quit, plus all other normal interactive browser tools. c will trigger a reparse and events will continue as scheduled, starting with the one just edited. There may be some unexpected consequences if the simList objects had already been changed before the error occurred.

If not specified in the function call, the package option spades.debug is used. The following options for debug are available:

TRUE	the event immediately following will be printed as it runs (equivalent to current(sim)).
function name (as character string)	If a function, then it will be run on the simList, e.g., "time" will run time(sim) at each event.
moduleName (as character string)	All calls to that module will be entered interactively
eventName (as character string)	All calls that have that event name (in any module) will be entered interactively
c(<moduleName>, <eventName>)	Only the event in that specified module will be entered into.
Any other R expression expressed as a character string	Will be evaluated with access to the simList as 'sim'. If this is more than one character string, then all will be printed to the screen in their sequence.
A numeric scalar, currently 1 or 2 (maybe others)	This will print out alternative forms of event information that users may find useful
information that users may find useful	TRUE

Details

The is the workhorse function in the SpaDES package. It runs simulations by implementing the rules outlined in the simList.

This function gives simple access to two sets of module parameters: .plotInitialTime and with .plotInitialTime. The primary use of these arguments is to temporarily turn off plotting and saving. "Temporary" means that the simList is not changed, so it can be used again with the simList values reinstated. To turn off plotting and saving, use .plotInitialTime = NA or .saveInitialTime = NA. NOTE: if a module did not use .plotInitialTime or .saveInitialTime, then these arguments will not do anything.

If cache is TRUE, this allows for a seamless way to "save" results of a simulation. The user does not have to intentionally do any saving manually. Instead, upon a call to spades in which the simList is identical, the function will simply return the result that would have come if it had been rerun. Use this with caution, as it will return exactly the result from a previous run, even if there is stochasticity internally. Caching is only based on the input simList. See also experiment for the same mechanism, but it can be used with replication. See also the vignette on caching for examples.

References

Matloff, N. (2011). The Art of R Programming (ch. 7.8.3). San Francisco, CA: No Starch Press, Inc.. Retrieved from https://www.nostarch.com/artofr.htm

See Also

SpaDES.core-package, experiment for using replication with spades, simInit, and the caching vignette (very important for reproducibility): https://CRAN.R-project.org/package=SpaDES/vignettes/iii-cache.html which uses Cache.

Examples

# NOT RUN {
mySim <- simInit(
 times = list(start = 0.0, end = 2.0, timeunit = "year"),
 params = list(
   .globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
 ),
 modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
 paths = list(modulePath = system.file("sampleModules", package = "SpaDES.core"))
)
spades(mySim)

# set default debug printing for the current session
# setOption(spades.debug = TRUE)

# Different debug options (overrides the package option 'spades.debug')
spades(mySim, debug = TRUE) # Fastest
spades(mySim, debug = "simList")
spades(mySim, debug = "print(table(sim$landscape$Fires[]))")

# Can turn off plotting, and inspect the output simList instead
out <- spades(mySim, .plotInitialTime = NA) # much faster
completed(out) # shows completed events

# use cache -- simInit should generally be rerun each time a spades call is made
#   to guarantee that it is identical. Here, run spades call twice, first
#   time to establish cache, second time to return cached result
for (i in 1:2) {
 mySim <- simInit(
   times = list(start = 0.0, end = 2.0, timeunit = "year"),
   params = list(
     .globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
   ),
   modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
   paths = list(modulePath = system.file("sampleModules", package = "SpaDES.core"))
 )
 print(system.time(out <- spades(mySim, cache = TRUE)))
}
# }
# NOT RUN {
# }