Simulation inputs

Source: R/simList-accessors.R

Accessor functions for the inputs slots in a simList object.

inputs(sim)

# S4 method for class 'simList'
inputs(sim)

inputs(sim) <- value

# S4 method for class 'simList'
inputs(sim) <- value

inputArgs(sim)

# S4 method for class 'simList'
inputArgs(sim)

inputArgs(sim) <- value

# S4 method for class 'simList'
inputArgs(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.

Value

Returns or sets the value(s) of the input or output slots in the simList object.

Details

These functions are one of three mechanisms to add the information about which input files to load in a spades call.

  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.

inputs function or argument in simInit

inputs accepts a data.frame, with up to 7 columns. Columns are:

filerequired, a character string indicating the file path. There is no default.
objectNameoptional, character string indicating the name of the object that the loaded file will be assigned to in the simList. This object can therefore be accessed with sim$xxx in any module, where objectName = "xxx". Defaults to the filename without file extension or directory information.
funoptional, a character string indicating the function to use to load that file. Defaults to the known extensions in SpaDES (found by examining .fileExtensions()). The package and fun can be jointly specified here as "packageName::functionName", e.g., "terra::rast".
packageoptional character string indicating the package in which to find the fun);
loadTimeoptional numeric, indicating when in simulation time the file should be loaded. The default is the highest priority at start(sim), i.e., at the very start.
intervaloptional numeric, indicating at what interval should this same exact file be reloaded from disk, e.g,. 10 would mean every 10 time units. The default is NA or no interval, i.e, load the file only once as described in loadTime
argumentsis a list of lists of named arguments, one list for each fun. For example, if fun="raster", arguments = list(native = TRUE) will pass the argument "native = TRUE" to raster. 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.

Currently, only file is required. All others will be filled with defaults if not specified.

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

.inputObjects function placed inside module

Any code placed inside a function called .inputObjects will be run during simInit() for the purpose of creating any objects required by this module, i.e., objects identified in the inputObjects element of defineModule. This is useful if there is something required before simulation to produce the module object dependencies, including such things as downloading default datasets, e.g., downloadData('LCC2005', modulePath(sim)). Nothing should be created here that does not create an named object in inputObjects. Any other initiation procedures should be put in the "init" eventType of the doEvent function. Note: the module developer can use sim$.userSuppliedObjNames inside the function to selectively skip unnecessary steps because the user has provided those inputObjects in the simInit call. e.g., the following code would look to see if the user had passed defaultColor into during simInit. If the user had done this, then this function would not override that value with 'red'. If the user has not passed in a value for defaultColor, then the module will get it here:

if (!('defaultColor' %in% sim$.userSuppliedObjNames)) { sim$defaultColor <- 'red' }

See also

SpaDES.core-package, specifically the section 1.2.2 on loading and saving.

Other functions to access elements of a 'simList' object: .addDepends(), checkpointFile(), envir(), events(), globals(), modules(), objs(), packages(), params(), paths(), progressInterval(), times()

Examples

#######################
# inputs
#######################

# Start with a basic empty simList
sim <- simInit()
#> Setting:
#>   options(
#>     reproducible.cachePath = '/tmp/RtmpIQ0Aky/cache'
#>     spades.inputPath = '/tmp/RtmpIQ0Aky/inputs'
#>     spades.outputPath = '/tmp/RtmpIQ0Aky'
#>     spades.modulePath = '/tmp/RtmpIQ0Aky/modules'
#>     spades.scratchPath = '/tmp/RtmpIQ0Aky/scratch'
#>   )
#> Jan27 19:04:15 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Elpsed time for simInit: 0.0289669 secs

