Retrieve a SyncroSim Datasheet — datasheet • rsyncrosim

This function retrieves a SyncroSim Datasheet, either by calling the SyncroSim console, or by directly querying the SsimLibrary database.

datasheet(
  ssimObject,
  name = NULL,
  project = NULL,
  scenario = NULL,
  summary = NULL,
  optional = FALSE,
  empty = FALSE,
  filterColumn = NULL,
  filterValue = NULL,
  lookupsAsFactors = TRUE,
  sqlStatement = list(select = "SELECT *", groupBy = ""),
  includeKey = FALSE,
  forceElements = FALSE,
  fastQuery = FALSE
)

# S4 method for list
datasheet(
  ssimObject,
  name = NULL,
  project = NULL,
  scenario = NULL,
  summary = NULL,
  optional = FALSE,
  empty = FALSE,
  filterColumn = NULL,
  filterValue = NULL,
  lookupsAsFactors = TRUE,
  sqlStatement = list(select = "SELECT *", groupBy = ""),
  includeKey = FALSE,
  forceElements = FALSE,
  fastQuery = FALSE
)

# S4 method for character
datasheet(
  ssimObject,
  name,
  project,
  scenario,
  summary,
  optional,
  empty,
  filterColumn,
  filterValue,
  lookupsAsFactors,
  sqlStatement,
  includeKey,
  fastQuery
)

# S4 method for SsimObject
datasheet(
  ssimObject,
  name = NULL,
  project = NULL,
  scenario = NULL,
  summary = NULL,
  optional = FALSE,
  empty = FALSE,
  filterColumn = NULL,
  filterValue = NULL,
  lookupsAsFactors = TRUE,
  sqlStatement = list(select = "SELECT *", groupBy = ""),
  includeKey = FALSE,
  forceElements = FALSE,
  fastQuery = FALSE
)

Arguments

ssimObject	`SsimLibrary`, `Project`, or `Scenario` object or list of objects. Note that all objects in a list must be of the same type, and belong to the same SsimLibrary
name	character or character vector. Sheet name(s). If `NULL` (default), all datasheets in the ssimObject will be returned. Note that setting `summary=FALSE` and `name=NULL` pulls all Datasheets, which is time consuming and not generally recommended
project	numeric or numeric vector. One or more `Project` ids
scenario	numeric or numeric vector. One or more `Scenario` ids
summary	logical or character. If `TRUE` (default) returns a data.frame of sheet names and other info. If `FALSE` returns data.frame or list of data.frames. If `"CORE"` returns data.frame of sheet names and other info including built-in core SyncroSim Datasheets
optional	logical. If `summary=TRUE` and `optional=TRUE` returns only `scope`, `name` and `displayName`. If `summary=FALSE` and `optional=TRUE` returns all of the Datasheet's columns, including the optional columns. If `summary=TRUE`, `optional=FALSE` (default), returns only those columns that are mandatory and contain data (if `empty=FALSE`). Ignored if `summary=FALSE`, `empty=FALSE` and `lookupsAsFactors=FALSE`
empty	logical. If `TRUE` returns empty data.frames for each Datasheet. Ignored if `summary=TRUE` Default is `FALSE`
filterColumn	character string. The column to filter a Datasheet by. (e.g. "TransitionGroupID"). Note that to use the filterColumn argument, you must also specify the filterValue argument. Default is `NULL`
filterValue	character string or integer. The value to filter the filterColumn by. To use the filterValue argument, you must also specify the filterColumn argument. Default is `NULL`
lookupsAsFactors	logical. If `TRUE` (default) dependencies returned as factors with allowed values (levels). Set `FALSE` to speed calculations. Ignored if `summary=TRUE`
sqlStatement	list returned by `sqlStatement`. `SELECT` and `GROUP BY` SQL statements passed to SQLite database. Ignored if `summary=TRUE` (optional)
includeKey	logical. If `TRUE` include primary key in table. Default is `FALSE`
forceElements	logical. If `FALSE` (default) and name has a single element returns a data.frame; otherwise returns a list of data.frames. Ignored if `summary=TRUE`
fastQuery	logical. If `TRUE`, the request is optimized for performance. Ignored if combined with summary, empty, or `sqlStatement` flags. Default is `FALSE`

Value

If summary=TRUE or summary="CORE" returns a data.frame of Datasheet names and other information, otherwise returns a data.frame or list of these.

Details

If summary=TRUE or summary=NULL and name=NULL a data.frame describing the Datasheets is returned. If optional=TRUE, columns include: scope, package, name, displayName, isSingle, isOutput, data. data only displayed for a SyncroSim Scenario. dataInherited and dataSource columns added if a Scenario has dependencies. If optional=FALSE, columns include: scope, name, displayName. All other arguments are ignored.

Otherwise, for each element in name a Datasheet is returned as follows:

If lookupsAsFactors=TRUE (default): Each column is given the correct data type, and dependencies returned as factors with allowed values (levels). A warning is issued if the lookup has not yet been set.
If empty=TRUE: Each column is given the correct data type. Fast (1 less console command).
If empty=FALSE and lookupsAsFactors=FALSE: Column types are not checked, and the optional argument is ignored. Fast (1 less console command).
If SsimObject is a list of Scenario or Project objects (output from run, Scenario or Project): Adds ScenarioID/ProjectID column if appropriate.
If Scenario/Project is a vector: Adds ScenarioID/ProjectID column as necessary.
If requested Datasheet has Scenario scope and contains info from more than one Scenario: ScenarioID/ScenarioName/ScenarioParent columns identify the Scenario by name, id, and parent (if a result Scenario).
If requested Datasheet has Project scope and contains info from more than one Project: ProjectID/ProjectName columns identify the Project by name and id

Examples

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

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

# Set the SyncroSim Session
mySession <- session()

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

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

# Can get same info using Project and Scenario arguments
myDatasheets <- datasheet(myLibrary, project = 1, scenario = 1)

# Return a list of data.frames (1 for each Datasheet)
myDatasheetList <- datasheet(myScenario, summary = FALSE)

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

# Include primary key when retrieving a Datasheet
myDatasheet <- datasheet(myScenario, name = "RunControl", includeKey = TRUE)

# Return all columns, including optional ones
myDatasheet <- datasheet(myScenario, name = "RunControl", summary = TRUE, 
                         optional = TRUE)

# Return Datasheet as an element
myDatasheet <- datasheet(myScenario, name = "RunControl", forceElements = TRUE)
myDatasheet$helloworldSpatial_RunControl
#>   MinimumIteration MaximumIteration MinimumTimestep MaximumTimestep
#> 1                1                5               1              20

# Get a Datasheet without pre-specified values
myDatasheetEmpty <- datasheet(myScenario, name = "RunControl", empty = TRUE)

# If Datasheet is empty, do not return dependencies as factors
myDatasheetEmpty <- datasheet(myScenario, name = "RunControl", empty = TRUE,
                              lookupsAsFactors = FALSE)
                              
# Optimize query
myDatasheet <- datasheet(myScenario, name = "RunControl", fastQuery = TRUE)

# Get all the SsimLibrary core Datasheet info
myDatasheets <- datasheet(myLibrary, summary = "CORE")

# Get specific SsimLibrary core Datasheet
myDatasheet <- datasheet(myLibrary, name = "core_Backup")

# Use an SQL statement to query a Datasheet
mySQL <- sqlStatement(
  groupBy = c("ScenarioID"),
  aggregate = c("MinimumTimestep"),
  where = list(MinimumTimestep = c(1))
)
myAggregatedDatasheet <- datasheet(myScenario, name = "RunControl",
                                   sqlStatement = mySQL)
# }