• 1 Getting started with SpaDES
  • 2 Anatomy of a SpaDES module
    • 2.1 Directory structure
  • 3 Anatomy of a SpaDES module
    • 3.1 Directory structure
  • 4 Anatomy of a SpaDES module
    • 4.1 Code file structure
  • 5 New module template
  • 6 1. Module metadata
  • 7 1. Module metadata
    • 7.1 Module parameters
  • 8 1. Module metadata
    • 8.1 Data dependencies
  • 9 1. Module metadata
    • 9.1 Working with data
  • 10 2. Module events
  • 11 3. Additional module functions
  • 12 4. The .inputObjects block (optional)
  • 13 Visualizations
  • 14 Plotting
  • 15 Event-level plotting
  • 16 Interacting with plots
  • 17 Saving
  • 18 Loading
  • 19 Checkpointing
  • 20 Debugging
  • 21 Finding SpaDES tools
    • 21.1 Categorized overview of the SpaDES package
  • 22 Summary statistics
  • 23 Module development checklist
    • 23.1 Metadata
  • 24 Module development checklist
    • 24.1 Events
  • 25 Module development checklist
    • 25.1 Documentation
  • 26 Module development checklist
    • 26.1 Data
  • 27 Module development checklist
    • 27.1 Distributing your module

1 Getting started with SpaDES

2 Anatomy of a SpaDES module

2.1 Directory structure

module.path <- file.path(dirname(tempdir()), "modules")
downloadModule('wolfAlps', module.path, data = TRUE)
list.files(file.path(module.path, 'wolfAlps'), all.files = TRUE)
/moduleRepository
  |_ moduleName/
      |_ data/                  # directory for all included data
          |_ CHECKSUMS.txt      # contains checksums for data files
      |_ citation.bib           # bibtex citation for the module
      |_ LICENSE.txt            # describes module's legal usage
      |_ README.txt             # provide overview of key aspects
      |_ moduleName.R           # module code file (incl. metadata)
      |_ moduleName.Rmd         # documentation, usage info, etc.
      |_ moduleName_x.y.z.zip   # zip archive of previous versions

3 Anatomy of a SpaDES module

3.1 Directory structure

advanced: not included (yet) in the main module repo are examples of modules that include unit tests and code coverage.

These are encouraged and can be built using

# when creating a new module
newModule(..., unitTests = TRUE) # default

# or after-the-fact with
newModuleTests(...)

4 Anatomy of a SpaDES module

4.1 Code file structure

samplePath <- system.file('sampleModules', package = 'SpaDES')
openModules('randomLandscapes', samplePath)

A module code file (.R) consists of the following key sections:

  1. module metatadata (defineModule block)

  2. definitions of each module event type (doEvent.moduleName block)

  3. additional functions used in the events above

  4. (optional) block of code that is run during module initialization, used to perform additional data processing/transformation steps (.inputObjects block)

5 New module template

The newModule function creates a module template for you to edit to suit your needs:

newModule('moduleName', file.path('path/to/my/module/directory'))

Alternatively, use the RStudio addin which is simply a GUI wrapper for this function:

6 1. Module metadata

Each module requires a collection of metadata describing the module, its dependencies, and linking to documentation, etc.

These metatadata are defined in the defineModule code block at the start of the file, and are intended to be both human and machine readable.

# see section 'Required metadata elements'
?defineModule

7 1. Module metadata

7.1 Module parameters

Parameters defined in the module’s defineParameter block are module-specific.

This is where default parameter values are specified (which can be overridden by the user during simInit()).

8 1. Module metadata

8.1 Data dependencies

The inputObjects and outputObjects metadata fields specify a module’s inputs and outputs respectively.

These refer to R objects, rather than raw data files.

9 1. Module metadata

9.1 Working with data

  • data can be bundled directly with your module or can be hosted externally
  • sourceURL field in module metadata is used for URLs of external data, which are downloaded using downloadData()
  • checksums are to verify file integrity of the data (e.g., in case of download error or change in the data file)

10 2. Module events

  • Each module may contain an arbitrary number of event types.

  • Each event consists of two parts:

    1. what to do right now;
    2. what to do later (via scheduleEvent())

  • To keep this section as easy to read as possible, use additional module functions (defined in the section below).

11 3. Additional module functions

  • Should get and return objects in the simulation environment (envir), rather than pass them as function arguments.
  • Accessing objects in envir is similar to accessing items in a list, i.e., sim[["object"]] or sim$object can be used.
  • To ensure unique function names, follow the naming convention modulenameEventtype().

12 4. The .inputObjects block (optional)

See ?defineModule for details.

13 Visualizations

SpaDES builds on R’s exceptional graphics capabilities, and the standard R visualization packages etc. can be used with SpaDES.

However, for fast prototyping and on-the-fly graphics useful for module debugging and development you should use Plot().

- much faster than base graphics, ggplot, etc.
- modular plotting (automatic multipanel layouts)

WARNING: The built-in RStudio plotting device is heinously slow!

dev()

14 Plotting

See the plotting vignette and ?Plot for more detailed examples.

Plot(...)
clearPlot()

Plot(..., new = TRUE)
Plot(..., addTo = objectName)

rePlot()

15 Event-level plotting

Module-specific plot parameters can be used to control plotting for your event: .plotInitialTime and .plotInterval.

E.g., schedule a recurring plot event within a module:

nextPlot <- time(mySim) + SpaDES::p(mySim)$.plotInterval
mySim <- scheduleEvent(mySim, nextPlot, "moduleName", "plot")

16 Interacting with plots

See http://spades.predictiveecology.org/vignettes/iii-plotting.html#interacting-with-plots

  • clickValues()
  • clickExtent()

17 Saving

E.g., schedule a recurring save event within a module:

nextSave <- time(mySim) + SpaDES::p(mySim)$.saveInterval
sim <- scheduleEvent(mySim, nextSave, "moduleName", "save")

19 Checkpointing

Checkpointing is build into SpaDES automatically and can be turned on at the simulation level (not the module level).

parameters <- list(
  .checkpoint = list(interval = 10, file = "chkpnt.RData")
)

mySim <- simInit(..., params = parameters)

See vignette for more details.

NOTE don’t checkpoint too often, or your simulation will slow down too much (disk writes are slow).

20 Debugging

  • using spades(sim, debug = TRUE)

  • adding browser() calls to your module code

  • using the Rstudio debugger

21 Finding SpaDES tools

21.1 Categorized overview of the SpaDES package

?SpaDES
  1. Spatial discrete event simulation (SpaDES)
  2. Module functions
  3. Plotting
  4. File operations
  5. Sample data and modules included in package

22 Summary statistics

See this wiki entry.

  1. Add a new module parameter and output to the module metadata.

  2. Add a ‘summarize’ event.

  3. Add an new event function that calculates the statistic(s) of interest.

  4. Update your module’s reqdPkgs metadata field if you are using additional packages.

23 Module development checklist

*Adapted from the one on the wiki.

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

24 Module development checklist

*Adapted from the one on the wiki.

24.1 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

25 Module development checklist

*Adapted from the one on the wiki.

25.1 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!

26 Module development checklist

*Adapted from the one on the wiki.

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

27 Module development checklist

*Adapted from the one on the wiki.

27.1 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