Create or open Scenario(s) — scenario • rsyncrosim

Create or open one or more Scenarios from a SsimLibrary.

scenario(
  ssimObject = NULL,
  scenario = NULL,
  sourceScenario = NULL,
  summary = NULL,
  results = FALSE,
  forceElements = FALSE,
  overwrite = FALSE
)

Arguments

ssimObject	`SsimLibrary` or `Project` object, or character (i.e. a filepath)
scenario	character, integer, or vector of these. Names or ids of one or more Scenarios. Note integer ids are slightly faster, but can only be used to open existing Scenarios
sourceScenario	character or integer. If not `NULL` (Default), new Scenarios will be copies of the sourceScenario
summary	logical. If `TRUE` then loads and returns the Scenario(s) in a named vector/dataframe with the scenarioId, name, description, owner, dateModified, readOnly, parentID. Default is `TRUE` if `scenario=NULL`, `FALSE` otherwise
results	logical. If `TRUE` only return result Scenarios. Default is `FALSE`
forceElements	logical. If `TRUE` then returns a single Scenario as a named list; if `FALSE` (default), returns a single Scenario as a `Scenario` object. Applies only when `summary=FALSE`
overwrite	logical. If `TRUE` an existing Scenario will be overwritten. Default is `FALSE`

Value

A Scenario object representing a SyncroSim scenario, a list of Scenario objects, or a data frame of Scenario names and descriptions. If summary = FALSE, returns one or more Scenario objects representing SyncroSim Scenarios. If summary = TRUE, returns Scenario summary info.

Details

For each element of Scenario:

If element/Project/SsimObject uniquely identifies an existing Scenario: Returns the existing Scenario.
If element/Project/SsimObject uniquely identifies more than one existing Scenario: Error.
If element/Project/SsimObject do not identify an existing Scenario or Project: Error.
If element/Project/SsimObject do not identify an existing Scenario and element is numeric: Error - a name is required for new Scenarios. SyncroSim will automatically assign an id when a Scenario is created.
If element/Project/SsimObject do not identify an existing Scenario and do identify a Project, and element is a character string: Creates a new Scenario named element in the Project. SyncroSim automatically assigns an id. If sourceScenario is not NULL the new Scenario will be a copy of sourceScenario.

Examples

# \donttest{
# Set the file path and name of the new SsimLibrary
myLibraryName <- file.path(tempdir(),"testlib")

# Set the SyncroSim Session, SsimLibrary, and Project
mySession <- session()
myLibrary <- ssimLibrary(name = myLibraryName, session = mySession) 
myProject <- project(myLibrary, project = "My Project")

# Create a new Scenario
myScenario <- scenario(myProject, scenario = "My Scenario")


# Create a new Scenario from an existing Scenario
myScenarioCopy <- scenario(myProject, scenario = "My Scenario Copy",
                           sourceScenario = myScenario)
                          
# Find all the Scenarios in a SsimLibrary
scenario(myLibrary)
#>   scenarioId projectId             name isResult parentID owner
#> 1          1        14 My Scenario Name       No       NA   N/A
#> 2          2        14  my New Scenario       No       NA   N/A
#> 3          3        14      My Scenario       No       NA   N/A
#> 4          4        27      My Scenario       No       NA   N/A
#> 5          5        27 My Scenario Copy       No       NA   N/A
#>            lastModified readOnly mergeDependencies
#> 1 2021-11-03 at 2:33 PM       No               Yes
#> 2 2021-11-03 at 2:33 PM       No                No
#> 3 2021-11-03 at 2:34 PM      Yes                No
#> 4 2021-11-03 at 2:35 PM       No                No
#> 5 2021-11-03 at 2:35 PM       No                No
#>                        ignoreDependencies autoGenTags
#> 1 stsim_RunControl,stsim_TransitionTarget          NA
#> 2                                                  NA
#> 3                                                  NA
#> 4                                                  NA
#> 5                                                  NA

# Only return the results Scenarios for a SsimLibrary
scenario(myLibrary, results = TRUE)
#>  [1] scenarioId         projectId          name               isResult          
#>  [5] parentID           owner              lastModified       readOnly          
#>  [9] mergeDependencies  ignoreDependencies autoGenTags       
#> <0 rows> (or 0-length row.names)

# Overwrite an existing Scenario
myNewScenario <- scenario(myProject, scenario = "My New Scenario", 
                         overwrite = TRUE)
# }