Save objects using .saveObjects in params slot of simInit

Source: R/save.R

In the simInit() call, a parameter called .saveObjects can be provided in each module. This must be a character string vector of all object names to save. These objects will then be saved whenever a call to saveFiles is made.

saveFiles(sim)

Arguments

sim

A simList simulation object.

Value

(invisibly) the modified sim object. invoked for side effect of saving the simulation to file.

Details

The file names will be equal to the object name plus time(sim) is appended at the end. The files are saved as .rds files, meaning, only one object gets saved per file.

For objects saved using this function, the module developer must create save events that schedule a call to saveFiles.

If this function is used outside of a module, it will save all files in the outputs(sim) that are scheduled to be saved at the current time in the simList.

There are several ways to save objects using SpaDES.

Note

It is not possible to schedule separate saving events for each object that is listed in the .saveObjects.

Model-level saving

Using the outputs slot in the simInit() call. See example in simInit(). This can be convenient because it gives overall control of many modules at a time, and it gets automatically scheduled during the simInit() call.

Module-level saving

Using the saveFiles function inside a module. This must be accompanied by a .saveObjects vector or list element in the params slot in the simList(). Usually a module developer will create this method for future users of their module.

Custom saving

A module developer can save any object at any time inside their module, using standard R functions for saving R objects (e.g., save or saveRDS). This is the least modular approach, as it will happen whether a module user wants it or not.

Author

Eliot McIntire and Alex Chubaty

Examples

