Getting Started Guide

Prerequisites

1. Install R (version >=3.2.2).
2. (optional) Install Rstudio.

Installation

1. Install the SpaDES package via CRAN:

   install.packages("SpaDES")

   Since SpaDES is still a package in the early stages of maturity, the development branch on GitHub may contain useful bug fixes that are not in the CRAN version. To install this development version:

   library("devtools")
   install_github("PredictiveEcology/SpaDES", ref = "development")

2. Using the instructions above, devtools::install_github() will automatically try to install the optional fastshp package. This additional package requires OS development tools (e.g., Rtools for Windows). If the above installation doesn't work for you, be sure to install the necessary development tools before reinstalling the package.

   install.packages("fastshp", repos = "http://rforge.net", type = "source")

Getting Started with SpaDES

Load the SpaDES package in your R session using library(SpaDES).

Using pre-existing modules

1. Browse locally available modules:

   openModules(path = "/path/to/my/modules") # opens all modules in a directory
   openModules("moduleName", "/path/to/my/modules") # opens only the named module

2. Browse modules at https://github.com/PredictiveEcology/SpaDES-modules

3. Download modules for use:

   downloadModule("moduleName", path = "/path/to/my/modules", data = TRUE)
   openModules("moduleName", "/path/to/my/modules")

Creating new modules

1. Create an empty module template:

   newModule("moduleName", path = "/path/to/my/modules")

2. Read the modules vignette for more details.

Module development checklist

Metadata

• are module metadata fully and correctly specified (module description, authorship and citation info, parameters and inputs/outputs, etc.)?
• citation should specify how to cite the module, or if published, the paper that describes the module.
• module object dependencies: use moduleDiagram and objectDiagram to confirm how data objects are passed among modules.

Events

• are all event types defined in doEvent?
• use sim$function(sim) to access event functions
• use sim$object to access simulation data objects
• use e.g., sim[[globals(sim)$objectName]] to access variable-named objects
• use unique function names to reduce the risk of another module overwriting your functions. E.g., use moduleNameFunction() instead of function().
• using sim$function notation is not required for the definition of event functions

Documentation

• have you provided useful (meaningful) documentation in the module's .Rmd file and README?
• have you built (knitted) the .Rmd file to generate a .pdf or .html version?
• have you specified the terms under which your module code can be reused and/or modified? Add a license!

Data

• verify that data you wish to include with your module are saved in data/
• verify that external data sources are included in the sourceURL metadata field
• verify that any additional data preparation/transformation steps used in .inputObjects are correct
• write CHECKSUMS.txt file for all data using checksums(..., write = TRUE)

Distributing your module

• where will your module code/data be hosted?
• test downloadModule and downloadData from a temp dir to ensure your module can be downloaded correctly by others

Strategies for module development

Speed considerations

Since modules will often have to run many, many times because of replication, there are a few strategies that should be followed:

• Always write fast code. This means use data.table or dplyr for data and data wrangling.

  • Avoid data.frame if possible.
  • Matrices and vectors are fast.
  • Avoid loops.

• Use memoise or archivist package to cache functions for speed. We will soon be pushing out ways and examples to do this easily for functions within a module.

• For computationally intensive functions, consider writing them in C++, via the Rcpp package.

• For large (out of RAM) situations, use ff or bigMemory. Sometimes, these can be done seamlessly inside functions using the getOption("spades.lowMemory"), where two alternatives a provided, one "in Memory" the other "on disk". See "if (lowMemory)" code block about 20 lines from start of spread function for one way to do this with ff.

Other best practices

• Don't write modules that depend internally on other modules. Instead, pass data via the inputObjects and outputObjects in the metadata. This means avoid scheduling one event in module A from module B, if possible.
• Use existing modules from the SpaDES-Modules repository (https://github.com/PredictiveEcology/SpaDES-modules) using downloadModule().

Types of modules

Modules are generic. The only components that must exist are the metadata and the init event. This means that many, many types of modules can be written. As we slowly build a SpaDES ecosystem of modules designed to be used and re-used, we can consider writing our entire work flow -- raw data, data wrangling, data analysis, calibration of simulation model, simulation, output analysis, decision support -- all in one chain. We can cache everything along the way, so that if something must run again, but its inputs are identical to a previous run, then it can just read from disk.

This is an evolving list of types of modules that would be useful to have in this "re-use" cycle:

• dynamic forecasting

  • "classical" simulation models
  • netLogo-type models
  • SELES-type models
  • time is a component of the model

• static forecasting

  • e.g., predict methods from statistical outputs

• agent based models

  • animals, plants
  • processes, such as fire

• raster models

  • e.g., forest succession, cellular automata

• statistical

  • Bayesian

• calibration and optimization

  • taking outputs from other modules and rescheduling those other modules again, iterating through a heuristic optimization

• translators

  • from one data type to another to allow two different modules to talk

• GIS

  • reprojection, crop, mask etc.

• data fetching

  • modules that go to specific web resources (e.g., Dryad etc.)

• data manipulation

  • simplifying, joining etc.
  • interpolators

• output analysis

  • e.g., takes time series of rasters and visualizes them

• quality scanning - e.g., from external databases

Current modules on the SpaDES-modules repository (see above) include simple versions of dynamic forecasting (Forest Succession, fireSpreadLcc, forestAge), GIS (cropReprojectLccAge), translators (LccToBeaconsReclassify),