simList-accessors-outputs: Simulation outputs

In SpaDES.core: Core Utilities for Developing and Running Spatially Explicit Discrete Event Models

Simulation outputs

Description

Accessor functions for the outputs slots in a simList object.

If a module saves a file to disk during events, it can be useful to keep track of the files that are saved e.g., for saveSimList() so that all files can be added to the archive. In addition to setting outputs at the simInit stage, a module developer can also put this in a using any saving mechanism that is relevant (e.g., qs::qsave, saveRDS etc.). When a module event does this it can be useful to register that saved file. registerOutputs offers an additional mechanism to do this. See examples.

Usage

outputs(sim)

## S4 method for signature 'simList'
outputs(sim)

outputs(sim) <- value

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

registerOutputs(filename, sim, ...)

outputArgs(sim)

## S4 method for signature 'simList'
outputArgs(sim)

outputArgs(sim) <- value

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

Arguments

sim	A simList. If missing, then the function will search in the call stack, so it will find it if it is in a SpaDES module.
value	The object to be stored at the slot. See Details.
filename	The filename to register in the outputs(sim) data.frame. If missing, an attempt will be made to search for either a file or filename argument in the call itself. This means that this function can be used with the pipe, as long as the returned return from the upstream pipe function is a filename or if it is NULL (e.g., saveRDS), then it will find the file argument and use that.
...	Not used.

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 using registerOutputs: a user can pass any other arguments to registerOutputs that are in the outputs(sim) data.frame, such as objectName, fun, package, though these will not be used to save the files as this function is only about registering an output that has already been saved.

Value

A simList which will be the sim passed in with a new object registered in the outputs(sim)

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 the simList that will be saved to disk (without the ⁠sim$⁠ prefix).
file	optional, 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".
fun	optional, a character string indicating the function to use to save that file. The default is saveRDS()
package	optional character string indicating the package in which to find the fun);
saveTime	optional 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.
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 = 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")).

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.

See Also

registerOutputs() which enables files that are saved to be added to the simList using the outputs(sim) mechanism, so the files that are saved during a module event can be tracked at the simList level. saveSimList() which will optionally add all the outputs that are tracked into an archive.

Plots(), outputs()

Examples

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

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))
outputs(sim) # To see what will be saved, when, what filename
sim <- spades(sim)
outputs(sim) # To see that it was saved, when, what filename

# Also can add using assignment after a simList object has been made
sim <- simInit(objects = c("tempObj"), paths = list(outputPath = tmpdir))
outputs(sim) <- data.frame(objectName = "tempObj", saveTime = 1:10)
sim <- spades(sim)
outputs(sim) # To see that it was saved, when, what filename.

# 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))
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)
outputs(sim)

# read one back in just to test it all worked as planned
newObj <- read.csv(dir(tmpdir, pattern = "year10.csv", full.name = TRUE))
newObj

# using saving with SpaDES-aware methods
# To see current ones SpaDES can do
.saveFileExtensions()

library(terra)
ras <- rast(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 = "terra",
  objectName = "ras",
  stringsAsFactors = FALSE)

# outputArgs(sim)[[1]] <- list(format = "GTiff") # see ?raster::writeFormats
simOut <- spades(sim)
outputs(simOut)
newRas <- rast(dir(tmpdir, full.name = TRUE, pattern = ".tif")[1])
all.equal(newRas, ras) # Should be TRUE
# Clean up after
unlink(tmpdir, recursive = TRUE)
# For `registerOutputs`
sim <- simInit()
# This would normally be a save call, e.g., `writeRaster`
tf <- reproducible::tempfile2(fileext = ".tif")
sim <- registerOutputs(sim, filename = tf)

# Using a pipe
tf <- reproducible::tempfile2(fileext = ".rds")
sim$a <- 1
sim <- saveRDS(sim$a, tf) |> registerOutputs()
# confirm:
outputs(sim) # has object --> saved = TRUE

SpaDES.core documentation built on Nov. 10, 2023, 5:08 p.m.