SpaDES logo

This 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. Much work has been done to speed up the core of the DES, with current benchmarking as low as 700 microseconds overhead for each event (including queuing, sorting, spawning event etc.).

Bug reports: https://github.com/PredictiveEcology/SpaDES.core/issues

Module repository: https://github.com/PredictiveEcology/SpaDES-modules

Wiki: https://github.com/PredictiveEcology/SpaDES/wiki

------------------------------------------------------------------------------------------

1 Spatial discrete event simulation (<code>SpaDES</code>)

A collection of top-level functions for doing spatial discrete event simulation.

1.1 Simulations

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

1.2 Events

Within a module, important simulation functions include:
scheduleEvent Schedule a simulation event
removeEvent Remove an event from the simulation queue (not yet implemented)

2 The <code>simList</code> object class

The principle exported object class is the simList. All SpaDES simulations operate on this object class.

simList The 'simList' class

------------------------------------------------------------------------------------------

3 <code>simList</code> methods

Collections of commonly used functions to retrieve or set slots (and their elements) of a simList object are summarized further below.

3.1 Simulation parameters

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).

3.2 loading from disk, saving to disk

inputs List of loaded objects used in simulation. (advanced)
outputs List of objects to save during simulation. (advanced)

3.3 objects in the simList

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.

3.4 Simulation paths

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.

3.5 Simulation times

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..

3.6 Simulation event queues

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)

3.7 Modules, dependencies, packages

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)
packages Vector of required R libraries of all modules. (advanced)

3.8 simList environment

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 a list. In R, environments use pass-by-reference semantics, which means that copying a 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 share 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)

3.9 Checkpointing

Accessor method Module Description
checkpointFile .checkpoint Name of the checkpoint file. (advanced)
checkpointInterval .checkpoint The simulation checkpoint interval. (advanced)

3.10 Progress Bar

progressType .progress Type of graphical progress bar used. (advanced)
progressInterval .progress Interval for the progress bar. (advanced)

------------------------------------------------------------------------------------------

4 Module operations

4.1 Creating, distributing, and downloading modules

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.

4.2 Module metadata

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

4.3 Module dependencies

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

------------------------------------------------------------------------------------------

5 Module functions

A collection of functions that help with making modules can be found in the suggested SpaDES.tools package, and are summarized below.

5.1 Spatial spreading/distances methods

Spatial contagion is a key phenomenon for spatially explicit simulation models. Contagion can be modelled using discrete approaches or continuous approaches. Several SpaDES.tools functions assist with these:
adj An optimized (i.e., faster) version of adjacent
cir Identify pixels in a circle around a SpatialPoints* object
directionFromEachPoint Fast calculation of direction and distance surfaces
distanceFromEachPoint Fast calculation of distance surfaces
rings Identify rings around focal cells (e.g., buffers and donuts)
spokes Identify outward radiating spokes from initial points
spread Contagious cellular automata
wrap Create a torus from a grid

5.2 Spatial agent methods

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

5.3 GIS operations

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

5.4 'Map-reduce'--type operations

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.

5.5 Colors in Raster* objects

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

5.6 Random Map Generation

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

5.7 Checking for the existence of objects

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

5.8 SELES-type approach to simulation

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:
1 agentLocation Agent location
initiateAgents Initiate agents into a SpatialPointsDataFrame
numAgents Number of agents
probInit Probability of initiating an agent or event
transitions Transition probability

5.9 Miscellaneous

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

------------------------------------------------------------------------------------------

6 Caching simulations and simulation components

Simulation caching uses the reproducible package.

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 function, but often accessed as arg in spades
cache deprecated. Please use Cache
showCache Shows information about the objects in the cache
clearCache Removes objects from the cache
keepCache Keeps only the objects described
clearStubArtifacts Removes any erroneous items in a cache repository

A module developer can build caching into their module by creating cached versions of their functions.

------------------------------------------------------------------------------------------

7 Plotting

Much of the underlying plotting functionality is provided by the quickPlot package.

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

------------------------------------------------------------------------------------------

8 File operations

In addition to R's file operations, we have added several here to aid in bulk loading and saving of files for simulation purposes:

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

------------------------------------------------------------------------------------------

9 Sample modules included in package

Several dummy modules are included for testing of functionality. These can be found with file.path(find.package("SpaDES.core"), "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

------------------------------------------------------------------------------------------

10 Package options

SpaDES packages use 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/RtmpXXX/SpaDES/cache).

  • spades.cachePath: The default local directory in which to look for simulation inputs. Default is a temporary directory (typically /tmp/RtmpXXX/SpaDES/inputs).

  • spades.debug: The default debugging value for spades(). Default is FALSE.

  • 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/RtmpXXX/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/RtmpXXX/SpaDES/outputs).

  • spades.switchPkgNamespaces: Should the search path be modified to ensure a module's required packages are listed first? Default TRUE, which reduces name conflicts among package objects, but is not without overhead (i.e., can be slow).

  • spades.tolerance: The default tolerance value used for floating point number comparisons. Default .Machine$double.eps^0.5.

  • spades.useragent: The default user agent to use for downloading modules from GitHub.com. Default "http://github.com/PredictiveEcology/SpaDES".

See also

Useful links: