In PredictiveEcology/SpaDES.Workshops: Training workshops for ecological modeling with SpaDES

knitr::opts_chunk$set(cache = TRUE, echo = TRUE, eval = FALSE)

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

• In SpaDES-Modules repository,
• Two published movement modules
• Wolfs recolonizing the Alps
• Caribou in Gaspésie

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

library(igraph)
g <- data.frame(from = c("grandparentModule", "grandparentModule",
                         "parentModuleA", "parentModuleA",
                         "parentModuleB", "parentModuleB"),
                to = c("parentModuleA", "parentModuleB",
                       "childModuleA1", "childModuleA2",
                       "childModuleB1", "childModuleB2")) %>% 
  graph_from_data_frame()
plot(g, mark.groups = list(1:7, c(2,4,5), c(3,6,7)))

### NOT RENDERING IN THE WEBSITE!

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?

PredictiveEcology/SpaDES.Workshops documentation built on Jan. 30, 2021, 6:52 p.m.