Develop and Run Spatially Explicit Discrete Event Simulation Models

Metapackage for implementing a variety of event-based models, with a focus on spatially explicit models. These include raster-based, event-based, and agent-based models. The core simulation components (provided by 'SpaDES.core') are built upon a discrete event simulation (DES) framework that facilitates modularity, and easily enables the user to include additional functionality by running user-built simulation modules (see also ''). Included are numerous tools to visualize rasters and other maps (via 'quickPlot'), and caching methods for reproducible simulations (via 'reproducible'). Additional functionality is provided by the 'SpaDES.addins' and 'SpaDES.shiny' packages.

Easily implement a variety of simulation models, with a focus on spatially explicit models. These include raster-based, event-based, and agent-based models. The core simulation components are built upon a discrete event simulation framework that facilitates modularity, and easily enables the user to include additional functionality by running user-built simulation modules. Included are numerous tools to rapidly visualize raster and other maps.



Building packages from source requires the appropriate development libraries for your operating system (e.g., Windows users should install Rtools).

The suggested package fastshp can be installed with:

install.packages("fastshp", repos = "", type = "source")

Install from CRAN:


Install from GitHub:

install_github("PredictiveEcology/SpaDES", dependencies = TRUE) # stable

Install from GitHub:

install_github("PredictiveEcology/SpaDES", ref = "development", dependencies = TRUE) # unstable


Available via our wiki or via browseVignettes(package = "SpaDES").


Q&A Forum:

Contact us via the package GitHub site:

Copyright (C) 2016 Her Majesty the Queen in Right of Canada, as represented by the Minister of Natural Resources Canada


Known issues:

version 1.3.1

  • Default module path (set via spades.modulePath option) is now set to a temporary location to avoid unintentionally writing to the user's home directory.
  • add options for cache, input, output dirs (defaults to a temp dir until changed by user)
  • rename spades.modulesPath and spades.modulesRepo options to spades.modulePath and spades.moduleRepo
  • New cache-related functions: showCache and clearCache

