## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(echo = TRUE)
options(spades.moduleCodeChecks = FALSE)

## ----module-metadata, eval=FALSE, echo=TRUE-----------------------------------
#  ## sample module metadata for the default `randomLandscapes` module
#  ## NOTE: long lines have been truncated
#  defineModule(sim, list(
#    name = "randomLandscapes",
#    description = "Generate RasterStack of random maps representative of a forest landsc...",
#    keywords = c("random map", "random landscape"),
#    authors = c(person(c("Alex", "M"), "Chubaty",
#                       email = "alexander.chubaty@canada.ca",
#                       role = c("aut", "cre")),
#                person(c("Eliot", "J", "B"), "McIntire",
#                       email = "eliot.mcintire@canada.ca",
#                       role = c("aut", "cre"))),
#    version = numeric_version("0.2.0"),
#    spatialExtent = raster::extent(rep(NA_real_, 4)),
#    timeframe = as.POSIXlt(c(NA, NA)),
#    timeunit = NA_real_,
#    citation = list(),
#    reqdPkgs = list("raster", "RColorBrewer", "SpaDES.tools"),
#    parameters = rbind(
#      defineParameter("stackName", "character", "randomLandscape", NA, NA, "..."),
#      defineParameter("nx", "numeric", 100L, NA, NA, "size of map (number ..."),
#      defineParameter("ny", "numeric", 100L, NA, NA, "size of map (number ..."),
#      defineParameter("inRAM", "logical", FALSE, NA, NA, "should the raster ..."),
#      defineParameter(".plotInitialTime", "numeric", 0, NA, NA, "time to ..."),
#      defineParameter(".plotInterval", "numeric", 1, NA, NA, "time interval ..."),
#      defineParameter(".saveInitialTime", "numeric", NA_real_, NA, NA, "time ..."),
#      defineParameter(".saveInterval", "numeric", NA_real_, NA, NA, "time ...")
#    ),
#    inputObjects = bind_rows(
#      expectsInput(objectName = NA_character_, objectClass = NA_character_,
#                   desc = NA_character_, sourceURL = NA_character_, other = NA_character_)
#    ),
#    outputObjects = bind_rows(
#      createsOutput(objectName = globals(sim)$stackName, objectClass = "RasterStack",
#                    desc = NA_character_, other = NA_character_)
#    )
#  ))

## ----passing-params, eval=FALSE, echo=TRUE------------------------------------
#  library(SpaDES.core)
#  
#  outputDir <- file.path(tempdir(), "simOutputs")
#  times <- list(start = 0.0, end = 20.0)
#  parameters <- list(
#    .globals = list(stackName = "landscape", burnStats = "nPixelsBurned"),
#    .progress = list(NA),
#    randomLandscapes = list(nx = 100L, ny = 100L, inRAM = TRUE),
#    fireSpread = list(
#      nFires = 10L, spreadprob = 0.225, its = 1e6, persistprob = 0,
#      returnInterval = 10, startTime = 0,
#      .plotInitialTime = 0, .plotInterval = 10
#    ),
#    caribouMovement = list(
#      N = 100L, moveInterval = 1, torus = TRUE,
#      .plotInitialTime = 1, .plotInterval = 1
#    )
#  )
#  modules <- list("randomLandscapes", "fireSpread", "caribouMovement")
#  objects <- list()
#  paths <- list(modulePath = system.file("sampleModules", package = "SpaDES.core"),
#                outputPath = outputDir)
#  
#  mySim <- simInit(times = times, params = parameters, modules = modules,
#                   objects = objects, paths = paths)
#  
#  # Access parameters
#  params(mySim)               # shows all parameters
#  P(mySim)                    # same, but more concise
#  P(mySim, "caribouMovement") # only parameters in caribouMovement
#  P(mySim)$caribouMovement    # same
#  P(mySim)$caribouMovement$N  # Only one parameter
#  
#  # If used within the module source code, then module name can be omitted:
#  # This will return NULL here, but will return the actual value if used
#  # in a module
#  P(sim)$N  # Only one parameter

