simList – What is in it?

Alex M Chubaty & Eliot McIntire

2019 October 17

Where does simList come from?

1. Initializing a simulation using simInit() creates a simList object.

2. Running a simulation via a spades() call returns a modified simList object.

How are simulations specified?

A simList object is simply a structured data type containing various elements of a simulation.

The main components of a simList are:

1. A list of modules used;
2. The event queue;
3. A description of the data (object) dependencies.

How SpaDES works: simLists

We can examine the simList object structure in the usual R fashion by printing (showing) it, or by using str():

emptySim <- simInit()
emptySim  # same as show(emptySim)
str(emptySim)

NOTE: simLists are S4 objects, so we can use getSlots() and slotNames() to examine the object.

See also ?'.simList-class'

Accessing the parts of a simLists

## Setting:
##   options(
##     reproducible.cachePath = '/private/var/folders/l2/hy6b0sl977bcd8695nt6j7s80000gn/T/RtmpAl0B0u/reproducible/cache'
##     spades.inputPath = '/private/var/folders/l2/hy6b0sl977bcd8695nt6j7s80000gn/T/RtmpcfSl1B/SpaDES/inputs'
##     spades.outputPath = '/private/var/folders/l2/hy6b0sl977bcd8695nt6j7s80000gn/T/RtmpcfSl1B/SpaDES/outputs'
##     spades.modulePath = '/private/var/folders/l2/hy6b0sl977bcd8695nt6j7s80000gn/T/RtmpcfSl1B/SpaDES/modules'
##   )

slot	accessor
modules	modules()
params	params()
events	events()
current	current()
completed	completed()
depends	depends()
simtimes	times()
inputs	inputs()
outputs	outputs()
paths	paths()
.envir	envir()
.xData	objects()

other_accessors
packages()
globals()
start()
end()
timeunit()
timeunits()
paths()
cachePath()
inputPath()
outputPath()
modulePath()

Model specification

Simple examples (using demo modules) of simInit() and spades() calls.

• examine simList structure before and after the spades() call

Initiliaze an empty simList object

emptySim <- simInit()

Inspect the empty simList object

1. What are the names of each of the slots in the simList?
2. What do each of these slots contain? Hint: see ?'.simList-class'.

str(emptySim)
slotNames(emptySim)
getSlots('simList')
?'.simList-class'

Initialize a simulation using sample modules

This code is based on the SpaDES package demo.

set.seed(42)

filelist <- data.frame(
  files = dir(system.file("maps", package = "SpaDES"),
              full.names = TRUE, pattern = "tif"),
  functions = "rasterToMemory",
  packages = "SpaDES",
  stringsAsFactors = FALSE
)

# create the simList object 'mySim'
mySim <- simInit(
  times = list(start = 0.0, end = 100.00),
  params = list(
    .progress = list(type = NA, interval = NA),
    .globals = list(burnStats = "nPixelsBurned"),
    randomLandscapes = list(
      nx = 1e2, ny = 1e2, .saveObjects = "landscape",
      .plotInitialTime = NA, .plotInterval = NA, inRAM = TRUE
    ),
    caribouMovement = list(
      N = 1e2, .saveObjects = c("caribou"),
      .plotInitialTime = 1, .plotInterval = 1, moveInterval = 1
    ),
    fireSpread = list(
      nFires = 1e1, spreadprob = 0.235, persistprob = 0, its = 1e6,
      returnInterval = 10, startTime = 0,
      .plotInitialTime = 0, .plotInterval = 10
    )
  ),
  modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
  inputs = filelist,
  paths = list(modulePath = system.file("sampleModules", package = "SpaDES"))
)

mySim$landscape <- stack(mySim$DEM, mySim$forestAge, mySim$habitatQuality, mySim$percentPine)

Inspect the new simList object

Use the simList accessor functions to determine the following:

1. the modules included in the simulation and their package dependencies;
2. the global parameter values used;
3. the module-specific parameter values used;
4. the simulation start and end times;
5. the timeunits used by the modules in the simulation;
6. the scheduled and completed event queues;
7. the objects (functions, data, etc.) used in the simulation;
8. the file paths used for simulation inputs and outputs.

# list modules used in the simulation
modules(mySim)

# list module dependencies and packages used
depends(mySim)
packages(mySim)

# list global and module-specific param values
globals(mySim)
params(mySim)
P(mySim)       ## bonus: how do params() and P() differ?

# list start and end times
times(mySim)
start(mySim)
end(mySim)

# get the simulation and module timeunits
timeunit(mySim)
timeunits(mySim)

# get the scheduled and completed event queues
events(mySim)
completed(mySim)

# list the objects (functions, data, etc.) stored in the simList
objects(mySim)

# list the file paths used in the simulation
paths(mySim)
inputPath(mySim)
outputPath(mySim)

Run the simulation

dev()
mySimOut <- Copy(mySim) ## make a deep copy of the simList
mySimOut <- spades(mySimOut)

Compare the simList before and after

times(mySim)
times(mySimOut)

objects(mySim)
objects(mySimOut)