version 1.3.0

  • stricter package version dependencies in Imports and Suggests

  • debug argument in spades() can now take any expression, character strings. TRUE/FALSE changed behavior to show only current event.

  • timeunits: when there are parent and grandparent modules, if timeunit is defined, it overrides the "smallest unit" rule. Thus, a parent module can force a timeunit.

  • Plot - enhancements and fixes:

    • more robust base plotting and many visual tests on Windows;
    • re-add col arg to Plot (mimicks cols). Was lost from version 1.1.2;
    • allow any arbitrary function to be used internally to Plot (e.g., barplot, plot, etc.);
    • add arr argument to Plot(), allowing passing of arrangement;
    • allow title arg in Plot() to accept character for plot title;
    • Plot can use character passed to title as a title;
    • some additional functionality for plotting of factor rasters, incl. clickValues, legends correct for wide variety of types;
    • change new arg in Plot(). Now it does one plot at a time, not whole device. Use clearPlot() to wipe whole device.
  • Add modulesGraph, showing parent and child module relationships.

  • Add filesOnly arg to shine(). This can be in preparation for publishing to or other pages. Currently still alpha.

  • Add POM: Pattern Oriented Modeling (#269). A simple interface to a simList object, allowing fitting parameters to data.

  • add .inputObjects functionality -- function that runs during simInit() to create default inputObjects

  • add P as a namespaced shortcut for params: P(sim) would replace params(sim)$moduleName when called from within that module

  • allow params(sim) & start(sim) & others in defineModule() by changing parse order in module metadata

  • add explicit cl arg to parallel aware functions, for more control

  • newModule gains new arguments type = c("child", "parent") and children = c(). See ?newModule (#300).

  • module structure now includes an R subfolder for R scripts. These will be parsed during simInit.

  • checksums updated to use faster hashing algorithm (xxhash64) and now only requires a single hash value per file (#295)

  • new Rstudio addin for 'newModule' (#298); requires Import of shiny (>= 0.13), miniUI (>= 0.1.1), and rstudioapi (>= 0.5)

  • fixed bugs in module template

  • fixed bug in cir (#288, #311)

  • improved use of package options; added new option spades.modulesPath.

  • improved downloadModule to use option spades.modulesPath (#309)

  • improved specification of module inputs and outputs (#189, #214, PR#310)

  • remove module version warning (#312)

  • other tweaks and fixes

version 1.2.0

  • fix bug associated with forthcoming dplyr update
  • remove gtools and secr from Imports
  • spread enhancements: circular spreading, landscape-based functions, allow overlapping events
  • enhancements to cir and bug fix (#290)
  • new function rings whose argument names closer match to cir
  • performance enhancements in spread, rings, cir
  • add cache and progress args to spades and experiment functions
  • Plot now clips symbols (generally points) to plotting area. This will allow future "wiping" of plot area.
  • dev() returns dev.cur invisibly, allowing for finer control of plotting devices
  • add distanceFromEachPoint, a multipoint version of raster::distanceFromPoints
  • improve splitRaster (#276, #284)
  • new function mergeRaster (#282, #283)
  • changed and performance boost to randomPolygons (uses spread internally now)
  • minor performance enhancements
  • many more and improved unit tests

version 1.1.4

  • fix OSX CRAN check errors caused by inconsistent use of normalizePath

version 1.1.3

  • add gtools to Imports
  • bug fix in experiment that did not allow parallel spawning on some systems and crashed with empty outputs argument* fix minor bugs in sampleModules
  • lots of documentation enhancements, esp. ?inputs and ?outputs
  • add .plotInitialTime and .saveInitialTime arguments to spades() to easily allow turning off plotting and saving
  • more robust inputs and outputs, including extension-based automated outputs, using data.frame instead of data.table allowing lists to be passed for "arguments"
  • allow vectorized n in setColors (#70), and partial n if named
  • many more unit tests (#139)
  • other bug fixes

version 1.1.2

  • fix issues associated with upcoming dplyr updates
  • performance enhancements: much faster simulation execution
  • Plot accepts color column in SpatialPointDataFrame objects
  • add col arg to Plot (mimicks cols)
  • add experiment function, a wrapper around spades for running multiple simulations (#265)
  • add shine function, with simList signature (#261)
  • add copy function, which does a deep copy of a simList object
  • add RColorBrewer to Imports
  • allow Plot colours to be set in the Plot call using cols argument
  • allow Plot colours to be set in the Plot call using RColorBrewer palettes
  • fix bug when plotting certain real-numbered rasters
  • fix bug in Plot legends
  • fix bug in assigning vectors as default module param values
  • fix bug that prevented printing simulation times
  • fix bug in event list sorting by eventPriority
  • new slot in simList object: current, to store the current event
  • new accessors current and current<- to get and set the current event
  • defineParameter now coerces the default value to match the type class
  • export objectNames() for external use
  • outputPath updates output(sim)$file file paths, in addition to just paths(sim)$outputPath
  • other bug fixes

version 1.1.1

  • require archivist version 2.0 or greater
  • improved moduleCoverage testing and template (PR257)
  • correct legends from rasters so that is.factor(raster) is TRUE
  • user defined time units can be used in module metadata "timeunit".
  • add module timeunits to simList show method (#260)

version 1.1.0

  • require R version 3.2.2 or higher
  • remove downloader from Imports (#203)
  • add covr to Suggests and lazyeval to Imports
  • require DiagrammeR version 0.8.2 or higher which fixes mermaid/knitr/pandoc error (
  • add data source info module metadata (#205)
  • new function downloadData to download module data (with #205)
  • new function checksums to verify MD5 hashes of data files (with #205)
  • warn instead of error when using e.g., newModule with Rstudio on Windows (#209)
  • more control of caching behaviour: added cachePath to paths slot (#227)
  • only download data if file doesn't exist or checksum mismatch (#229)
  • allow multiple checksums per file in checksum (#230)
  • fix error caused by coercing NA to arbitrary class for which no suitable NA type exists (#231)
  • use warnings instead of errors for missing modules metadata (#233)
  • add event priorities (#236)
  • enhanced functionality of spread() (#237)
  • add unit tests and coverage to newModule (PR242, PR245)
  • objects passed to simInit can be named differently from their objects (#247)
  • downloadModule and downloadData now also download children modules/data
  • new function divergentColors to generate divergent colour palettes for legends
  • improve efficiency of loadPackages
  • change .spatialObjects class to spatialObjects and export
  • add .Rdata and .rds files to automatic loading.
  • warn user if SpaDES package version doesn't match module version
  • allow more signatures in simInit (modules can be character)
  • other bug fixes

version 1.0.3

  • fully fix inputs data.frame construction in simInit (#225)

version 1.0.2

  • update maintainer's and authors' email addresses
  • fix bug in .parseModule (#215)
  • improve dependency graph & module diagram (#216)
  • simList accessors now work with .simList superclass (#217)
  • fix %>% bug in demo (#218)
  • use rmarkdown::render for vignettes (with #219)
  • improve documentation (including #219)
  • reduce sizes of built vignettes (#222)
  • add slot documentation to module metadata (see ?defineModule) (#224)
  • fix inputs data.frame construction in simInit (#225)
  • various other bug fixes

version 1.0.1

  • no longer attach the simulation environment (#212)
  • improve documentation
  • bug fixes

version 1.0.0

  • no longer rely on side effects to update objects in global environment; instead uses simulation environments (#185) (not backwards compatible!)

  • sample modules rewritten to use simulation enviroments (#185) (not backwards compatible!).

  • redefined simList class:

    • new superclass .simList contains all previous simList slots except .envir
    • class simList extends .simList by adding slot .envir
    • new class simList_ extends .simList by adding slot .list
    • simList_ can be used internally to save a simList object, because saving lists of objects to file is more reliable that saving environments.
  • fastshp can be installed from Rforge as a CRAN-like repository (instead of relying on devtools::install_github)

  • software requirements changed: depends R (>=3.2.0)

  • moved data.table, grid, raster, and sp from Depends to Imports (#207).

  • add archivist, ff, ffbase to Imports; add lubridate to Imports (with #151)

  • removed magrittr from Imports (%>% is now exported by igraph)

  • most external methods/classes imported using importFrom; except methods, graphics, igraph, and utils (because of methods/classes which are not exported) (#201)

  • simulations now use timeunit (instead of timestep) specified in metadata (#151)

  • defineModule requires timeunit to be a character string instead of numeric (with #151)

  • simulation checkpointing fixed (#191, #130)

  • ls and ls.str can now be used with simList objects to list objects in the simulation environment

  • objs returns a list containing all the objects in the simulation enviroment

  • new function splitRaster to divide RasterLayer into several tiles

  • new function normPath (extracted from checkPath) to more strictly normalize filepaths without checking that they exist.

  • new function classFilter to filter list of objects by their type

  • new function packages to get all packages required by a simulation

  • new function rndstr to generate random strings

  • new function append_attr to append list items and keep their attributes

  • improved loadPackages

  • improved .objectNames

  • defineParameter now accepts min, max, and description values (#172; #175)

  • defineModule better handles NA values (#138)

  • various Plot improvements.

  • new plotting funcions to produce overview diagrams of simulations (#181; #184):

    • eventDiagram shows Gantt chart of event sequences
    • moduleDiagram shows igraph network diagram of dependencies
    • objectDiagram shows sequence diagram of object dependencies between modules
  • improved simList show and debug methods (#57; #73)

  • improvements to loadFiles:

    • use data.table
    • allow package::function notation in load (#174)
    • bug fixes
  • added "metamodules" which specify module groups (#176)

  • improved test coverage (see #139)

  • all functions imported explicity (@importFrom). 3 entire packages imported: methods, graphics, igraph (because of classes which are not exported from igraph) (#201)

  • removed package dependencies on raster, sp, data.table, grid. Use importFrom instead (#207).

  • improved documentation and vignettes

  • added cache mechanism to hash function calls to spades (#206)

  • fixed progress bar bug (#147)

  • prepend copyright info to LICENSE and README (with #140)

  • various other bug fixes

version 0.6.2

This is a minor release update to satisfy CRAN submission requirements.

  • bug fix when saving files

version 0.6.1

  • added the Queen as copyright holder (#140)

  • explicitly use GPL-3 (previously used GPL) (#140)

  • modules now require metadata; module code without it will break!

    • new module dependency checking and metadata structure (#126)
    • explicit declaration of parameters, and object (data) dependencies
    • deprecated use of reloadModuleLater
  • new module directory structure (#125):

      |_ moduleName.R    # the actual module code file, incl. module metadata
      |_ moduleName.Rmd  # longform documentation and usage info, etc.
      |_ citation.bib    # properly formatted bibtex citation for the module
      |_ LICENSE         # license file describing the allowed usage etc. of the module
      |_ README          # incl. module metadata in addition to version change info, etc.
  • updated package dependencies:

    • added downloader, dplyr, fpCompare, httr, magrittr, stringr to Imports
  • updated vignettes and documentation improvements

  • transfered project to PredictiveEcology/SpaDES from achubaty/SpaDES.

  • overhaul to Plot function:

    • no longer needs *Named objects.

    • now handles SpatialPolygons objects much faster than default plot:

      • Uses package fastshp.
        • The suggested package fastshp can be installed with:

    • numerous other Plot improvements

  • deprecated all *Named functionality

    • All code will break that uses *Named objects
  • new function, clearPlot can be used to clean all hidden metadata about a plot

  • new function, randomPolygons, will create random raster maps (not vector maps) of polygons

  • numerous bugfixes

version 0.4.0

  • second public ("beta") release
  • more improvements to Plot function, including dramatically faster for files on disk
  • added second "Model" that adds and integrates 3 sample modules, Fire, Succession and Aging
  • added Plotting vignette
  • bugfixes

version 0.3.1

  • first public ("beta") release
  • reworked plotting and visualization (it's faster, more reliable)
  • added additional parameter checks and improved debugging
  • new and improved documentation:
    • two new vignettes (introduction to SpaDES and how modules work)
    • new demo highlighting visualization components
    • more complete code documentation
  • numerous bug fixes

version 0.2

  • renamed package to SpaDES

version 0.1

  • first working alpha version
  • lots of "wishlist" items still to be implemented

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.0.0 by Alex M Chubaty, 4 months ago,

Report a bug at

Browse source code at

Authors: Alex M Chubaty [aut, cre], Eliot J B McIntire [aut], Yong Luo [ctb], Steve Cumming [ctb], Her Majesty the Queen in Right of Canada, as represented by the Minister of Natural Resources Canada [cph]

Documentation:   PDF Manual  

GPL-3 license

Imports methods, quickPlot, reproducible, SpaDES.addins, SpaDES.core,, utils

Suggests archivist, igraph, knitr, raster, rmarkdown, testthat

See at CRAN