SpaDES (version 1.2.0)

SpaDES-package: Categorized overview of the SpaDES package

Description

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.

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

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

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

Arguments

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

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.
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 default values for a module
zipModule
Zip a module and its associated files

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

simList
The 'simList' class
------------------------------------------------------------------------------------------

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.
defineModule
Define the module metadata
defineParameter
Specify a parameter's name, value and set a default

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

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.
rasterizeReduced
Convert reduced representation to full raster

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

2.10 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
nlayers
Return number of layers
paddedFloatToChar
Wrapper for padding (e.g., zeros) floating numbers to character
updateList
Update values in a named list
------------------------------------------------------------------------------------------

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

5 Sample data and modules included in package

Five maps and three modules are included within the SpaDES package

5.1 Data

Several dummy data sets are included for testing of functionality
spadesMaps
Help showing included maps

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