Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
339 lines (229 sloc) 9.21 KB
---
title : "Modules -- Downloading and using existing modules"
author : "Alex M Chubaty & Eliot McIntire"
date : "December 9, 2016"
---
```{r setup, include=FALSE}
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 -- 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, but not for submitting to (like *CRAN*)
- Therefore it is curated to some extent
## 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
```{r}
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
```{r}
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](https://htmlpreview.github.io/?https://github.com/PredictiveEcology/SpaDES-modules/blob/master/modules/wolfAlps/wolfAlps.html)
- [Caribou in Gaspésie](https://htmlpreview.github.io/?https://github.com/PredictiveEcology/SpaDES-modules/blob/master/modules/caribou2Movements/caribou2Movements.Rmd)
### Try one out
```{r}
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](https://github.com/PredictiveEcology/SpaDES/wiki/Debugging)
- `?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](http://htmlpreview.github.io/?https://github.com/PredictiveEcology/SpaDES-modules/blob/master/modules/LCC2005/LCC2005.html))
```{r exercise1}
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
<br>
- Will this decision (by `SpaDES` developers) create problems?
<br>
- Can have grand-parents, great-grandparents, mixtures of parents, grand-parents etc.
## Module relationships
```{r relationship-diagram, echo=FALSE, eval=TRUE, message=FALSE, fig.height=5, fig.width=5}
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
```{r}
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
```{r run-lcc, echo=TRUE, eval=FALSE}
# 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.
```{r}
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:
```{r visualize-sim, echo=TRUE, eval=FALSE}
# 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:
```{r new-module, echo=TRUE, eval=FALSE}
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):
![](images/screenshot-new-module-addin.png)
## 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:
<div class="centered" style="color:#0000FF">
*make a child module that does all the stuff you might think of as parent module content, add appropriate data dependencies*<br>
*(*i.e.*, outputs are required by the other modules as inputs)*
</div>
## 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
```{r define module}
# What are the 15 items?
```
- Explore different options
## Metadata
- Is there anything missing from the 15 items?