# \donttest{
if (requireNamespace("SpaDES.tools", quietly = TRUE) &&
requireNamespace("NLMR", quietly = TRUE)) {
## This will save the "caribou" object at the save interval of 1 unit of time
## in the outputPath location
  outputPath <- file.path(tempdir(), "test_save")
  times <- list(start = 0, end = 1, "month")
  parameters <- list(
    .globals = list(stackName = "landscape"),
    caribouMovement = list(
      .saveObjects = "caribou",
      .saveInitialTime = 1, .saveInterval = 1,
      .plots = NA
    ),
    randomLandscapes = list(.plots = NA, nx = 20, ny = 20))

  modules <- list("randomLandscapes", "caribouMovement")
  paths <- list(
    modulePath = getSampleModules(tempdir()),
    outputPath = outputPath
  )
  opts <- options("spades.moduleCodeChecks" = FALSE) # not necessary for example
  mySim <- simInit(times = times, params = parameters, modules = modules,
                   paths = paths)

  # The caribou module has a saveFiles(sim) call, so it will save caribou
  spades(mySim)
  dir(outputPath)

  # remove the files
  file.remove(dir(outputPath, full.names = TRUE))

  ## save multiple outputs
  parameters <- list(
    .globals = list(stackName = "landscape"),
    caribouMovement = list(
      .saveObjects = c("caribou", "habitatQuality"),
      .saveInitialTime = 1, .saveInterval = 1,
      .plots = NA
    ),
    randomLandscapes = list(.plots = NA, nx = 20, ny = 20))

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

  spades(mySim)
  dir(outputPath)
  # remove the files
  file.remove(dir(outputPath, full.names = TRUE))

  options(opts) # clean up

}# }
#> Setting:
#>   options(
#>     spades.outputPath = '/tmp/RtmpoLaiAE/test_save'
#>     spades.modulePath = '/tmp/RtmpoLaiAE/sampleModules'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/RtmpoLaiAE/SpaDES/scratch/raster'
#>     reproducible.cachePath = '/tmp/RtmpoLaiAE/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpoLaiAE/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpoLaiAE/test_save'
#>     spades.modulePath = '/tmp/RtmpoLaiAE/sampleModules'
#>     spades.scratchPath = '/tmp/RtmpoLaiAE/SpaDES/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/RtmpoLaiAE/SpaDES/scratch/terra'
#> Apr25 18:01:17 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Apr25 18:01:17 simInit The following .globals were used:
#> Apr25 18:01:17 simInit Key: <global, module>
#> Apr25 18:01:17 simInit              module    global
#> Apr25 18:01:17 simInit              <char>    <char>
#> Apr25 18:01:17 simInit 1:  caribouMovement stackName
#> Apr25 18:01:17 simInit 2: randomLandscapes stackName
#> Elpsed time for simInit: 0.09969759 secs
#> Apr25 18:01:17 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Apr25 18:01:17 chckpn:init total elpsd: 0.1 secs | 0 checkpoint init 0
#> Apr25 18:01:17 save  :init total elpsd: 0.1 secs | 0 save init 0
#> Apr25 18:01:17 prgrss:init total elpsd: 0.11 secs | 0 progress init 0
#> Apr25 18:01:17 load  :init total elpsd: 0.11 secs | 0 load init 0
#> Apr25 18:01:17 rndmLn:init total elpsd: 0.11 secs | 0 randomLandscapes init 1
#> Apr25 18:01:18 rndmLn:init New objects created:
#> Apr25 18:01:18 rndmLn:init                  <char>
#> Apr25 18:01:18 rndmLn:init 1:            landscape
#> Apr25 18:01:18 crbMvm:init total elpsd: 0.56 secs | 0 caribouMovement init 1
#> Apr25 18:01:18 crbMvm:init New objects created:
#> Apr25 18:01:18 crbMvm:init                  <char>
#> Apr25 18:01:18 crbMvm:init 1:              caribou
#> Apr25 18:01:18 rndmLn:plot total elpsd: 0.57 secs | 0 randomLandscapes plot 1
#> Apr25 18:01:18 crbMvm:plot.init total elpsd: 0.58 secs | 0 caribouMovement plot.in
#> Apr25 18:01:18 crbMvm:move total elpsd: 0.62 secs | 1 caribouMovement move 5
#> Apr25 18:01:18 crbMvm:move New objects created:
#> Apr25 18:01:18 crbMvm:move                  <char>
#> Apr25 18:01:18 crbMvm:move 1:       habitatQuality
#> Apr25 18:01:18 crbMvm:plot total elpsd: 0.66 secs | 1 caribouMovement plot 10
#> Apr25 18:01:18 crbMvm:save total elpsd: 0.66 secs | 1 caribouMovement save 11
#> simList saved in
#> SpaDES.core:::.pkgEnv$.sim
#> It will be deleted at next spades() call.
#> Setting:
#>   options(
#>     spades.outputPath = '/tmp/RtmpoLaiAE/test_save'
#>     spades.modulePath = '/tmp/RtmpoLaiAE/sampleModules'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/RtmpoLaiAE/SpaDES/scratch/raster'
#>     reproducible.cachePath = '/tmp/RtmpoLaiAE/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpoLaiAE/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpoLaiAE/test_save'
#>     spades.modulePath = '/tmp/RtmpoLaiAE/sampleModules'
#>     spades.scratchPath = '/tmp/RtmpoLaiAE/SpaDES/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/RtmpoLaiAE/SpaDES/scratch/terra'
#> Apr25 18:01:19 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Apr25 18:01:19 simInit The following .globals were used:
#> Apr25 18:01:19 simInit Key: <global, module>
#> Apr25 18:01:19 simInit              module    global
#> Apr25 18:01:19 simInit              <char>    <char>
#> Apr25 18:01:19 simInit 1:  caribouMovement stackName
#> Apr25 18:01:19 simInit 2: randomLandscapes stackName
#> Elpsed time for simInit: 0.07608056 secs
#> Apr25 18:01:19 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Apr25 18:01:19 chckpn:init total elpsd: 0.078 secs | 0 checkpoint init 0
#> Apr25 18:01:19 save  :init total elpsd: 0.08 secs | 0 save init 0
#> Apr25 18:01:19 prgrss:init total elpsd: 0.082 secs | 0 progress init 0
#> Apr25 18:01:19 load  :init total elpsd: 0.084 secs | 0 load init 0
#> Apr25 18:01:19 rndmLn:init total elpsd: 0.086 secs | 0 randomLandscapes init 
#> Apr25 18:01:20 rndmLn:init New objects created:
#> Apr25 18:01:20 rndmLn:init                  <char>
#> Apr25 18:01:20 rndmLn:init 1:            landscape
#> Apr25 18:01:20 crbMvm:init total elpsd: 0.2 secs | 0 caribouMovement init 1
#> Apr25 18:01:20 crbMvm:init New objects created:
#> Apr25 18:01:20 crbMvm:init                  <char>
#> Apr25 18:01:20 crbMvm:init 1:              caribou
#> Apr25 18:01:20 rndmLn:plot total elpsd: 0.21 secs | 0 randomLandscapes plot 1
#> Apr25 18:01:20 crbMvm:plot.init total elpsd: 0.22 secs | 0 caribouMovement plot.in
#> Apr25 18:01:20 crbMvm:move total elpsd: 0.22 secs | 1 caribouMovement move 5
#> Apr25 18:01:20 crbMvm:move New objects created:
#> Apr25 18:01:20 crbMvm:move                  <char>
#> Apr25 18:01:20 crbMvm:move 1:       habitatQuality
#> Apr25 18:01:20 crbMvm:plot total elpsd: 0.24 secs | 1 caribouMovement plot 10
#> Apr25 18:01:20 crbMvm:save total elpsd: 0.25 secs | 1 caribouMovement save 11
#> simList saved in
#> SpaDES.core:::.pkgEnv$.sim
#> It will be deleted at next spades() call.