Accessor functions for the outputs slots in a simList object.

outputs(sim)

# S4 method for simList
outputs(sim)

outputs(sim) <- value

# S4 method for simList
outputs(sim) <- value

outputArgs(sim)

# S4 method for simList
outputArgs(sim)

outputArgs(sim) <- value

# S4 method for simList
outputArgs(sim) <- value

Arguments

sim

A simList object from which to extract element(s) or in which to replace element(s).

value

The object to be stored at the slot. See Details.

Details

These functions are one of three mechanisms to add information about which output files to save.

  1. As arguments to a simInit call. Specifically, inputs or outputs. See ?simInit.

  2. With the outputs(simList) function call.

  3. By adding a function called .inputObjects inside a module, which will be executed during the simInit call. This last way is the most "modular" way to create default data sets for your model.

See below for more details.

Note

The automatic file type handling only adds the correct extension from a given fun and package. It does not do the inverse, from a given extension find the correct fun and package.

outputs function or argument in simInit

outputs accepts a data.frame similar to the inputs data.frame, but with up to 6 columns.

objectNamerequired, character string indicating the name of the object in the simList that will be saved to disk (without the sim$ prefix).
fileoptional, a character string indicating the file path to save to. The default is to concatenate objectName with the model timeunit and saveTime, separated by underscore, '_'. So a default filename would be "Fires_year1.rds".
funoptional, a character string indicating the function to use to save that file. The default is saveRDS()
packageoptional character string indicating the package in which to find the fun);
saveTimeoptional numeric, indicating when in simulation time the file should be saved. The default is the lowest priority at end(sim), i.e., at the very end.
argumentsis a list of lists of named arguments, one list for each fun. For example, if fun = "write.csv", arguments = list(row.names = TRUE) will pass the argument row.names = TRUE to write.csv If there is only one list, then it is assumed to apply to all files and will be recycled as per normal R rules of recycling for each fun.

See the modules vignette for more details (browseVignettes("SpaDES.core")).

Examples

#######################
# outputs
#######################

library(igraph) # for %>%
tmpdir <- file.path(tempdir(), "outputs") %>% checkPath(create = TRUE)
tmpFile <- file.path(tmpdir, "temp.rds")
tempObj <- 1:10

# Can add data.frame of outputs directly into simInit call
sim <- simInit(objects = c("tempObj"),
               outputs = data.frame(objectName = "tempObj"),
               paths = list(outputPath = tmpdir))
#> Setting:
#>   options(
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/RtmpAzfvD1/SpaDES/scratch/raster'
#>     reproducible.cachePath = '/tmp/RtmpAzfvD1/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpAzfvD1/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>     spades.modulePath = '/tmp/RtmpAzfvD1/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmpAzfvD1/SpaDES/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/RtmpAzfvD1/SpaDES/scratch/terra'
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
outputs(sim) # To see what will be saved, when, what filename
#>   objectName                                       file     fun package
#> 1    tempObj /tmp/RtmpAzfvD1/outputs/tempObj_year10.rds saveRDS    base
#>   saveTime saved arguments
#> 1       10    NA        NA
sim <- spades(sim)
#> Aug19 19:59:30       Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Aug19 19:59:30 chckpn  total elpsd: 0.00096 secs | 0 checkpoint init 0
#> Aug19 19:59:30 save    total elpsd: 0.0026 secs | 0 save init 0
#> Aug19 19:59:30 prgrss  total elpsd: 0.0044 secs | 0 progress init 0
#> Aug19 19:59:30 load    total elpsd: 0.0059 secs | 0 load init 0
#> Aug19 19:59:30 save    total elpsd: 0.0073 secs | 10 save spades 10
#> simList saved in
#>  SpaDES.core:::.pkgEnv$.sim 
#> It will be deleted at next spades() call.
outputs(sim) # To see that it was saved, when, what filename
#>   objectName                                       file     fun package
#> 1    tempObj /tmp/RtmpAzfvD1/outputs/tempObj_year10.rds saveRDS    base
#>   saveTime saved arguments
#> 1       10  TRUE        NA

