These functions are one of three mechanisms to add the information about which input files to load in a spades call and the information about which output files to save. 1) As arguments to a simInit call. Specifically, inputs or outputs. See ?simInit. 2) With the inputs(simList) or 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(sim)

# S4 method for simList
inputs(sim)

inputs(sim) <- value

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

outputs(sim)

# S4 method for simList
outputs(sim)

outputs(sim) <- value

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

inputArgs(sim)

# S4 method for simList
inputArgs(sim)

inputArgs(sim) <- value

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

Value

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

Details

Accessor functions for the inputs and outputs slots in a simList object.

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.

inputs function or argument in simInit

inputs 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 thesimList
. This objectcan therefore be accessed with
sim$xxxin 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 inSpaDES
(found byexamining
.fileExtensions()). The
packageand
funcan be
jointly specified here as"packageName::functionName"
, e.g.,"raster::raster"
.
package
optional character string indicating the package in
which to find thefun
);
loadTime
optional numeric, indicating when in simulation time the file
should be loaded. The default is the highest priority atstart(sim)
,i.e., at the very start.
interval
optional numeric, indicating at what interval should this sameexact 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 inloadTime
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 eachfun
.

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' }

outputs function or argument in simInit

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

objectName
required, character string indicating the name of the object
in thesimList
that will be saved to disk (without thesim$
prefix).
file
optional, a character string indicating the file path to save to.
The default is to concatenateobjectName
with the model timeunit andsaveTime
, separated by underscore, "_". So a default filename would be"Fires_year1.rds"
fun
optional, a character string indicating the function to use tosave that file. The default is
saveRDS
package
optional character string indicating the package inwhich to find the
fun);
saveTime
optional numeric, indicating when in simulation time the fileshould be saved. The default is the lowest priority at
end(sim),
i.e., at the very end.
arguments
is 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 = TRUEto
write.csvIf there is only one list,
then it is assumed to apply to all files and will be recycled as per normal Rrules of recycling for each
fun.

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

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, doEvent.checkpoint, 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/RtmpTMlCNd/reproducible/cache' #> spades.inputPath = '/tmp/Rtmpj3cw1D/SpaDES/inputs' #> spades.outputPath = '/tmp/Rtmpj3cw1D/SpaDES/outputs' #> spades.modulePath = '/tmp/Rtmpj3cw1D/SpaDES/modules' #> )
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/Rtmpj3cw1D/inputs/test.rds readRDS base test 0 NA #> arguments intervals #> 1 NA NA
simOut <- spades(sim)
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 0 load inputs 1
#> test read from /tmp/Rtmpj3cw1D/inputs/test.rds using readRDS
#> 0 checkpoint init 5 #> 0 save init 5 #> 0 progress init 5 #> 0 load init 5
inputs(simOut) # confirm it was loaded
#> file fun package objectName loadTime loaded #> 1 /tmp/Rtmpj3cw1D/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) }
#> rgdal: version: 1.3-6, (SVN revision 773) #> Geospatial Data Abstraction Library extensions to R successfully loaded #> Loaded GDAL runtime: GDAL 2.2.3, released 2017/11/20 #> Path to GDAL shared files: /usr/share/gdal/2.2 #> GDAL binary built with GEOS: TRUE #> Loaded PROJ.4 runtime: Rel. 4.9.3, 15 August 2016, [PJ_VERSION: 493] #> Path to PROJ.4 shared files: (autodetected) #> Linking to sp version: 1.3-1
#> Setting: #> options( #> reproducible.cachePath = '/tmp/RtmpTMlCNd/reproducible/cache' #> spades.inputPath = '/tmp/Rtmpj3cw1D/SpaDES/inputs' #> spades.outputPath = '/tmp/Rtmpj3cw1D/SpaDES/outputs' #> spades.modulePath = '/tmp/Rtmpj3cw1D/SpaDES/modules' #> )
#> DEM read from /usr/local/lib/R/site-library/quickPlot/maps/DEM.tif using raster(inMemory=FALSE)
#> forestAge read from /usr/local/lib/R/site-library/quickPlot/maps/forestAge.tif using raster(inMemory=FALSE)
#> forestCover read from /usr/local/lib/R/site-library/quickPlot/maps/forestCover.tif using raster(inMemory=FALSE)
#> habitatQuality read from /usr/local/lib/R/site-library/quickPlot/maps/habitatQuality.tif using raster(inMemory=FALSE)
#> percentPine read from /usr/local/lib/R/site-library/quickPlot/maps/percentPine.tif using raster(inMemory=FALSE)
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 0 load inputs 1
#> Maps1 read from /usr/local/lib/R/site-library/quickPlot/maps/DEM.tif using raster(inMemory=FALSE)
#> Maps2 read from /usr/local/lib/R/site-library/quickPlot/maps/forestAge.tif using raster(inMemory=FALSE)
#> Maps3 read from /usr/local/lib/R/site-library/quickPlot/maps/forestCover.tif using raster(inMemory=FALSE)
#> Maps4 read from /usr/local/lib/R/site-library/quickPlot/maps/habitatQuality.tif using raster(inMemory=FALSE)
#> Maps5 read from /usr/local/lib/R/site-library/quickPlot/maps/percentPine.tif using raster(inMemory=FALSE)
#> 0 checkpoint init 5 #> 0 save init 5 #> 0 progress init 5 #> 0 load init 5 #> 10 load inputs 1
#> Maps5 read from /usr/local/lib/R/site-library/quickPlot/maps/percentPine.tif using raster(inMemory=FALSE) #> at time 10
# 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/RtmpTMlCNd/reproducible/cache' #> spades.inputPath = '/tmp/Rtmpj3cw1D/SpaDES/inputs' #> spades.outputPath = '/tmp/Rtmpj3cw1D/SpaDES/outputs' #> spades.modulePath = '/tmp/Rtmpj3cw1D/SpaDES/modules' #> )
a <- spades(a)
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 0 checkpoint init 5 #> 0 save init 5 #> 0 progress init 5 #> 0 load init 5 #> 1 load inputs 1
#> a loaded into simList
identical(a1, a$a)
#> [1] TRUE
end(a) <- 3 a <- spades(a) # different object (a2) loaded onto a$a
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 2 load inputs 1
#> a loaded into simList
identical(a2, a$a)
#> [1] TRUE
# Clean up after unlink(tmpdir, recursive = TRUE) ####################### # 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/Rtmpj3cw1D/outputs' #> )
#> Paths set to: #> options( #> reproducible.cachePath = '/tmp/RtmpTMlCNd/reproducible/cache' #> spades.inputPath = '/tmp/Rtmpj3cw1D/SpaDES/inputs' #> spades.outputPath = '/tmp/Rtmpj3cw1D/outputs' #> spades.modulePath = '/tmp/Rtmpj3cw1D/SpaDES/modules' #> )
outputs(sim) # To see what will be saved, when, what filename
#> objectName file fun package #> 1 tempObj /tmp/Rtmpj3cw1D/outputs/tempObj_year10.rds saveRDS base #> saveTime saved arguments #> 1 10 NA NA
sim <- spades(sim)
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 0 checkpoint init 5 #> 0 save init 5 #> 0 progress init 5 #> 0 load init 5 #> 10 save spades 10
outputs(sim) # To see that it was saved, when, what filename
#> objectName file fun package #> 1 tempObj /tmp/Rtmpj3cw1D/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/Rtmpj3cw1D/outputs' #> )
#> Paths set to: #> options( #> reproducible.cachePath = '/tmp/RtmpTMlCNd/reproducible/cache' #> spades.inputPath = '/tmp/Rtmpj3cw1D/SpaDES/inputs' #> spades.outputPath = '/tmp/Rtmpj3cw1D/outputs' #> spades.modulePath = '/tmp/Rtmpj3cw1D/SpaDES/modules' #> )
outputs(sim) <- data.frame(objectName = "tempObj", saveTime = 1:10) sim <- spades(sim)
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 0 checkpoint init 5 #> 0 save init 5 #> 0 progress init 5 #> 0 load init 5 #> 1 save spades 10 #> 2 save later 10 #> 3 save later 10 #> 4 save later 10 #> 5 save later 10 #> 6 save later 10 #> 7 save later 10 #> 8 save later 10 #> 9 save later 10 #> 10 save later 10
outputs(sim) # To see that it was saved, when, what filename.
#> objectName saveTime file fun #> 1 tempObj 1 /tmp/Rtmpj3cw1D/outputs/tempObj_year01.rds saveRDS #> 2 tempObj 2 /tmp/Rtmpj3cw1D/outputs/tempObj_year02.rds saveRDS #> 3 tempObj 3 /tmp/Rtmpj3cw1D/outputs/tempObj_year03.rds saveRDS #> 4 tempObj 4 /tmp/Rtmpj3cw1D/outputs/tempObj_year04.rds saveRDS #> 5 tempObj 5 /tmp/Rtmpj3cw1D/outputs/tempObj_year05.rds saveRDS #> 6 tempObj 6 /tmp/Rtmpj3cw1D/outputs/tempObj_year06.rds saveRDS #> 7 tempObj 7 /tmp/Rtmpj3cw1D/outputs/tempObj_year07.rds saveRDS #> 8 tempObj 8 /tmp/Rtmpj3cw1D/outputs/tempObj_year08.rds saveRDS #> 9 tempObj 9 /tmp/Rtmpj3cw1D/outputs/tempObj_year09.rds saveRDS #> 10 tempObj 10 /tmp/Rtmpj3cw1D/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/Rtmpj3cw1D/outputs' #> )
#> Paths set to: #> options( #> reproducible.cachePath = '/tmp/RtmpTMlCNd/reproducible/cache' #> spades.inputPath = '/tmp/Rtmpj3cw1D/SpaDES/inputs' #> spades.outputPath = '/tmp/Rtmpj3cw1D/outputs' #> spades.modulePath = '/tmp/Rtmpj3cw1D/SpaDES/modules' #> )
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)
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 0 checkpoint init 5 #> 0 save init 5 #> 0 progress init 5 #> 0 load init 5 #> 1 save spades 10 #> 2 save later 10 #> 4 save later 10 #> 6 save later 10 #> 7 save later 10 #> 10 save later 10
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/Rtmpj3cw1D/outputs/tempObj_year01.rds TRUE NA #> 2 /tmp/Rtmpj3cw1D/outputs/tempObj_year04.rds TRUE NA #> 3 /tmp/Rtmpj3cw1D/outputs/tempObj2_year02.rds TRUE NA #> 4 /tmp/Rtmpj3cw1D/outputs/tempObj2_year06.rds TRUE NA #> 5 /tmp/Rtmpj3cw1D/outputs/tempObj2_year07.rds TRUE NA #> 6 /tmp/Rtmpj3cw1D/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 #> 4 grd writeRaster raster #> 3 csv write.csv utils #> 2 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")) all.equal(newRas, ras) # Should be TRUE }
#> Setting: #> options( #> spades.outputPath = '/tmp/Rtmpj3cw1D/outputs' #> )
#> Paths set to: #> options( #> reproducible.cachePath = '/tmp/RtmpTMlCNd/reproducible/cache' #> spades.inputPath = '/tmp/Rtmpj3cw1D/SpaDES/inputs' #> spades.outputPath = '/tmp/Rtmpj3cw1D/outputs' #> spades.modulePath = '/tmp/Rtmpj3cw1D/SpaDES/modules' #> )
#> This is the current event, printed as it is happening: #> eventTime moduleName eventType eventPriority #> 0 checkpoint init 5 #> 0 save init 5 #> 0 progress init 5 #> 0 load init 5 #> 10 save spades 10
#> [1] TRUE
# Clean up after unlink(tmpdir, recursive = TRUE)