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: 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) |
1.2 <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.1.2.1 Simulation parameters
Accessor functions for the params slot and its elements. Commonly used:
globals |
| List of global simulation parameters. |
objs |
| List of objects referenced by the simulation environment. |
params |
| Nested list of all simulation parameter. |
Advanced use:
|
Accessor method |
Module |
| Description |
checkpointFile |
.checkpoint |
Name of the checkpoint file. (advanced) |
checkpointInterval |
.checkpoint |
| The simulation checkpoint interval. (advanced) |
outputPath |
NA |
Global simulation output path. (advanced) |
inputPath |
NA |
| Global simulation input path. (advanced) |
modulePath |
NA |
Global module path. (advanced) |
paths |
NA |
| Show all paths (input, output, module). (advanced) |
progressType |
.progress |
Type of graphical progress bar used. (advanced) |
progressInterval |
.progress |
| Interval for the progress bar. (advanced) |
Accessor method |
1.2.2 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.. |
1.2.3 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) |
1.2.4 Modules and dependencies
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) |
inputs |
| List of loaded objects used in simulation. (advanced) |
outputs |
| List of objects to save during simulation. (advanced) |
1.2.5 Copy simList
The simList has a slot with all objects, called ".envir". This is an
environment. 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.
copy |
| Deep copy of a simList. (advanced) |
1.3 Module operations
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. 1.4 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 |
1.5 Exported <code>SpaDES</code> object classes
------------------------------------------------------------------------------------------2 Module functions
A collection of functions that help with making modules, in addition to all the other R packages and code.2.1 Module metadata
Each module requires several items to be defined.
These comprise the metadata for that module (including default parmater specifications),
and are currently written at the top of the module's .R file. 2.2 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 functions assist
with these: 2.3 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 |
2.4 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 |
2.5 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.
2.6 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 |
2.7 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 |
2.8 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 |
2.9 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:
2.10 Miscellaneous
Functions that may be useful within a SpaDES context
------------------------------------------------------------------------------------------3 Plotting
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 |
------------------------------------------------------------------------------------------4 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: ------------------------------------------------------------------------------------------5 Sample data and modules included in package
Five maps and three modules are included within the SpaDES package5.1 Data
Several dummy data sets are included for testing of functionality
5.2 Modules
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 |