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
)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
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
numeric or numeric vector. One or more
Project ids
numeric or numeric vector. One or more
Scenario ids
logical or character. If TRUE (default) returns a data.frame of sheet names
and other info including built-in core SyncroSim Datasheets. If FALSE returns
data.frame or list of data.frames.
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
logical. If TRUE returns empty data.frames for each
Datasheet. Ignored if summary=TRUE Default is FALSE
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
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
logical. If TRUE (default) dependencies
returned as factors with allowed values (levels). Set FALSE to speed
calculations. Ignored if summary=TRUE
list returned by sqlStatement. SELECT and
GROUP BY SQL statements passed to SQLite database. Ignored if
summary=TRUE (optional)
logical. If TRUE include primary key in table. Default is
FALSE
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
logical. If TRUE, the request is optimized for
performance. Ignored if combined with summary, empty, or
sqlStatement flags. Default is FALSE
If summary=TRUE 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")
#> 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",
forceUpdate = TRUE)
#> Scenarios available in this template:
# 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)
# 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 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)
# }