## ----event-types, echo=TRUE, eval=FALSE---------------------------------------
#  ## sample event type definitions from the default `randomLandscapes` module
#  doEvent.randomLandscapes <- function(sim, eventTime, eventType, debug = FALSE) {
#    if (eventType == "init") {
#      # do stuff for this event
#      sim <- randomLandscapesInit(sim)
#  
#      # schedule the next events
#      sim <- scheduleEvent(sim, params(sim)$randomLandscapes$.plotInitialTime,
#                           "randomLandscapes", "plot")
#      sim <- scheduleEvent(sim, params(sim)$randomLandscapes$.saveInitialTime,
#                           "randomLandscapes", "save")
#  
#    } else if (eventType=="plot") {
#      # do stuff for this event
#      Plot(sim[[globals(sim)$stackName]])
#  
#      # schedule the next event
#      sim <- scheduleEvent(sim, time(sim) +
#                             params(sim)$randomLandscapes$.plotInterval,
#                           "randomLandscapes", "plot")
#    } else if (eventType == "save") {
#      # do stuff for this event
#      saveFiles(sim)
#  
#      # schedule the next event
#      sim <- scheduleEvent(sim, time(sim) +
#                             params(sim)$randomLandscapes$.saveInterval,
#                           "randomLandscapes", "save")
#  
#    } else {
#      warning(paste("Undefined event type: \'",
#                    events(sim)[1, "eventType", with = FALSE],
#                    "\' in module \'",
#                    events(sim)[1, "moduleName", with = FALSE],
#                    "\'", sep = ""))
#    }
#    return(invisible(sim))
#  }

## ----event-functions, echo=TRUE, eval=FALSE-----------------------------------
#  ## sample event functions from the default `randomLandscapes` module
#  library(raster)
#  if (require(SpaDES.tools)) {
#  
#    randomLandscapesInit <- function(sim) {
#      if (is.null(params(sim)$randomLandscapes$inRAM)) {
#        inMemory <- FALSE
#      } else {
#        inMemory <- params(sim)$randomLandscapes$inRAM
#      }
#      # Give dimensions of dummy raster
#      nx <- params(sim)$randomLandscapes$nx
#      ny <- params(sim)$randomLandscapes$ny
#      r <- raster(nrows = ny, ncols = nx, xmn = -nx/2, xmx = nx/2,
#                  ymn = -ny/2, ymx = ny/2)
#      speedup <- max(1, nx/5e2)
#      # Make dummy maps for testing of models
#      DEM <- gaussMap(template, scale = 300, var = 0.03,
#                      speedup = speedup, inMemory = inMemory)
#      DEM[] <- round(getValues(DEM), 1) * 1000
#      forestAge <- gaussMap(template, scale = 10, var = 0.1,
#                            speedup = speedup, inMemory = inMemory)
#      forestAge[] <- round(getValues(forestAge), 1) * 20
#      percentPine <- gaussMap(template, scale = 50, var = 1,
#                              speedup = speedup, inMemory = inMemory)
#      percentPine[] <- round(getValues(percentPine), 1)
#  
#      # Scale them as needed
#      forestAge <- forestAge / maxValue(forestAge) * 100
#      percentPine <- percentPine / maxValue(percentPine) * 100
#  
#      # Make layers that are derived from other layers
#      habitatQuality <- (DEM + 10 + (forestAge + 2.5) * 10) / 100
#      habitatQuality <- habitatQuality / maxValue(habitatQuality)
#  
#      # Stack them into a single stack and assign to sim envir
#      mapStack <- stack(DEM, forestAge, habitatQuality, percentPine)
#      names(mapStack) <- c("DEM", "forestAge", "habitatQuality", "percentPine")
#      setColors(mapStack) <- list(DEM = brewer.pal(9, "YlOrBr"),
#                                  forestAge = brewer.pal(9, "BuGn"),
#                                  habitatQuality = brewer.pal(8, "Spectral"),
#                                  percentPine = brewer.pal(9, "Greens"))
#      sim[[globals(sim)$stackName]] <- mapStack
#      return(invisible(sim))
#    }
#  }

## ----sim-eventDiagram, eval=TRUE, echo=FALSE, message=FALSE, warning=FALSE----
library(igraph) # for %>%
library(SpaDES.core)
if (require(SpaDES.tools) && require(RandomFields)) {
  parameters <- list(
    .globals = list(stackName = "landscape", burnStats = "nPixelsBurned"),
    .progress = list(NA),
    randomLandscapes = list(nx = 100L, ny = 100L, inRAM = TRUE),
    fireSpread = list(nFires = 10L, spreadprob = 0.225, its = 1e6,
                      persistprob = 0, returnInterval = 1, startTime = 0,
                      .plotInitialTime = 0, .plotInterval = 10),
    caribouMovement = list(N = 100L, moveInterval = 1, torus = TRUE,
                           .plotInitialTime = 1, .plotInterval = 1)
  )
  
  ftmp <- tempfile("spades_vignetteOutputs", fileext = ".pdf")
  pdf(ftmp)
  clearPlot()
  mySim <- simInit(
    times = list(start = 0.0, end = 2.0, timeunit = "year"),
    params = parameters,
    modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
    objects = list(),
    paths = list(modulePath = system.file("sampleModules", package = "SpaDES.core"))
    ) %>% 
    spades()
  dev.off()
  unlink(ftmp)
}

