Modules – Downloading and using existing modules

Alex M Chubaty & Eliot McIntire

October 2019

Source: vignettes/03a-Existing_modules.Rmd

How to share modules

  • We can share modules in any number of ways

    • email
    • Cloud (Dropbox, Google Drive, etc.)
    • Version Control repository (e.g.,SpaDES-Modules)

SpaDES-Modules GitHub repository

  • We have created a repository on GitHub for this purpose (like CRAN for SpaDES modules)
  • Of course, one can use any location, but we start here
  • It is open for viewing, even submitting to (like CRAN) via (pull request for now)
  • It is curated to some extent (like CRAN)

Downloading modules

  • There are several modules on SpaDES-Modules
  • Several types (agent-based, raster, GIS, etc)
  • We have several that are NOT hosted here, yet…
  • After publishing them, we will host them here.

Types we will look at

These are all simple, “toy” modules so far

  • Spread module (fire)
  • Agent-based modules (caribou, wolf)

Modules not on SpaDES-Modules yet, waiting for publication

  • Land-R_Biomass
  • Land-R_BiomassClimate
  • ECCC Caribou Population projection
  • R-CBM (carbon budget model)

Modules to download

Downloading

  • fireSpread
  • caribouMovementLcc
  • caribou2movements

What does each do?

When you go to the next steps, try things out… ask some of these questions:

  • Where do we start?
  • Are there bugs?
  • Are there visualizations?
  • Is is complex, simple?
  • What type of module is it?

Fire spread module

  • Lets start with a simple spreading module
library(SpaDES)
tmpdir <- file.path(dirname(tempdir()), "Modules")
downloadModule("fireSpreadLcc", path = tmpdir)
  • Where is it? (where is tmpdir?)
  • What does it look like?

Agent modules

Download toy movement module

  • Lets start with a simple movement module
library(SpaDES)
tmpdir <- file.path(dirname(tempdir()), "Modules")
downloadModule("caribouMovementLcc", path = tmpdir)

Wolf Alps & Caribou Gaspesie

Try one out

downloadModule("caribou2Movements", path = tmpdir)
downloadModule("wolfAlps", path = tmpdir) # ignore warning about file size

# Can open the .Rmd (how to run it) or .R (module code)
file.edit(file.path(tmpdir, "caribou2Movements", "caribou2Movements.Rmd"))
file.edit(file.path(tmpdir, "wolfAlps", "wolfAlps.Rmd"))
  • Can you get either to run?

Debugging

  • Lets do it…
  • Go back to SpaDES wiki pages (how do I find it again…?)… Maybe Google search “R SpaDES wiki”
  • Remember the debugging tools
  • ?spades has new section on debugging that complements the above wiki

Meta models

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)

setPaths(cachePath = "~/temp_SpaDESws/cache", 
         inputPath = "~/temp_SpaDESws/inputs", 
         modulePath = "~/temp_SpaDESws/modules", 
         outputPath = "~/temp_SpaDESws/outputs")

openModules("LCC2005", getPaths()$modulePath)

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

If you restarted your R session, first prepare the global setup again:

library(SpaDES)

# Remember, if you changed it in the previous step, keep it the same. Otherwise it won't find your modules!
setPaths(cachePath = "~/temp_SpaDESws/cache", 
         inputPath = "~/temp_SpaDESws/inputs", 
         modulePath = "~/temp_SpaDESws/modules", 
         outputPath = "~/temp_SpaDESws/outputs")

Then, prepare the simulation:

# setup simulation

times <- list(start = 2005.0, end = 2015.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 = getPaths()$cachePath,
  modulePath = getPaths()$modulePath,
  inputPath = getPaths()$inputPath,
  outputPath = getPaths()$outputPath
)
mySim <- simInit(modules = modules, paths = paths, params = parameters, times = times)

Create a new parent module

The LCC2005 is a parent module that contains several children (What are they?). Now make a new parent module from several of the LCC2005 modules, but without, say, fire.

allButFire <- unlist(modules(mySim))[-6]
newModule("LCC2005NoFire", children = allButFire)
openModules("LCC2005NoFire", getPaths()$modulePath)

Go ahead and open the LCC2005NoFire.R and check the child modules in the metadata.

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?