Save Datasheet(s) — saveDatasheet • rsyncrosim

Saves Datasheets to a SsimLibrary, Project, or Scenario.

saveDatasheet(
  ssimObject,
  data,
  name = NULL,
  fileData = NULL,
  append = NULL,
  forceElements = FALSE,
  force = FALSE,
  breakpoint = FALSE,
  import = TRUE,
  path = NULL
)

# S4 method for character
saveDatasheet(
  ssimObject,
  data,
  name = NULL,
  fileData = NULL,
  append = NULL,
  forceElements = FALSE,
  force = FALSE,
  breakpoint = FALSE,
  import = TRUE,
  path = NULL
)

# S4 method for SsimObject
saveDatasheet(
  ssimObject,
  data,
  name = NULL,
  fileData = NULL,
  append = NULL,
  forceElements = FALSE,
  force = FALSE,
  breakpoint = FALSE,
  import = TRUE,
  path = NULL
)

Arguments

ssimObject	`SsimLibrary`, `Project`, or `Scenario` object
data	data.frame, named vector, or list of these. One or more Datasheets to load
name	character or vector of these. The name(s) of the Datasheet(s) to be saved. If a vector of names is provided, then a list must be provided for the `data` argument. Names provided here will override those provided with `data` argument's list
fileData	named list or raster stack. Names are file names (without paths), corresponding to entries in `data` The elements are objects containing the data associated with each name. Currently only supports Raster objects as elements
append	logical. If `TRUE`, the incoming data will be appended to the Datasheet if possible. Default is `TRUE` for Project/SsimLibrary-scope Datasheets, and `FALSE` for Scenario-scope Datasheets. See 'details' for more information about this argument
forceElements	logical. If `FALSE` (default) a single return message will be returned as a character string. Otherwise it will be returned in a list
force	logical. If Datasheet scope is Project/SsimLibrary, and `append=FALSE`, Datasheet will be deleted before loading the new data. This can also delete other definitions and results, so if `force=FALSE` (default) user will be prompted for approval
breakpoint	logical. Set to `TRUE` when modifying Datasheets in a breakpoint function. Default is `FALSE`
import	logical. Set to `TRUE` to import the data after saving. Default is `FALSE`
path	character. output path (optional)

Value

Invisibly returns a vector or list of logical values for each input: TRUE upon success (i.e.successful save) and FALSE upon failure.

Details

SsimObject/Project/Scenario should identify a single SsimObject.

If fileData != NULL, each element of names(fileData) should correspond uniquely to at most one entry in data. If a name is not found in data the element will be ignored with a warning. If names(fileData) are full filepaths, rsyncrosim will write each object to the corresponding path for subsequent loading by SyncroSim. Note this is generally more time-consuming because the files must be written twice. If names(fileData) are not filepaths (faster, recommended), rsyncrosim will write each element directly to the appropriate SyncroSim input/output folders. rsyncrosim will write each element of fileData directly to the appropriate SyncroSim input/output folders. If fileData != NULL, data should be a data.frame, vector, or list of length 1, not a list of length >1.

About the 'append' argument:

A Datasheet is a VALIDATION SOURCE if its data can be used to validate column values in a different Datasheet.
The append argument will be ignored if the Datasheet is a validation source and has a Project scope. In this case the data will be MERGED.

Examples

# \donttest{
# Install helloworldSpatial package
addPackage("helloworldSpatial")
#> Package <helloworldSpatial> is already installed

# Set the file path and name of the new SsimLibrary
myLibraryName <- file.path(tempdir(),"testlib_saveDatasheet")

# Set the SyncroSim Session, SsimLibrary, Project, and Scenario
mySession <- session()
myLibrary <- ssimLibrary(name = myLibraryName,
                         session = mySession, 
                         package = "helloworldSpatial",
                         template = "example-library")
#> Scenarios available in this template:    My Scenario
myProject <- project(myLibrary, project = "Definitions")
myScenario <- scenario(myProject, scenario = "My Scenario")

# Get all Datasheet info
myDatasheets <- datasheet(myScenario)

# Get a specific Datasheet
myDatasheet <- datasheet(myScenario, name = "RunControl")

# Modify Datasheet
myDatasheet$MaximumTimestep <- 10

# Save Datasheet
saveDatasheet(ssimObject = myScenario, data = myDatasheet, name = "RunControl")
#> Datasheet <helloworldSpatial_RunControl> saved
          
# Import data after saving
saveDatasheet(ssimObject = myScenario, data = myDatasheet, name = "RunControl",
              import = TRUE)
#> Datasheet <helloworldSpatial_RunControl> saved
        
# Save the new Datasheet to a specified output path
saveDatasheet(ssimObject = myScenario, data = myDatasheet, name = "RunControl",
              path = tempdir())
#> Datasheet <helloworldSpatial_RunControl> saved
              
# Save a raster stack using fileData
# Create a raster stack - add as many raster files as you want here
map1 <- datasheetRaster(myScenario, datasheet = "InputDatasheet",
                        column = "InterceptRasterFile")
inRasters <- raster::stack(map1)

# Change the name of the rasters in the input Datasheets to match the stack
inSheet <- datasheet(myScenario, name="InputDatasheet")
inSheet[1,"InterceptRasterFile"] <- names(inRasters)[1]

# Save the raster stack to the input Datasheet
saveDatasheet(myScenario, data=inSheet, name="InputDatasheet", 
              fileData=inRasters)
#> Datasheet <helloworldSpatial_InputDatasheet> saved
# }