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)

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?

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.

Module relationships

Module directory structure

moduleRepo/
  |_ childModuleA1/
  |_ childModuleA2/
  |_ childModuleB1/
  |_ childModuleB2/
  |_ grandparentModule/
  |_ parentModuleA/
  |_ parentModuleB/

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
)

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?

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

Parent modules

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

Parent modules

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)

Child modules

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

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

Metadata

• Is there anything missing from the 15 items?