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,
  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,
  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,
  lookupsAsFactors,
  sqlStatement,
  includeKey,
  fastQuery
)

# S4 method for SsimObject
datasheet(
  ssimObject,
  name = NULL,
  project = NULL,
  scenario = NULL,
  summary = NULL,
  optional = FALSE,
  empty = FALSE,
  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

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) # }