3 Passing data between modules
Modularity in SpaDES simulations is maintained by ensuring modules interact indirectly with one another by reading in and modifying objects in the simulation environment.
3.1 Data types
As you build your modules for your simulation, you can use any of R’s data types to store your objects and data. In particular, matrices (including vectors) and lists work well for this purpose because, as of R version 3.1.0, they are more efficient, reducing your model’s memory footprint and speeding up your code’s execution. Other useful datatypes include Raster* and SpatialPoints* objects (see examples below).
3.2 Global objects and the simulation environment
R passes copies of objects to functions (instead of using pass-by-reference), so the typical R function never acts directly on the global copy of the variable. Within a function, all operations are generally performed on a local copy of the object, which is then either discarded or returned back to the parent environment upon when the function completes. This object-copying behaviour has given R a reputation of being slow in comparison to languages like C and FORTRAN. However, recent improvements to R have made it more memory efficient and faster to execute, in part by minimizing the number of object copies made and lazy loading.
One way SpaDES reduces object copying is by storing and modifying objects in a simulation environment, because environments in R have reference semantics. Instead of storing simulation data in the global environment, each SpaDES simulation uses a unique environment wherein simulation data are referenced.
3.3 Module object dependencies
As noted above, modules should not depend on one another for event scheduling. However, it is often useful to develop collections of modules that interact indirectly and are dependent on shared data objects. Modules can be designed to rely on outputs (data objects) from other modules. When objects are shared between modules, it is important to state these dependencies explicitly. To check whether objects upon which a model depends exist, a call to checkObject is made during module initialization.
Note that modules need not be inter-dependent on one another: module B may depend on module A (for example to initialize a data object), without module A depending on module B.
To view the dependencies for a simulation:
library(SpaDES)
times <- list(start = 0.0, end = 20)
parameters <- list(
.globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
)
modules <- list("randomLandscapes", "fireSpread", "caribouMovement")
paths <- list(modulePath = system.file("sampleModules", package = "SpaDES"))
mySim <- simInit(times = times, params = parameters, modules = modules, paths = paths)
## examine simulation module (object) dependencies
depsEdgeList(mySim, FALSE) # all object dependency relationships## from to objName objClass
## 1: caribouMovement caribouMovement landscape RasterStack
## 2: caribouMovement fireSpread landscape RasterStack
## 3: fireSpread caribouMovement landscape RasterStack
## 4: fireSpread fireSpread landscape RasterStack
## 5: fireSpread fireSpread nPixelsBurned numeric
## 6: randomLandscapes caribouMovement landscape RasterStack
## 7: randomLandscapes fireSpread landscape RasterStackmoduleDiagram(mySim) # simplified visual representation of modules
# detailed visual representation of objects
objectDiagram(mySim, width = 720)The output of the depsEdgeList is an edgelist describing the relationships between each module. In the example above, line 2 of the output indicates that the fireSpread module relies on an object landscape provided by the caribouMovement module. This edgelist is used inside the depsGraph function to produce a dependency graph (network), where each module corresponds to a vertex (node), and object dependencies are denoted by the arrows. When plotting the dependency graph, it’s often useful to use the plot=TRUE argument to simplify the network by showing no more than one object dependency between modules.