Accessor functions for the inputs slots in a simList object.
inputs(sim)
# S4 method for simList
inputs(sim)
inputs(sim) <- value
# S4 method for simList
inputs(sim) <- value
inputArgs(sim)
# S4 method for simList
inputArgs(sim)
inputArgs(sim) <- value
# S4 method for simList
inputArgs(sim) <- valueA simList object from which to extract element(s) or
in which to replace element(s).
The object to be stored at the slot. See Details.
Returns or sets the value(s) of the input or output slots
in the simList object.
These functions are one of three mechanisms to add the information about which input files
to load in a spades call.
As arguments to a simInit call. Specifically, inputs or outputs.
See ?simInit.
With the outputs(simList) function call.
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.
simInitinputs accepts a data.frame, with up to 7 columns.
Columns are:
file | required, a character string indicating the file path. There is no default. |
objectName | optional, 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. |
fun | optional, 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.,
"raster::raster". |
package | optional character string indicating the package in
which to find the fun); |
loadTime | optional 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. |
interval | optional 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 |
arguments | is 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 moduleAny 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'
}
SpaDES.core-package(), specifically the section 1.2.2 on loading and saving.
Other functions to access elements of a 'simList' object:
.addDepends(),
doEvent.checkpoint(),
envir(),
events(),
globals(),
modules(),
objs(),
packages(),
params(),
paths(),
progressInterval(),
times()
#######################
# inputs
#######################
# Start with a basic empty simList
sim <- simInit()
#> Setting:
#> options(
#> reproducible.cachePath = '/tmp/RtmppEYNhs/myProject/cache'
#> spades.inputPath = '/tmp/RtmppEYNhs/myProject/inputs'
#> spades.outputPath = '/tmp/RtmppEYNhs/myProject/outputs'
#> spades.modulePath = '/tmp/RtmppEYNhs/myProject/modules'
#> spades.scratchPath = '/tmp/RtmppEYNhs/SpaDES/scratch'
#> )
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
test <- 1:10
library(igraph) # for %>%
library(reproducible) # for checkPath
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/RtmppEYNhs/inputs/test.rds readRDS base test 0 NA
#> arguments intervals
#> 1 NA NA
simOut <- spades(sim)
#> Jan12 22:40:12 Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan12 22:40:12 chckpn total elpsd: 0.00091 secs | 0 checkpoint init 0
#> Jan12 22:40:12 save total elpsd: 0.0025 secs | 0 save init 0
#> Jan12 22:40:12 prgrss total elpsd: 0.004 secs | 0 progress init 0
#> Jan12 22:40:12 load total elpsd: 0.0055 secs | 0 load init 0
#> Jan12 22:40:12 load total elpsd: 0.0068 secs | 0 load inputs 0
#> Jan12 22:40:12 load test read from /tmp/RtmppEYNhs/inputs/test.rds using readRDS
#> simList saved in
#> SpaDES.core:::.pkgEnv$.sim
#> It will be deleted at next spades() call.
inputs(simOut) # confirm it was loaded
#> file fun package objectName loadTime loaded
#> 1 /tmp/RtmppEYNhs/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(system.file("maps", package = "quickPlot"),
full.names = TRUE, pattern = "tif")
# next: .objectNames are taken from the filenames (without the extension)
# This will load all 5 tifs in the SpaDES sample directory, using
# the raster fuction in the raster package, all at time = 0
if (require("rgdal", quietly = TRUE)) {
sim <- simInit(
inputs = data.frame(
files = allTifs,
functions = "raster",
package = "raster",
loadTime = 0,
stringsAsFactors = FALSE)
)
##############################
#A fully described inputs object, including arguments:
files <- dir(system.file("maps", package = "quickPlot"),
full.names = TRUE, pattern = "tif")
# 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 = "raster::raster",
arguments = arguments,
loadTime = 0,
intervals = c(rep(NA, length(files) - 1), 10)
)
inputs(sim) <- filelist
spades(sim)
}
#> Please note that rgdal will be retired during 2023,
#> plan transition to sf/stars/terra functions using GDAL and PROJ
#> at your earliest convenience.
#> See https://r-spatial.org/r/2022/04/12/evolution.html and https://github.com/r-spatial/evolution
#> rgdal: version: 1.6-3, (SVN revision 1187)
#> Geospatial Data Abstraction Library extensions to R successfully loaded
#> Loaded GDAL runtime: GDAL 3.4.1, released 2021/12/27
#> Path to GDAL shared files: /usr/share/gdal
#> GDAL binary built with GEOS: TRUE
#> Loaded PROJ runtime: Rel. 8.2.1, January 1st, 2022, [PJ_VERSION: 821]
#> Path to PROJ shared files: /home/runner/.local/share/proj:/usr/share/proj
#> PROJ CDN enabled: FALSE
#> Linking to sp version:1.5-1
#> To mute warnings of possible GDAL/OSR exportToProj4() degradation,
#> use options("rgdal_show_exportToProj4_warnings"="none") before loading sp or rgdal.
#> Setting:
#> options(
#> reproducible.cachePath = '/tmp/RtmppEYNhs/myProject/cache'
#> spades.inputPath = '/tmp/RtmppEYNhs/myProject/inputs'
#> spades.outputPath = '/tmp/RtmppEYNhs/myProject/outputs'
#> spades.modulePath = '/tmp/RtmppEYNhs/myProject/modules'
#> spades.scratchPath = '/tmp/RtmppEYNhs/SpaDES/scratch'
#> )
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan12 22:40:13 simInit: DEM read from /home/runner/work/_temp/Library/quickPlot/maps/DEM.tif using raster(inMemory=FALSE)
#> Jan12 22:40:13 simInit: forestAge read from /home/runner/work/_temp/Library/quickPlot/maps/forestAge.tif using raster(inMemory=FALSE)
#> Jan12 22:40:13 simInit: forestCover read from /home/runner/work/_temp/Library/quickPlot/maps/forestCover.tif using raster(inMemory=FALSE)
#> Jan12 22:40:14 simInit: habitatQuality read from /home/runner/work/_temp/Library/quickPlot/maps/habitatQuality.tif using raster(inMemory=FALSE)
#> Jan12 22:40:14 simInit: percentPine read from /home/runner/work/_temp/Library/quickPlot/maps/percentPine.tif using raster(inMemory=FALSE)
#> Jan12 22:40:14 Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan12 22:40:14 chckpn total elpsd: 0.00085 secs | 0 checkpoint init 0
#> Jan12 22:40:14 save total elpsd: 0.0024 secs | 0 save init 0
#> Jan12 22:40:14 prgrss total elpsd: 0.0039 secs | 0 progress init 0
#> Jan12 22:40:14 load total elpsd: 0.0054 secs | 0 load init 0
#> Jan12 22:40:14 load total elpsd: 0.0067 secs | 0 load inputs 0
#> Jan12 22:40:15 load Maps1 read from /home/runner/work/_temp/Library/quickPlot/maps/DEM.tif using raster(inMemory=FALSE)
#> Jan12 22:40:15 load Maps2 read from /home/runner/work/_temp/Library/quickPlot/maps/forestAge.tif using raster(inMemory=FALSE)
#> Jan12 22:40:15 load Maps3 read from /home/runner/work/_temp/Library/quickPlot/maps/forestCover.tif using raster(inMemory=FALSE)
#> Jan12 22:40:16 load Maps4 read from /home/runner/work/_temp/Library/quickPlot/maps/habitatQuality.tif using raster(inMemory=FALSE)
#> Jan12 22:40:16 load Maps5 read from /home/runner/work/_temp/Library/quickPlot/maps/percentPine.tif using raster(inMemory=FALSE)
#> Jan12 22:40:16 load total elpsd: 1.8 secs | 10 load inputs 0
#> Jan12 22:40:16 load Maps5 read from /home/runner/work/_temp/Library/quickPlot/maps/percentPine.tif using raster(inMemory=FALSE) at time 10
#> simList saved in
#> SpaDES.core:::.pkgEnv$.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 sessino
})
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/RtmppEYNhs/myProject/cache'
#> spades.inputPath = '/tmp/RtmppEYNhs/myProject/inputs'
#> spades.outputPath = '/tmp/RtmppEYNhs/myProject/outputs'
#> spades.modulePath = '/tmp/RtmppEYNhs/myProject/modules'
#> spades.scratchPath = '/tmp/RtmppEYNhs/SpaDES/scratch'
#> )
#> Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
a <- spades(a)
#> Jan12 22:40:16 Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan12 22:40:16 chckpn total elpsd: 0.00083 secs | 0 checkpoint init 0
#> Jan12 22:40:16 save total elpsd: 0.0024 secs | 0 save init 0
#> Jan12 22:40:16 prgrss total elpsd: 0.0039 secs | 0 progress init 0
#> Jan12 22:40:16 load total elpsd: 0.0053 secs | 0 load init 0
#> Jan12 22:40:16 load total elpsd: 0.0067 secs | 1 load inputs 0
#> Jan12 22:40:16 load a loaded into simList
#> simList saved in
#> SpaDES.core:::.pkgEnv$.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
#> Jan12 22:40:16 Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan12 22:40:16 load total elpsd: 0.022 secs | 2 load inputs 0
#> Jan12 22:40:16 load a loaded into simList
#> simList saved in
#> SpaDES.core:::.pkgEnv$.sim
#> It will be deleted at next spades() call.
identical(a2, a$a)
#> [1] TRUE
# Clean up after
unlink(tmpdir, recursive = TRUE)