# Also can add using assignment after a simList object has been made
sim <- simInit(objects = c("tempObj"), paths = list(outputPath = tmpdir))
#> Setting:
#>   options(
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/RtmpAzfvD1/SpaDES/scratch/raster'
#>     reproducible.cachePath = '/tmp/RtmpAzfvD1/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpAzfvD1/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>     spades.modulePath = '/tmp/RtmpAzfvD1/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmpAzfvD1/SpaDES/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/RtmpAzfvD1/SpaDES/scratch/terra'
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
outputs(sim) <- data.frame(objectName = "tempObj", saveTime = 1:10)
sim <- spades(sim)
#> Aug19 19:59:30       Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Aug19 19:59:30 chckpn  total elpsd: 0.00097 secs | 0 checkpoint init 0
#> Aug19 19:59:30 save    total elpsd: 0.0026 secs | 0 save init 0
#> Aug19 19:59:30 prgrss  total elpsd: 0.0043 secs | 0 progress init 0
#> Aug19 19:59:30 load    total elpsd: 0.0058 secs | 0 load init 0
#> Aug19 19:59:30 save    total elpsd: 0.0073 secs | 1 save spades 10
#> Aug19 19:59:30 save    total elpsd: 0.012 secs | 2 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.017 secs | 3 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.022 secs | 4 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.026 secs | 5 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.031 secs | 6 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.036 secs | 7 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.04 secs | 8 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.045 secs | 9 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.05 secs | 10 save later 10
#> simList saved in
#>  SpaDES.core:::.pkgEnv$.sim 
#> It will be deleted at next spades() call.
outputs(sim) # To see that it was saved, when, what filename.
#>    objectName saveTime                                       file     fun
#> 1     tempObj        1 /tmp/RtmpAzfvD1/outputs/tempObj_year01.rds saveRDS
#> 2     tempObj        2 /tmp/RtmpAzfvD1/outputs/tempObj_year02.rds saveRDS
#> 3     tempObj        3 /tmp/RtmpAzfvD1/outputs/tempObj_year03.rds saveRDS
#> 4     tempObj        4 /tmp/RtmpAzfvD1/outputs/tempObj_year04.rds saveRDS
#> 5     tempObj        5 /tmp/RtmpAzfvD1/outputs/tempObj_year05.rds saveRDS
#> 6     tempObj        6 /tmp/RtmpAzfvD1/outputs/tempObj_year06.rds saveRDS
#> 7     tempObj        7 /tmp/RtmpAzfvD1/outputs/tempObj_year07.rds saveRDS
#> 8     tempObj        8 /tmp/RtmpAzfvD1/outputs/tempObj_year08.rds saveRDS
#> 9     tempObj        9 /tmp/RtmpAzfvD1/outputs/tempObj_year09.rds saveRDS
#> 10    tempObj       10 /tmp/RtmpAzfvD1/outputs/tempObj_year10.rds saveRDS
#>    package saved arguments
#> 1     base  TRUE        NA
#> 2     base  TRUE        NA
#> 3     base  TRUE        NA
#> 4     base  TRUE        NA
#> 5     base  TRUE        NA
#> 6     base  TRUE        NA
#> 7     base  TRUE        NA
#> 8     base  TRUE        NA
#> 9     base  TRUE        NA
#> 10    base  TRUE        NA

# can do highly variable saving
tempObj2 <- paste("val", 1:10)
df1 <- data.frame(col1 = tempObj, col2 = tempObj2)
sim <- simInit(objects = c("tempObj", "tempObj2", "df1"),
  paths = list(outputPath = tmpdir))
#> Setting:
#>   options(
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/RtmpAzfvD1/SpaDES/scratch/raster'
#>     reproducible.cachePath = '/tmp/RtmpAzfvD1/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpAzfvD1/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>     spades.modulePath = '/tmp/RtmpAzfvD1/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmpAzfvD1/SpaDES/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/RtmpAzfvD1/SpaDES/scratch/terra'
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
outputs(sim) = data.frame(
     objectName = c(rep("tempObj", 2), rep("tempObj2", 3), "df1"),
     saveTime = c(c(1,4), c(2,6,7), end(sim)),
     fun = c(rep("saveRDS", 5), "write.csv"),
     package = c(rep("base", 5), "utils"),
     stringsAsFactors = FALSE)
