SpaDES
packageThis package allows implementation a variety of simulation-type models, with a focus on spatially explicit models. The core simulation components are built upon a discrete event simulation framework that facilitates modularity, and easily enables the user to include additional functionality by running user-built simulation modules. Included are numerous tools to visualize various spatial data formats, as well as non-spatial data.
Bug reports: https://github.com/PredictiveEcology/SpaDES/issues
Module repository: https://github.com/PredictiveEcology/SpaDES-modules
A collection of top-level functions for doing spatial discrete event simulation.
There are two workhorse functions that initialize and run a simulation, and third function for doing multiple spades runs:
simInit |
Initialize a new simulation |
spades |
Run a discrete event simulation |
experiment |
Run multiple spades calls |
Within a module, important simulation functions include:
scheduleEvent |
Schedule a simulation event |
removeEvent |
Remove an event from the simulation queue (not yet implemented) |
##########################################################################
Collections of commonly used functions to retrieve or set slots (and their elements)
of a simList
object are summarized further below.
globals |
List of global simulation parameters. |
params |
Nested list of all simulation parameter. |
P |
Namespaced version of params
(i.e., do not have to specify module name). |
inputs |
List of loaded objects used in simulation. (advanced) |
outputs |
List of objects to save during simulation. (advanced) |
ls , objects |
Names of objects referenced by the simulation environment. |
ls.str |
List the structure of the simList objects. |
objs |
List of objects referenced by the simulation environment. |
Accessor functions for the paths
slot and its elements.
cachePath |
Global simulation cache path. |
modulePath |
Global simulation module path. |
inputPath |
Global simulation input path. |
outputPath |
Global simulation output path. |
paths |
Global simulation paths (cache, modules, inputs, outputs). |
cachePath |
Global simulation cache path. |
Accessor functions for the simtimes
slot and its elements.
time |
Current simulation time, in units of longest module. |
start |
Simulation start time, in units of longest module. |
end |
Simulation end time, in units of longest module. |
times |
List of all simulation times (current, start, end), in units of longest module.. |
Accessor functions for the events
and completed
slots.
By default, the event lists are shown when the simList
object is printed,
thus most users will not require direct use of these methods.
events |
Scheduled simulation events (the event queue). (advanced) |
current |
Currently executing event. (advanced) |
completed |
Completed simulation events. (advanced) |
Accessor functions for the depends
, modules
,
and .loadOrder
slots.
These are included for advanced users.
depends |
List of simulation module dependencies. (advanced) |
modules |
List of simulation modules to be loaded. (advanced) |
The simList
has a slot called .envir
which is an environment.
All objects in the simList are actually in this environment, i.e., the simList is
not entirely just a list. In R, environments use pass-by-reference semantics, which means that
copying an simList object using normal R assignment operation, e.g., sim2 <- sim1,
will not copy the objects contained within the .envir slot. The two objects sim1 and
sim2 will shared identical objects within that slot. Sometimes, this not desired, and
a true copy is required.
envir |
Access the environment of the simList directly (advanced) |
copy |
Deep copy of a simList. (advanced) |
Accessor method | Module | Description |
checkpointFile |
.checkpoint |
Name of the checkpoint file. (advanced) |
checkpointInterval |
.checkpoint |
The simulation checkpoint interval. (advanced) |
progressType |
.progress |
Type of graphical progress bar used. (advanced) |
progressInterval |
.progress |
Interval for the progress bar. (advanced) |
##########################################################################
Modules are the basic unit of SpaDES
.
These are generally created and stored locally, or are downloaded from remote repositories,
including our
SpaDES-modules repository on GitHub.
checksums |
Verify (and optionally write) checksums for a module's data files. |
downloadModule |
Open all modules nested within a base directory |
getModuleVersion |
Get the latest module version # from module repository |
newModule |
Create new module from template |
newModuleDocumentation |
Create empty documentation for a new module |
openModules |
Open all modules nested within a base directory |
moduleMetadata |
Shows the module metadata |
zipModule |
Zip a module and its associated files |
Each module requires several items to be defined.
These comprise the metadata for that module (including default parameter specifications,
inputs and outputs), and are currently written at the top of the module's .R
file.
defineModule |
Define the module metadata |
defineParameter |
Specify a parameter's name, value and set a default |
expectsInput |
Specify an input object's name, class, description, sourceURL and other specifications |
createsOutput |
Specify an output object's name, class, description and other specifications |
Once a set of modules have been chosen, the dependency information is automatically calculated once simInit is run. There are several functions to assist with dependency information:
depsEdgeList |
Build edge list for module dependency graph |
depsGraph |
Build a module dependency graph using igraph |
simList |
The 'simList' class |
Caching can be done in a variety of ways, most of which are up to the module developer. However, the one most common usage would be to cache a simulation run. This might be useful if a simulation is very long, has been run once, and the goal is just to retrieve final results. This would be an alternative to manually saving the outputs.
See example in spades
, achieved by using cache = TRUE
argument.
cache |
Caches a spades call, but often used as arg in spades |
showCache |
Shows information about the objects in the cache |
clearCache |
Removes objects from the cache |
clearStubArtifacts |
Removes some errors in cached files |
A module developer can build caching into their module by creating cached versions of their functions.
------------------------------------------------------------------------------------------
A collection of functions that help with making modules, in addition to all the other R packages and code.
Spatial contagion is a key phenomenon for spatially explicit simulation models. Contagion can
be modelled using discrete approaches or continuous approaches. Several SpaDES
functions assist
with these:
spread |
Contagious cellular automata |
rings |
Identify rings around focal cells (e.g., buffers and donuts) |
adj |
An optimized (i.e., faster) version of adjacent |
cir |
Identify pixels in a circle around a SpatialPoints* object |
distanceFromEachPoint |
Fast calculation of distance surfaces |
Agents have several methods and functions specific to them:
crw |
Simple correlated random walk function |
heading |
Determines the heading between SpatialPoints* |
makeLines |
Makes SpatialLines object for, e.g., drawing arrows |
move |
A meta function that can currently only take "crw" |
specificNumPerPatch |
Initiate a specific number of agents per patch |
In addition to the vast amount of GIS operations available in R (mostly from
contributed packages such as sp
, raster
, maps
, maptools
and many others), we provide the following GIS-related functions:
equalExtent |
Assess whether a list of extents are all equal |
These functions convert between reduced and mapped representations of the same data. This allows compact representation of, e.g., rasters that have many individual pixels that share identical information.
rasterizeReduced |
Convert reduced representation to full raster |
We likely will not want the default colours for every map.
Here are several helper functions to add to, set and get colors of Raster*
objects:
setColors |
Set colours for plotting Raster* objects |
getColors |
Get colours in a Raster* objects |
divergentColors |
Create a color palette with diverging colors around a middle |
It is often useful to build dummy maps with which to build simulation models before all data are available. These dummy maps can later be replaced with actual data maps.
gaussMap |
Creates a random map using gaussian random fields |
randomPolygons |
Creates a random polygon with specified number of classes |
SpaDES
modules will often require the existence of objects in the simList
.
These are helpers for assessing this:
checkObject |
Check for a existence of an object within a simList |
checkPath |
Checks the specified filepath for formatting consistencies |
These functions are essentially skeletons and are not fully implemented. They are intended to make translations from SELES. You must know how to use SELES for these to be useful:
agentLocation |
Agent location |
initiateAgents |
Initiate agents into a SpatialPointsDataFrame |
numAgents |
Number of agents |
probInit |
Probability of intiating an agent or event |
transitions |
Transition probability |
Functions that may be useful within a SpaDES
context
inRange |
Test whether a number lies within range [a,b] |
layerNames |
Get layer names for numerous object classes |
loadPackages |
Simple wrapper for loading packages |
numLayers |
Return number of layers |
paddedFloatToChar |
Wrapper for padding (e.g., zeros) floating numbers to character |
updateList |
Update values in a named list |
------------------------------------------------------------------------------------------
There are several user-accessible plotting functions that are optimized for modularity and speed of plotting:
Commonly used:
Plot |
The workhorse plotting function |
Simulation diagrams:
eventDiagram |
Gantt chart representing the events in a completed simulation. |
moduleDiagram |
Network diagram of simplified module (object) dependencies. |
objectDiagram |
Sequence diagram of detailed object dependencies. |
Other useful plotting functions:
clearPlot |
Helpful for resolving many errors |
clickValues |
Extract values from a raster object at the mouse click location(s) |
clickExtent |
Zoom into a raster or polygon map that was plotted with Plot |
clickCoordinates |
Get the coordinates, in map units, under mouse click |
dev |
Specify which device to plot on, making a non-RStudio one as default |
newPlot |
Open a new default plotting device |
rePlot |
Replots all elements of device for refreshing or moving plot |
------------------------------------------------------------------------------------------
In addition to R's file operations, we have added several here to aid in bulk loading and saving of files for simulation purposes:
getFileName |
Get the name of current file |
loadFiles |
Load simulation objects according to a filelist |
rasterToMemory |
Read a raster from file to RAM |
saveFiles |
Save simulation objects according to outputs and params |
------------------------------------------------------------------------------------------
Five maps and three modules are included within the SpaDES
package
Several dummy data sets are included for testing of functionality
spadesMaps |
Help showing included maps |
Several dummy modules are included for testing of functionality. These can be
found with file.path(find.package("SpaDES"), "sampleModules")
randomLandscapes |
Imports, updates, and plots several raster map layers |
caribouMovement |
A simple agent-based (a.k.a., individual-based) model |
fireSpread |
A simple model of a spatial spread process |
SpaDES
uses the following options
to configure behaviour:
spades.cachePath
: The default local directory in which to
cache simulation outputs.
Default is a temporary directory (typically /tmp/SpaDES/cache
).
spades.inputPath
: The default local directory in which to
look for simulation inputs.
Default is a temporary directory (typically /tmp/SpaDES/inputs
).
spades.lowMemory
: If true, some functions will use more memory
efficient (but slower) algorithms. Default FALSE
.
spades.modulePath
: The default local directory where modules
and data will be downloaded and stored.
Default is a temporary directory (typically /tmp/SpaDES/modules
).
spades.moduleRepo
: The default GitHub repository to use when
downloading modules. Default "PredictiveEcology/SpaDES-modules"
.
spades.nCompleted
: The maximum number of completed events to
retain in the completed
event queue. Default 1000L
.
spades.outputPath
: The default local directory in which to
save simulation outputs.
Default is a temporary directory (typically /tmp/SpaDES/outputs
).
spades.tolerance
: The default tolerance value used for floating
point number comparisons. Default .Machine$double.eps^0.5
.