1 Building models from modules

A model (as defined in the SpaDES world) consists of multiple interacting components (sub-models), which in the vocabulary of SpaDES we have been referring to as ‘modules’

  • One could imagine an example model:

    • caribou movement
    • vegetation dynamics
    • disturbance dynamics
    • data cleaning, downloading, etc.

  • And we would give this ensemble of modules a name, like “LCC2005” (or maybe even a better name, but we will go with this)

2 LCC2005

(Return to LCC2005 model)

library(igraph)
library(SpaDES)

workDirectory <- file.path(dirname(tempdir()), "Lcc2005")
moduleDir <- file.path(workDirectory, "modules") %>%
  checkPath(., create = TRUE)
downloadModule("LCC2005", moduleDir)
openModules("LCC2005", moduleDir)
  • Examine this module
  • What is different about it?

3 Parent modules (a.k.a. module groups)

  • Currently, only used to identify a group of modules
  • Uses “childModules” list entry
  • Currently, a parent module can not have any events or functions only metadata and only childModules is used
  • This may be changed in the future, but most likely by simplifying the number of entries in the metadata


  • Will this decision (by SpaDES developers) create problems?


  • Can have grand-parents, great-grandparents, mixtures of parents, grand-parents etc.

4 Running a parent module

# setup simulation
outputDir <- file.path(workDirectory, "simOutputs")
cacheDir <- checkPath(file.path(outputDir, "cache"), create = TRUE)
times <- list(start = 2005.0, end = 2020.0, timeunit = "year")
parameters <- list(
  .globals = list(burnStats = "fireStats"),
  fireSpreadLcc = list(drought = 1.2),
  caribouMovementLcc = list(N = 1e3, startTime = times$start + 1, 
                            glmInitialTime = NA_real_)
)
modules <- list("LCC2005")
paths <- list(
  cachePath = cacheDir,
  modulePath = moduleDir,
  inputPath = moduleDir,
  outputPath = outputDir
)

5 Visual tools

There are a few tools that can help visualize the relationships between modules:

# This next step will download data if they do not yet exist locally
lcc <- simInit(times = times, params = parameters,
               modules = modules, paths = paths)

objectDiagram(lcc)
moduleDiagram(lcc)
eventDiagram(lcc)

lcc <- spades(lcc)  # compare the diagrams after running sim

What do/would these do?

Do they all work after simInit?

6 Creating a new parent module

The newModule function creates a module template for you to edit to suit your needs:

newModule('moduleName', file.path('path/to/my/module/directory'),
          type = 'parent', children = c('child1', 'child2'))

Alternatively, use the RStudio addin which is simply a GUI wrapper for this function (select ‘parent’ type):

7 Parent modules

7.1 A hypothetical example

The new CFS-FD model (Forest Dynamics Model)

  • Has carbon, caribou, vegetation change, harvesting, climate, fire, insects

  • But the vegetation module is actually a parent module with 3 modules:

    • mortality, growth, and regeneration modules

  • fire module is actually 4 modules:

    • ignition, escape, spread, severity modules

8 Parent modules

8.1 Where to put code?

  • Likely you can imagine that there would be code you would want to put in the parent module
  • We had many discussions about this
  • We concluded:

make a child module that does all the stuff you might think of as parent module content, add appropriate data dependencies
(i.e., outputs are required by the other modules as inputs)

9 Child modules

  • Everything that we have talked about to date is a child module
  • This means that it is a stand alone module

10 Using metadata

  • There are 15 items in the metadata header
  • The header is defined withe the SpaDES function defineModule
  • Usually at the top of the module script, but it doesn’t have to be
  • In the future, this will likely expand, and gain functionality to allow increased automation
# What are the 15 items?
  • Explore different options

11 Metadata

  • Is there anything missing from the 15 items?