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)

(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?

• 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.

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

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

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?

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

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

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:

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

• 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

• Is there anything missing from the 15 items?