## ----eventDiagram, echo=FALSE, eval=TRUE, fig.height=10, fig.width=7----------
if (require(SpaDES.tools) && require(RandomFields))  {
  # overview of the events in the simulation
  eventDiagram(mySim, "0000-06-01", n = 200, width = 720)
}

## ----checksums, eval=FALSE----------------------------------------------------
#  ## 1. specify your module here
#  moduleName <- "my_module"
#  
#  ## 2. use a temp dir to ensure all modules get fresh copies of the data
#  tmpdir <- file.path(tempdir(), "SpaDES_modules")
#  
#  ## 3. download your module's data to the temp dir
#  downloadData(moduleName, tmpdir)
#  
#  ## 4. initialize a dummy simulation to ensure any 'data prep' steps in the .inputObjects section are run
#  simInit(modules = moduleName)
#  
#  ## 5. recalculate your checksums and overwrite the file
#  checksums(moduleName, tmpdir, write = TRUE)
#  
#  ## 6. copy the new checksums file to your working module directory (the one not in the temp dir)
#  file.copy(from = file.path(tmpdir, moduleName, 'data', 'CHECKSUMS.txt'),
#            to = file.path('path/to/my/moduleDir', moduleName, 'data', 'CHECKSUMS.txt'),
#            overwrite = TRUE)

## ----module-object-diagrams, eval=TRUE, echo=TRUE, message=FALSE, fig.width=7----
library(SpaDES.core)

times <- list(start = 0.0, end = 20)
parameters <- list(
  .globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
)
modules <- list("SpaDES_sampleModules")
paths <- list(modulePath = system.file("sampleModules", package = "SpaDES.core"))

mySim <- simInit(times = times, params = parameters, modules = modules, paths = paths)

## examine simulation module (object) dependencies
depsEdgeList(mySim, FALSE)      # all object dependency relationships
clearPlot()
moduleDiagram(mySim)            # simplified visual representation of modules

clearPlot()
moduleDiagram(mySim, showParents = TRUE) # similar, but showing parent module grouping

# detailed visual representation of objects
objectDiagram(mySim, width = 720)

## ----checkpoints, echo=TRUE, eval=TRUE, message=FALSE-------------------------

# initialize a new simulation, setting the checkpoint interval and filename.
times <- list(start = 0, end = 30)
parameters <- list(
  .globals = list(stackName = "landscape"),
  .checkpoint = list(interval = 10, file = "chkpnt.RData")
)
modules <- list("randomLandscapes", "caribouMovement")
paths <- list(
  modulePath = system.file("sampleModules", package = "SpaDES.core")
)

mySim <- simInit(times = times, params = parameters, modules = modules, paths = paths)

# retrieve the checkpoint params from the simulation object
checkpointFile(mySim)
checkpointInterval(mySim)

## ----progress, echo=TRUE, eval=TRUE, message=FALSE----------------------------
# initialize a new simulation, setting the progress parameters
mySim <- simInit(times = list(start = 0.0, end = 100.0),
                 params = list(.globals = list(stackName = "landscape"),
                               .progress = list(type = "text", interval = 10)),
                 modules = list("randomLandscapes"),
                 paths = list(modulePath = system.file("sampleModules", package = "SpaDES.core")))

# retrieve the checkpoint params from the simulation object
progressType(mySim)
progressInterval(mySim)

## ----load-save, echo=TRUE, eval=TRUE, message=FALSE---------------------------
# initialize a new simulation, setting the load and save parameters
library(data.table)

outputDir <- file.path(tempdir(), "simOutputs")
mySim <- simInit(times = list(start = 0.0, end = 10),
                 params = list(
                   .globals = list(stackName = "landscape"),
                   randomLandscapes = list(
                     .saveInitialTime = 0, .saveInterval = 10,
                     .saveObjects = c("landscape"),
                     .savePath = file.path(outputDir, "randomLandscapes"))
                   ),
                 modules = list("randomLandscapes"),
                 paths = list(modulePath = system.file("sampleModules", package = "SpaDES.core"),
                              outputPath = outputDir),
                 outputs = data.frame(objectName = "landscape")
)