test <- 1:10
tmpdir <- file.path(tempdir(), "inputs") |> checkPath(create = TRUE)
tmpFile <- file.path(tmpdir, "test.rds")
saveRDS(test, file = tmpFile)
inputs(sim) <- data.frame(file = tmpFile) # using only required column, "file"
inputs(sim) # see that it is not yet loaded, but when it is scheduled to be loaded
#>                              file     fun package objectName loadTime loaded
#> 1 /tmp/RtmpIQ0Aky/inputs/test.rds readRDS    base       test        0     NA
#>   arguments intervals
#> 1        NA        NA
simOut <- spades(sim)
#> Jan27 19:04:15 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan27 19:04:15 chckpn:init total elpsd: 0.03 secs | 0 checkpoint init 0
#> Jan27 19:04:15 save  :init total elpsd: 0.032 secs | 0 save init 0
#> Jan27 19:04:15 prgrss:init total elpsd: 0.034 secs | 0 progress init 0
#> Jan27 19:04:15 load  :init total elpsd: 0.036 secs | 0 load init 0
#> Jan27 19:04:15 load  :inputs total elpsd: 0.037 secs | 0 load inputs 0
#> Jan27 19:04:16 load  :inputs test read from /tmp/RtmpIQ0Aky/inputs/test.rds using readRDS
#> simList saved in
#> SpaDES.core:::savedSimEnv()$.sim
#> It will be deleted at next spades() call.
inputs(simOut) # confirm it was loaded
#>                              file     fun package objectName loadTime loaded
#> 1 /tmp/RtmpIQ0Aky/inputs/test.rds readRDS    base       test        0   TRUE
#>   arguments intervals
#> 1        NA        NA
simOut$test
#>  [1]  1  2  3  4  5  6  7  8  9 10

# can put data.frame for inputs directly inside simInit call
allTifs <- dir(getMapPath(tempdir()), full.names = TRUE)

# next: .objectNames are taken from the filenames (without the extension)
# This will load all 5 tifs in the SpaDES sample directory, using
#   the rast fuction in the terra package, all at time = 0
sim <- simInit(
  inputs = data.frame(
    files = allTifs,
    functions = "rast",
    package = "terra",
    loadTime = 0,
    stringsAsFactors = FALSE)
)
#> Setting:
#>   options(
#>     reproducible.cachePath = '/tmp/RtmpIQ0Aky/cache'
#>     spades.inputPath = '/tmp/RtmpIQ0Aky/inputs'
#>     spades.outputPath = '/tmp/RtmpIQ0Aky'
#>     spades.modulePath = '/tmp/RtmpIQ0Aky/modules'
#>     spades.scratchPath = '/tmp/RtmpIQ0Aky/scratch'
#>   )
#> Jan27 19:04:16 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan27 19:04:16 simInit DEM read from /tmp/RtmpIQ0Aky/maps/DEM.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 simInit forestAge read from /tmp/RtmpIQ0Aky/maps/forestAge.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 simInit forestCover read from /tmp/RtmpIQ0Aky/maps/forestCover.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 simInit habitatQuality read from /tmp/RtmpIQ0Aky/maps/habitatQuality.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 simInit percentPine read from /tmp/RtmpIQ0Aky/maps/percentPine.tif using rast(inMemory=FALSE)
#> Elpsed time for simInit: 0.05201316 secs

##############################
# A fully described inputs object, including arguments:
files <- dir(getMapPath(tempdir()), full.names = TRUE)

