## ----setup, include=FALSE----------------------------------------------------- # Packages used in this vignette vignette_pkgs <- c("DiagrammeR", "NLMR", "SpaDES.tools", "knitr", "CircStats") # Check availability without attaching hasSuggests <- function(pkgs) all(vapply(pkgs, requireNamespace, quietly = TRUE, FUN.VALUE = logical(1))) # CRAN sets NOT_CRAN = "false"; devtools sets it to "true" locally not_cran <- identical(Sys.getenv("NOT_CRAN"), "true") evalTRUE <- not_cran && hasSuggests(vignette_pkgs) # Evaluate chunks only if NOT_CRAN and all vignette packages are available knitr::opts_chunk$set( eval = evalTRUE, message = FALSE, warning = FALSE ) options( spades.moduleCodeChecks = FALSE, spades.useRequire = FALSE ) ## ----module-metadata, echo=FALSE, results="asis"------------------------------ # cat(c( # "```", # "## sample module metadata for the default `caribouMovement` module", # readLines(system.file("sampleModules", "caribouMovement", "caribouMovement.R", package = "SpaDES.core"))[10:45], # "```" # ), sep = "\n") ## ----passing-params, echo=TRUE------------------------------------------------ # library(SpaDES.core) # # outputDir <- file.path(tempdir(), "simOutputs") # times <- list(start = 0.0, end = 5.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 = getSampleModules(tempdir()), # outputPath = outputDir) # # mySim <- simInit(times = times, params = parameters, modules = modules, # objects = objects, paths = paths) ## ----accessing-params, eval=FALSE, echo=TRUE---------------------------------- # ## Access parameters # P(mySim) # shows all parameters # P(mySim, module = "caribouMovement") # only parameters in caribouMovement module # 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(mySim)$N # Only one parameter if used within a module ## ----event-types, echo=FALSE, results="asis"---------------------------------- # cat(c( # "```", # "## sample event type definitions for the default `caribouMovement` module", # readLines(system.file("sampleModules", "caribouMovement", "caribouMovement.R", package = "SpaDES.core"))[61:116], # "```" # ), sep = "\n") ## ----event-functions, echo=FALSE, results="asis"------------------------------ # cat(c( # "```", # "## sample Init event function from the default `caribouMovement` module", # readLines(system.file("sampleModules", "caribouMovement", "caribouMovement.R", package = "SpaDES.core"))[121:143], # "```" # ), sep = "\n") ## ----sim-eventDiagram, eval=evalTRUE, echo=FALSE, message=FALSE, warning=FALSE---- # # 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() # # # run just 1 year for vignette # mySim <- simInitAndSpades( # times = list(start = 0.0, end = 1.0, timeunit = "year"), # params = parameters, # modules = list("randomLandscapes", "fireSpread", "caribouMovement"), # objects = list(), # paths = list(modulePath = getSampleModules(tempdir())) # ) # dev.off() # unlink(normalizePath(ftmp)) ## ----eventDiagram, echo=FALSE, fig.height=10, fig.width=7--------------------- # # overview of the events in the simulation # # Needs DiagrammeR package # 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, echo=TRUE, message=FALSE, fig.width=7------------ # ## NOTE: Suggested packages SpaDES.tools and NLMR packages must be installed # #install.packages("SpaDES.taols") # #install.packages("NLMR", repos = "https://predictiveecology.r-universe.dev/") # # library(SpaDES.core) # # times <- list(start = 0.0, end = 1.0) # parameters <- list( # .globals = list(stackName = "landscape", burnStats = "nPixelsBurned") # ) # modules <- list("SpaDES_sampleModules") # paths <- list(modulePath = getSampleModules(tempdir())) # # 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, message=FALSE------------------------------------ # # initialize a new simulation, setting the checkpoint interval and filename. # times <- list(start = 0, end = 5) # parameters <- list( # .globals = list(stackName = "landscape"), # .checkpoint = list(interval = 2, file = "chkpnt.RData") # ) # modules <- list("randomLandscapes", "caribouMovement") # paths <- list( # modulePath = getSampleModules(tempdir()) # ) # # 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, message=FALSE--------------------------------------- # # initialize a new simulation, setting the progress parameters # mySim <- simInit(times = list(start = 0.0, end = 10.0), # params = list(.globals = list(stackName = "landscape"), # .progress = list(type = "text", interval = 1)), # modules = list("randomLandscapes"), # paths = list(modulePath = getSampleModules(tempdir()))) # # # retrieve the checkpoint params from the simulation object # progressType(mySim) # progressInterval(mySim) ## ----load-save, echo=TRUE, message=FALSE-------------------------------------- # # initialize a new simulation, setting the load and save parameters # outputDir <- file.path(tempdir(), "simOutputs") # mySim <- simInit(times = list(start = 0, end = 5), # params = list( # .globals = list(stackName = "landscape"), # randomLandscapes = list( # .saveInitialTime = 0, .saveInterval = 2, # .saveObjects = c("landscape"), # .savePath = file.path(outputDir, "randomLandscapes")) # ), # modules = list("randomLandscapes"), # paths = list(modulePath = getSampleModules(tempdir()), # 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 <- tempfile(pattern = "spades_vignetteOutputs", fileext = ".pdf") # pdf(ftmp) # clearPlot() # mySim2 <- spades(mySim) # # # More sophisticated, passing arguments to outputs() # outputs(mySim) <- data.frame( # objectName = "landscape", fun = "writeRaster", package = "terra", # saveTime = c(3, 6), arguments = I(lapply(c(3, 6), function(x) { # list(datatype = "FLT4S", filetype = "GTiff", overwrite = TRUE) # }))) # mySim2 <- spades(mySim) # dev.off() # unlink(normalizePath(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, end = 5), # params = list( # .globals = list(stackName = "landscape"), # randomLandscapes = list(.plotInitialTime = 0, .plotInterval = 1) # ), # modules = list("randomLandscapes"), # paths = list(modulePath = getSampleModules(tempdir())) # ) # # # 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(getSampleModules(tempdir()), "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 = getSampleModules(tempdir()), # 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, echo=FALSE------------------------------------------------------ # unlink(outputDir, recursive = TRUE)