Last chance! 50% off unlimited learning
Sale ends in
Create a new simulation object, the "sim" object. This object is implemented
using an environment
where all objects and functions are placed.
Since environments in R
are
pass by reference, "putting" objects in the sim object does no actual copy. This
is also the location of all parameters, and other important simulation information, such
as times, paths, modules, and module load order. See more details below.
simInit(times, params, modules, objects, paths, inputs, outputs, loadOrder)
# S4 method for list,list,list,list,list,data.frame,data.frame,character
simInit(times,
params, modules, objects, paths, inputs, outputs, loadOrder)
# S4 method for ANY,ANY,ANY,character,ANY,ANY,ANY,ANY
simInit(times, params,
modules, objects, paths, inputs, outputs, loadOrder)
# S4 method for ANY,ANY,character,ANY,ANY,ANY,ANY,ANY
simInit(times, params,
modules, objects, paths, inputs, outputs, loadOrder)
# S4 method for ANY,ANY,ANY,ANY,ANY,ANY,ANY,ANY
simInit(times, params, modules,
objects, paths, inputs, outputs, loadOrder)
A named list of numeric simulation start and end times
(e.g., times = list(start = 0.0, end = 10.0)
).
A list of lists of the form list(moduleName=list(param1=value, param2=value)). See details.
A named list of character strings specfying the names
of modules to be loaded for the simulation. Note: the module name
should correspond to the R source file from which the module is loaded.
Example: a module named "caribou" will be sourced form the file
caribou.R
, located at the specified modulePath(simList)
(see below).
(optional) A vector of object names (naming objects
that are in the calling environment of
the simInit
, which is often the
.GlobalEnv
unless used programmatically
-- NOTE: this mechanism will
fail if object name is in a package dependency), or
a named list of data objects to be
passed into the simList (more reliable).
These objects will be accessible
from the simList as a normal list, e.g,. mySim$obj
.
An optional named list with up to 4 named elements,
modulePath
, inputPath
, outputPath
, and cachePath
.
See details.
A data.frame
. Can specify from 1 to 6
columns with following column names: objectName
(character, required),
file
(character), fun
(character), package
(character),
interval
(numeric), loadTime
(numeric).
See inputs
and vignette("ii-modules") section about inputs.
A data.frame
. Can specify from 1 to 5
columns with following column names: objectName
(character, required),
file
(character), fun
(character), package
(character),
saveTime
(numeric). See outputs
and
vignette("ii-modules")
section about outputs.
An optional list of module names specfiying the order in which to load the modules. If not specified, the module load order will be determined automatically.
A simList
simulation object, pre-initialized from values
specified in the arguments supplied.
Calling this simInit function does several things including the following: - sources all module files, placing all function definitions in the sim object - optionally copies objects from the global environment to the sim object - optionally loads objects from disk - schedules all "init" events from all modules - assesses module dependencies via the inputs and outputs identified in their metadata - determines time units of modules and how they fit together
params
can only contain updates to any parameters that are defined in
the metadata of modules. Take the example of a module named, Fire
, which
has a parameter named .plotInitialTime
. In the metadata of that moduel,
it says TRUE. Here we can override that default with:
list(Fire=list(.plotInitialTime=NA))
, effectively turning off plotting. Since
this is a list of lists, one can override the module defaults for multiple parameters
from multiple modules all at once, with say:
list(Fire = list(.plotInitialTime = NA, .plotInterval = 2),
caribouModule = list(N = 1000))
.
We implement a discrete event simulation in a more modular fashion so it is
easier to add modules to the simulation. We use S4 classes and methods,
and use data.table
instead of data.frame
to implement the event
queue (because it is much faster).
paths
specifies the location of the module source files,
the data input files, and the saving output files. If no paths are specified
the defaults are as follows:
cachePath
: getOption("spades.cachePath")
;
inputPath
: getOption("spades.modulePath")
;
modulePath
: getOption("spades.inputPath")
;
inputPath
: getOption("spades.outputPath")
.
Matloff, N. (2011). The Art of R Programming (ch. 7.8.3). San Fransisco, CA: No Starch Press, Inc.. Retrieved from https://www.nostarch.com/artofr.htm
spades
,
times
, params
, objs
, paths
,
modules
, inputs
, outputs
# NOT RUN {
mySim <- simInit(
times = list(start = 0.0, end = 2.0, timeunit = "year"),
params = list(
.globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
),
modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
paths = list(modulePath = system.file("sampleModules", package = "SpaDES"))
)
spades(mySim, .plotInitialTime = NA)
# Change more parameters, removing plotting
wantPlotting <- FALSE
mySim <- simInit(
times = list(start = 0.0, end = 2.0, timeunit = "year"),
params = list(
.globals = list(stackName = "landscape", burnStats = "nPixelsBurned"),
fireSpread = list(.plotInitialTime=wantPlotting),
#caribouMovement = list(.plotInitialTime=wantPlotting),
#randomLandscapes = list(.plotInitialTime=wantPlotting)
),
modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
paths = list(modulePath = system.file("sampleModules", package = "SpaDES"))
)
outSim <- spades(mySim)
# A little more complicated with inputs and outputs
if (require(rgdal)) {
mapPath <- system.file("maps", package = "SpaDES")
mySim <- simInit(
times = list(start = 0.0, end = 2.0, timeunit = "year"),
params = list(
.globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
),
modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
paths = list(modulePath = system.file("sampleModules", package = "SpaDES"),
outputPath = tempdir()),
inputs = data.frame(
files = dir(file.path(mapPath), full.names = TRUE, pattern = "tif")[1:2],
functions = "raster",
package = "raster",
loadTime = 0,
stringsAsFactors = FALSE),
outputs = data.frame(
expand.grid(objectName = c("caribou","landscape"),
saveTime = 1:2,
stringsAsFactors = FALSE))
)
# Use accessors for inputs, outputs, times
mySim2 <- simInit(modules = list("randomLandscapes", "fireSpread",
"caribouMovement"),
params = list(.globals = list(stackName = "landscape",
burnStats = "nPixelsBurned")),
paths = list(modulePath = system.file("sampleModules",
package = "SpaDES"),
outputPath = tempdir()))
# add by accessor: note need current in times() accessor
times(mySim2) <- list(current=0, start = 0.0, end = 2.0, timeunit = "year")
inputs(mySim2) <- data.frame(
files = dir(file.path(mapPath), full.names = TRUE, pattern = "tif")[1:2],
functions = "raster",
package = "raster",
loadTime = 3,
stringsAsFactors = FALSE)
outputs(mySim2) <- data.frame(
expand.grid(objectName = c("caribou","landscape"),
saveTime = 1:2,
stringsAsFactors = FALSE))
all.equal(mySim, mySim2) # TRUE
}
# }
# NOT RUN {
# }
Run the code above in your browser using DataLab