# arguments must be a list of lists. This may require I() to keep it as a list
#   once it gets coerced into the data.frame.
# arguments = I(rep(list(native = TRUE), length(files)))
filelist <- data.frame(
  objectName = paste0("Maps", 1:5),
  files = files,
  functions = "terra::rast",
  # arguments = arguments,
  loadTime = 0,
  intervals = c(rep(NA, length(files) - 1), 10)
)
inputs(sim) <- filelist
spades(sim)
#> Jan27 19:04:16 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan27 19:04:16 chckpn:init total elpsd: 0.053 secs | 0 checkpoint init 0
#> Jan27 19:04:16 save  :init total elpsd: 0.055 secs | 0 save init 0
#> Jan27 19:04:16 prgrss:init total elpsd: 0.057 secs | 0 progress init 0
#> Jan27 19:04:16 load  :init total elpsd: 0.059 secs | 0 load init 0
#> Jan27 19:04:16 load  :inputs total elpsd: 0.06 secs | 0 load inputs 0
#> Jan27 19:04:16 load  :inputs Maps1 read from /tmp/RtmpIQ0Aky/maps/DEM.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 load  :inputs Maps2 read from /tmp/RtmpIQ0Aky/maps/forestAge.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 load  :inputs Maps3 read from /tmp/RtmpIQ0Aky/maps/forestCover.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 load  :inputs Maps4 read from /tmp/RtmpIQ0Aky/maps/habitatQuality.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 load  :inputs Maps5 read from /tmp/RtmpIQ0Aky/maps/percentPine.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 load  :inputs total elpsd: 0.079 secs | 10 load inputs 0
#> Jan27 19:04:16 load  :inputs Maps5 read from /tmp/RtmpIQ0Aky/maps/percentPine.tif using rast(inMemory=FALSE)
#> Jan27 19:04:16 load  :inputs    at time 10
#> simList saved in
#> SpaDES.core:::savedSimEnv()$.sim
#> It will be deleted at next spades() call.

# Example showing loading multiple objects from global environment onto the
#   same object in the simList, but at different load times
a1 <- 1
a2 <- 2
# Note arguments must be a list of NROW(inputs), with each element itself being a list,
#  which is passed to do.call(fun[x], arguments[[x]]), where x is row number, one at a time
args <- lapply(1:2, function(x) {
               list(x = paste0("a", x),
                    envir = environment()) # may be necessary to specify in which envir a1, a2
                                           # are located, if not in an interactive session
               })
inputs <- data.frame(objectName = "a", loadTime = 1:2, fun = "base::get", arguments = I(args))
a <- simInit(inputs = inputs, times = list(start = 0, end = 1))
#> Setting:
#>   options(
#>     reproducible.cachePath = '/tmp/RtmpIQ0Aky/cache'
#>     spades.inputPath = '/tmp/RtmpIQ0Aky/inputs'
#>     spades.outputPath = '/tmp/RtmpIQ0Aky'
#>     spades.modulePath = '/tmp/RtmpIQ0Aky/modules'
#>     spades.scratchPath = '/tmp/RtmpIQ0Aky/scratch'
#>   )
#> Jan27 19:04:16 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Elpsed time for simInit: 0.03267455 secs
a <- spades(a)
#> Jan27 19:04:16 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan27 19:04:16 chckpn:init total elpsd: 0.034 secs | 0 checkpoint init 0
#> Jan27 19:04:16 save  :init total elpsd: 0.036 secs | 0 save init 0
#> Jan27 19:04:16 prgrss:init total elpsd: 0.038 secs | 0 progress init 0
#> Jan27 19:04:16 load  :init total elpsd: 0.039 secs | 0 load init 0
#> Jan27 19:04:16 load  :inputs total elpsd: 0.041 secs | 1 load inputs 0
#> Jan27 19:04:16 load  :inputs a loaded into simList
#> simList saved in
#> SpaDES.core:::savedSimEnv()$.sim
#> It will be deleted at next spades() call.
identical(a1, a$a)
#> [1] TRUE

end(a) <- 3
a <- spades(a) # different object (a2) loaded onto a$a
#> Jan27 19:04:16 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan27 19:04:16 load  :inputs total elpsd: 0.056 secs | 2 load inputs 0
#> Jan27 19:04:16 load  :inputs a loaded into simList
#> simList saved in
#> SpaDES.core:::savedSimEnv()$.sim
#> It will be deleted at next spades() call.
identical(a2, a$a)
#> [1] TRUE

# Clean up after
unlink(tmpdir, recursive = TRUE)