Create scenario configurations from PKML files — createScenarioConfigurationsFromPKML • esqlabsR

Creates scenario configurations from PKML files by extracting available information such as applications, output paths, and simulation time settings. This function creates scenario configuration objects that can be used with the esqlabsR workflow.

Usage

createScenarioConfigurationsFromPKML(
  pkmlFilePaths,
  projectConfiguration,
  scenarioNames = NULL,
  individualId = NULL,
  populationId = NULL,
  applicationProtocols = NULL,
  paramSheets = NULL,
  outputPaths = NULL,
  simulationTime = NULL,
  simulationTimeUnit = NULL,
  steadyState = FALSE,
  steadyStateTime = NULL,
  steadyStateTimeUnit = NULL,
  readPopulationFromCSV = FALSE
)

Arguments

pkmlFilePaths: Character vector of paths to PKML files to create scenarios from.
projectConfiguration: A ProjectConfiguration object holding base information.
scenarioNames: Character vector. Optional custom names for the scenarios. If NULL (default), scenario names will be extracted from the simulation names in the PKML files. If provided, must have the same length as pkmlFilePaths.
individualId: Character string. Optional individual ID to use for all scenarios. If NULL (default), no individual will be specified.
populationId: Character string. Optional population ID to use for all scenarios. If NULL (default), no population will be specified. If provided, sets simulation type to "Population".
applicationProtocols: Character vector. Optional application protocol names to use for scenarios. If NULL (default), application protocols will be set to the scenario name. If provided, can be a single string (applied to all scenarios) or a vector with the same length as pkmlFilePaths.
paramSheets: Character vector. Optional parameter sheet names to apply to scenarios. If NULL (default), no parameter sheets will be applied.
outputPaths: Character vector. Optional output paths to use for scenarios. If NULL (default), output paths will be extracted from the PKML files' output selections.
simulationTime: Character string. Optional simulation time to use for scenarios as character string containing one or multiple time intervals separated by a ';'. Each time interval is a triplet of values <StartTime, EndTime, Resolution>, where Resolution is the number of simulated points per time unit defined in the simulationTimeUnit. If NULL (default), simulation time will be extracted from the PKML files' output schema intervals.
simulationTimeUnit: Character string. Optional simulation time unit. Only used when simulationTime is provided. If NULL (default), will be extracted from the PKML file's output schema intervals, or set to "min" (minutes) if not available.
steadyState: Logical. Whether to simulate steady-state. Default is FALSE.
steadyStateTime: Numeric. Steady-state time. Only used when steadyState = TRUE. If NULL (default), no steady-state time will be set.
steadyStateTimeUnit: Character string. Steady-state time unit. Only used when steadyState = TRUE and steadyStateTime is provided. If NULL (default), "min" will be used.
readPopulationFromCSV: Logical. Whether to read population from CSV. Default is FALSE.

Value

A named list of ScenarioConfiguration objects with the names being the scenario names.

Details

This function extracts the following information from PKML files:

Applications: Application protocol names (defaults to scenario name).
Output paths: All selected outputs for the simulation from outputSelections$allOutputs.
Simulation time: Time intervals with start time, end time, and resolution from outputSchema$intervals.
Simulation time unit: Time unit from the output schema intervals (e.g., "h" for hours).

The function handles duplicate scenario names by appending indices (e.g., "Scenario_1", "Scenario_2"). It creates scenario configurations but does not write them to Excel files. Use addScenarioConfigurationsToExcel() to add the scenarios to the project's Excel files.

Examples

if (FALSE) { # \dontrun{
# Create default project configuration
projectConfiguration <- createDefaultProjectConfiguration()

# Create scenarios from a single PKML file
pkmlPath <- "path/to/simulation.pkml"
scenarios <- createScenarioConfigurationsFromPKML(
  pkmlFilePaths = pkmlPath,
  projectConfiguration = projectConfiguration
)

# Add scenarios to Excel configuration
addScenarioConfigurationsToExcel(
  scenarioConfigurations = scenarios,
  projectConfiguration = projectConfiguration
)

# Create scenarios from multiple PKML files with custom names
pkmlPaths <- c("path/to/sim1.pkml", "path/to/sim2.pkml")
scenarios <- createScenarioConfigurationsFromPKML(
  pkmlFilePaths = pkmlPaths,
  projectConfiguration = projectConfiguration,
  scenarioNames = c("Scenario1", "Scenario2")
)

# Add multiple scenarios to configuration
addScenarioConfigurationsToExcel(
  scenarioConfigurations = scenarios,
  projectConfiguration = projectConfiguration
)
} # }