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 )
ssimObject |
|
---|---|
name | character or character vector. Sheet name(s). If |
project | numeric or numeric vector. One or more
|
scenario | numeric or numeric vector. One or more
|
summary | logical or character. If |
optional | logical. If |
empty | logical. If |
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 |
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 |
lookupsAsFactors | logical. If |
sqlStatement | list returned by |
includeKey | logical. If |
forceElements | logical. If |
fastQuery | logical. If |
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.
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
# \donttest{ # Install helloworldSpatial package from package server addPackage("helloworldSpatial")#># 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")#># 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) # }