# since write.csv has a default of adding a column, x, with rownames, must add additional
#   argument for 6th row in data.frame (corresponding to the write.csv function)
outputArgs(sim)[[6]] <- list(row.names = FALSE)
sim <- spades(sim)
#> Aug19 19:59:30       Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Aug19 19:59:30 chckpn  total elpsd: 0.00099 secs | 0 checkpoint init 0
#> Aug19 19:59:30 save    total elpsd: 0.0027 secs | 0 save init 0
#> Aug19 19:59:30 prgrss  total elpsd: 0.0045 secs | 0 progress init 0
#> Aug19 19:59:30 load    total elpsd: 0.006 secs | 0 load init 0
#> Aug19 19:59:30 save    total elpsd: 0.0074 secs | 1 save spades 10
#> Aug19 19:59:30 save    total elpsd: 0.013 secs | 2 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.018 secs | 4 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.023 secs | 6 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.027 secs | 7 save later 10
#> Aug19 19:59:30 save    total elpsd: 0.032 secs | 10 save later 10
#> simList saved in
#>  SpaDES.core:::.pkgEnv$.sim 
#> It will be deleted at next spades() call.
outputs(sim)
#>   objectName saveTime       fun package
#> 1    tempObj        1   saveRDS    base
#> 2    tempObj        4   saveRDS    base
#> 3   tempObj2        2   saveRDS    base
#> 4   tempObj2        6   saveRDS    base
#> 5   tempObj2        7   saveRDS    base
#> 6        df1       10 write.csv   utils
#>                                          file saved arguments
#> 1  /tmp/RtmpAzfvD1/outputs/tempObj_year01.rds  TRUE        NA
#> 2  /tmp/RtmpAzfvD1/outputs/tempObj_year04.rds  TRUE        NA
#> 3 /tmp/RtmpAzfvD1/outputs/tempObj2_year02.rds  TRUE        NA
#> 4 /tmp/RtmpAzfvD1/outputs/tempObj2_year06.rds  TRUE        NA
#> 5 /tmp/RtmpAzfvD1/outputs/tempObj2_year07.rds  TRUE        NA
#> 6      /tmp/RtmpAzfvD1/outputs/df1_year10.csv  TRUE     FALSE

# read one back in just to test it all worked as planned
newObj <- read.csv(dir(tmpdir, pattern = "year10.csv", full.name = TRUE))
newObj
#>    col1   col2
#> 1     1  val 1
#> 2     2  val 2
#> 3     3  val 3
#> 4     4  val 4
#> 5     5  val 5
#> 6     6  val 6
#> 7     7  val 7
#> 8     8  val 8
#> 9     9  val 9
#> 10   10 val 10

# using saving with SpaDES-aware methods
# To see current ones SpaDES can do
.saveFileExtensions()
#>   exts         fun package
#> 1  rds     saveRDS    base
#> 2   qs       qsave      qs
#> 5  grd writeRaster  raster
#> 4  csv   write.csv   utils
#> 3  txt write.table   utils

library(raster)
if (require(rgdal)) {
  ras <- raster(ncol = 4, nrow = 5)
  ras[] <- 1:20

  sim <- simInit(objects = c("ras"), paths = list(outputPath = tmpdir))
  outputs(sim) = data.frame(
    file = "test",
    fun = "writeRaster",
    package = "raster",
    objectName = "ras",
    stringsAsFactors = FALSE)

  outputArgs(sim)[[1]] <- list(format = "GTiff") # see ?raster::writeFormats
  simOut <- spades(sim)
  outputs(simOut)
  newRas <- raster(dir(tmpdir, full.name = TRUE, pattern = ".tif")[1])
  all.equal(newRas, ras) # Should be TRUE
}
#> Setting:
#>   options(
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/RtmpAzfvD1/SpaDES/scratch/raster'
#>     reproducible.cachePath = '/tmp/RtmpAzfvD1/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpAzfvD1/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpAzfvD1/outputs'
#>     spades.modulePath = '/tmp/RtmpAzfvD1/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmpAzfvD1/SpaDES/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/RtmpAzfvD1/SpaDES/scratch/terra'
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Aug19 19:59:30       Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Aug19 19:59:30 chckpn  total elpsd: 0.00093 secs | 0 checkpoint init 0
#> Aug19 19:59:30 save    total elpsd: 0.0025 secs | 0 save init 0
#> Aug19 19:59:30 prgrss  total elpsd: 0.0042 secs | 0 progress init 0
#> Aug19 19:59:30 load    total elpsd: 0.0057 secs | 0 load init 0
#> Aug19 19:59:30 save    total elpsd: 0.0071 secs | 10 save spades 10
#> simList saved in
#>  SpaDES.core:::.pkgEnv$.sim 
#> It will be deleted at next spades() call.
#> [1] TRUE
# Clean up after
unlink(tmpdir, recursive = TRUE)