# retrieve the load and save params from the simulation object
inputs(mySim)    # shows all files and objects that are "inputs"
outputs(mySim)   # shows all files and objects that are "outputs"

params(mySim)$randomLandscapes$.saveInitialTime
params(mySim)$randomLandscapes$.saveInterval
params(mySim)$randomLandscapes$.saveObjects
params(mySim)$randomLandscapes$.savePath
ftmp <- file.path(tempdir(), "spades_vignetteOutputs")
pdf(ftmp)
clearPlot()
mySim2 <- spades(mySim)

# More sophisticated, passing arguments to outputs()
outputs(mySim) <- data.frame(
  objectName = "landscape", fun = "writeRaster", package = "raster",
  saveTime = c(3,6), arguments = I(lapply(c(3,6), function(x) {
    list(dataType = "FLT4S", format = "raster", overwrite = TRUE)
})))
mySim2 <- spades(mySim)
dev.off()
unlink(ftmp)

## ----save-events, echo=TRUE, eval=FALSE, message=FALSE------------------------
#  ### WITHIN A MODULE:
#  
#  # schedule a recurring save event
#  nextSave <- time(mySim) + params(mySim)$randomLandscapes$.saveInterval
#  sim <- scheduleEvent(mySim, nextSave, "randomLandscapes", "save")

## ----plotting, echo=TRUE, eval=FALSE, message=FALSE---------------------------
#  # initialize a new simulation, setting the load and save parameters
#  mySim <- simInit(times = list(start = 0.0, end = 100),
#                   params = list(
#                     .globals = list(stackName = "landscape"),
#                     randomLandscapes = list(.plotInitialTime = 0, .plotInterval = 1)
#                   ),
#                   modules = list("randomLandscapes"),
#                   paths = list(modulePath = system.file("sampleModules", package = "SpaDES.core"))
#  )
#  
#  # retrieve the plotting params from the simulation object
#  params(mySim)$randomLandscapes$.plotInitialTime
#  params(mySim)$randomLandscapes$.plotInterval

## ----plot-events, echo=TRUE, eval=FALSE, message=FALSE------------------------
#  ### WITHIN A MODULE:
#  
#  # schedule a recurring plot event
#  nextPlot <- time(mySim) + params(mySim)$randomLandscapes$.plotInterval
#  mySim <- scheduleEvent(mySim, nextPlot, "randomLandscapes", "save")

## ----caribouMovement, echo=TRUE, eval=FALSE-----------------------------------
#  openModules(system.file("sampleModules", package = "SpaDES.core"), "moduleName")

## ----download-module, echo=TRUE, eval=FALSE-----------------------------------
#  downloadModule("moduleName")

## ----create-new-module, eval=FALSE, echo=TRUE, message=FALSE------------------
#  # create a new module called "randomLandscape" in the "custom-modules" subdirectory
#  # and open the resulting file immediately for editing.
#  newModule(name = "randomLandscapes", path = "custom-modules", open = TRUE)

## ----module-group-init, eval=FALSE--------------------------------------------
#  library(DiagrammeR)
#  library(SpaDES.core)
#  
#  outputDir <- file.path(tempdir(), "simOutputs")
#  times <- list(start = 0.0, end = 20.0)
#  parameters <- list(
#    .globals = list(stackName = "landscape", burnStats = "nPixelsBurned"),
#    .progress = list(NA),
#    randomLandscapes = list(nx = 100L, ny = 100L, inRAM = TRUE),
#    fireSpread = list(
#      nFires = 10L, spreadprob = 0.225, its = 1e6, persistprob = 0,
#      returnInterval = 10, startTime = 0,
#      .plotInitialTime = 0, .plotInterval = 10
#    ),
#    caribouMovement = list(
#      N = 100L, moveInterval = 1, torus = TRUE,
#      .plotInitialTime = 1, .plotInterval = 1
#    )
#  )
#  modules <- list("SpaDES_sampleModules")
#  objects <- list()
#  paths <- list(
#    modulePath = system.file("sampleModules", package = "SpaDES.core"),
#    outputPath = outputDir
#  )
#  
#  mySim <- simInit(times = times, params = parameters, modules = modules,
#                   objects = objects, paths = paths)
#  
#  modules(mySim) # note the child modules are initialized

## ----module-group-dl, eval=FALSE----------------------------------------------
#  downloadModule("SpaDES_sampleModules")

## ----cleanup, eval=TRUE, echo=FALSE-------------------------------------------
unlink(outputDir, recursive = TRUE)

