Inputs and outputs

Share:

Description

These functions are one of two mechanisms to add the information about which input files to load in a spades call and the information about which output files to save. The other way is to pass them as arguments to a simInit call.

inputArgs and outputArgs are ways to specify any arguments that are needed for file loading and file saving. This is still somewhat experimental.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
inputs(object)

## S4 method for signature '.simList'
inputs(object)

inputs(object) <- value

## S4 replacement method for signature '.simList'
inputs(object) <- value

outputs(object)

## S4 method for signature '.simList'
outputs(object)

outputs(object) <- value

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

inputArgs(object)

## S4 method for signature '.simList'
inputArgs(object)

inputArgs(object) <- value

## S4 replacement method for signature '.simList'
inputArgs(object) <- value

outputArgs(object)

## S4 method for signature '.simList'
outputArgs(object)

outputArgs(object) <- value

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

Arguments

object

A simList simulation object.

value

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

Details

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

Value

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

inputs

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 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 extentions 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")).

outputs

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")).

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

SpaDES, 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, ls.simList, ls.str.simList, modules, objs, packages, params, paths, progressInterval, times

Examples

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
#######################
# inputs
#######################

# Start with a basic empty simList
sim <- simInit()

test <- 1:10
library(igraph) # for %>%
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
simOut <- spades(sim)
inputs(simOut) # confirm it was loaded
simOut$test

# can put data.frame for inputs directly inside simInit call
allTifs <- dir(system.file("maps", package = "SpaDES"),
               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 = "SpaDES"),
               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)
}


# 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))
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="second10.csv", full.name=TRUE))
newObj

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

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
}
# Clean up after
unlink(tmpdir, recursive = TRUE)

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.