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 SpatRaster object. Names are file names (without paths), corresponding to entries in data The elements are objects containing the data associated with each name. Currently supports terra SpatRaster objects as elements, (support for Raster objects is deprecated)
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

if (FALSE) {
# Install helloworldSpatial package
addPackage("helloworldSpatial")

# 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",
                         forceUpdate = TRUE)
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")
          
# Import data after saving
saveDatasheet(ssimObject = myScenario, data = myDatasheet, name = "RunControl",
              import = TRUE)
        
# Save the new Datasheet to a specified output path
saveDatasheet(ssimObject = myScenario, data = myDatasheet, name = "RunControl",
              path = tempdir())
              
# 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 <- terra::rast(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)
}