Skip to contents

Standard workflow

Source: vignettes/standard-workflow.Rmd
standard-workflow.Rmd

Defining scenarios

Within the esqlabsR framework, the simulations are run by defining and executing multiple scenarios. A scenario is defined by the simulation file containing the model structure, parametrization of the model, application protocol, and (optionally) the physiology of the simulated individual or population. To simplify scenarios set up, all these information are stored in excel files with defined structure.

Information about location of scenario definition files, simulation files, output folders etc. is stored in excel file ProjectConfiguration.xlsx located in the folder Code. Usually it is not required to edit the contents of this file.

The first step in the workflow is to create a ProjectConfiguration from this file that will be used by the scripts to know where to find the required data (for all following examples, we assume that the current working directory is the Code folder):

projectConfiguration <- createDefaultProjectConfiguration()
print(projectConfiguration)
#> ProjectConfiguration: 
#>    Model folder: ../Models/Simulations 
#>    Parameters folder: ../Parameters 
#>    Parameters file name: ModelParameters.xlsx 
#>    Individual parameters file name: IndividualParameters.xlsx 
#>    Individual physiology file name: IndividualPhysiology.xlsx 
#>    Population parameters file name: PopulationParameters.xlsx 
#>    Scenario definitions file name: Scenarios.xlsx 
#>    Scenario applications definitions file name: ApplicationParameters.xlsx 
#>    Experimental data folder: ../Data 
#>    Experimental data file: TestProject_TimeValuesData.xlsx 
#>    Data importer configuration: esqlabs_dataImporter_configuration.xml 
#>    Output folder: ../Results 
#>    Output device:

Next, we will define a scenario that we want to simulate in the excel file Parameters/Scenarios.xlsx (or other as set in projectConfiguration$scenarioDefinitionFile). The package includes an example scenario that models the administration of a single dose of 250 mg aciclovir intravenously to an individual with a 90 ml/min estimated glomerular filtration rate. To define a scenario, create a new row in the Scenarios.xlsx file with the following content:

  • Scenario_name: unique name of the scenario. The name must be a valid R variables name.

  • IndividualId: Name (ID) of an individual. This name refers to the name of the individual as used in excel files IndividualPhysiology.xlsx for definition of the biometric properties of the simulated individual and IndividualParameters.xlsx for definition of individual-specific model parameters. IndividualId may be empty. In this case, standard individual as defined in the pkml simulation without any individual-specific model parameters will be simulated. To create an individual with specific biometric characteristics, define an entry with the same individual id in the file IndividualPhysiology.xlsx. The same individual can be used in multiple scenarios. Note that though it is technically possible to apply a species different from the one in the original simulation, the correctness of the results is not guaranteed as there exist some structural differences between the species.

  • ModelParameterSheets: A list of sheet names from the ModelParameter.xlsx file, separated by a ,. Each sheet must have the columns Container Path, Parameter Name, Value, and Units. Parameter values from specified sheets will be applied to the model in the order of their definition. E.g., if we define Global, Aciclovir, then parameters from the Aciclovir sheet will be applied after the Global parameters. ModelParameterSheets may be empty or specify as many sheets as required. Note that the specified sheets must be present in the ModelParameter.xlsx file. The purpose of this approach is to have global parameters that can be applied to most scenarios, and separate set of parameters for e.g. different disease states (parameter sheets Healthy and CKD), or separate parametrization of different compounds (sheet Aciclovir).
    We can further refine the parametrization of the scenario by specifying the individual parameters in the IndividualParameters.xlsx file. Create a sheet with the name as the IndividualId specified for the respective scenario and populate it the same structure as the ModelParameters.xlsx file. This way we can define e.g. individual-specific clearance values or, as in our case, the glomerular filtration rate. Individual specific parameters are applied after the parameters defined in the ModelParameterSheets. We can use an individual in multiple scenarios. If an individual is specified in the scenario definition, but no sheet with this name exists in the IndividualParameters.xlsx file, this step is simply ignored.

  • ApplicationProtocol: name of the application protocol that will be applied. Applications are defined as a set of parameters that will be applied to the model in the file ApplicationParameters.xlsx. For each application, create a sheet with the name as specified in the ApplicationProtocol entry and populate it with the same structure as the ModelParameter.xlsx file… Configuring application protocols this way requires that the loaded simulation includes all possible applications that can be turned on and off by setting parameters, e.g. the Dose or Start time parameters. As it might be cumbersome to manually create entries for all administration parameters, we can use the getAllApplicationParameters() function to get a list of all (constant) parameters located in the Applications container. In the following example, we will extract application parameters for the molecule Aciclovir from the example simulation:

sim <- loadSimulation(system.file("extdata", "Aciclovir.pkml", package = "ospsuite"))
applicationParams <- getAllApplicationParameters(sim)
print(applicationParams)
#> [[1]]
#> Parameter: 
#>    Path: Applications|IV 250mg 10min|Application_1|ProtocolSchemaItem|Start time 
#>    Value: 0.00 [min] 
#>    isConstant: TRUE 
#>    isStateVariable: FALSE 
#> 
#> [[2]]
#> Parameter: 
#>    Path: Applications|IV 250mg 10min|Application_1|ProtocolSchemaItem|Dose 
#>    Value: 0.00 [kg] 
#>    isConstant: TRUE 
#>    isStateVariable: FALSE 
#> 
#> [[3]]
#> Parameter: 
#>    Path: Applications|IV 250mg 10min|Application_1|ProtocolSchemaItem|DosePerBodySurfaceArea 
#>    Value: 0.00 [kg/dm²] 
#>    isConstant: TRUE 
#>    isStateVariable: FALSE 
#> 
#> [[4]]
#> Parameter: 
#>    Path: Applications|IV 250mg 10min|Application_1|ProtocolSchemaItem|DosePerBodyWeight 
#>    Value: 0.00 [kg/kg] 
#>    isConstant: TRUE 
#>    isStateVariable: FALSE 
#> 
#> [[5]]
#> Parameter: 
#>    Path: Applications|IV 250mg 10min|Application_1|ProtocolSchemaItem|Infusion time 
#>    Value: 10.00 [min] 
#>    isConstant: TRUE 
#>    isStateVariable: FALSE

and export the parameters to an excel file using the exportParametersToXLS() function:

exportParametersToXLS(parameters = applicationParams, paramsXLSpath = "../Applications.xlsx")

The created excel file will have the same structure as all Parameter-files and can be directly loaded in MoBi or R using the readParametersFromXLS() function.

  • SimulationTime: Time of the simulation. The output interval of the simulation will be set to the range [0 - SimulationTime] with the resolution of 1 point per minute.

  • SimulationTimeUnit: Unit for SimulationTime. For supported units, see ospsuite::ospUnits.

  • SteadyState: If TRUE, the model will be simulated for a “sufficiently long” time (1000 minutes by default). The steady-state time can be specified in the ScenarioConfiguration (see Section Running scenarios).

  • ModelFile: Name of the pkml file with the simulation. Must be located in the folder defined in ProjectConfiguration$modelFolder.

Code-based specifications

In addition to scenario set ups through the excel sheets, further specifications are made in the R files located in the InputCode project folder. Files in this folder must be sourced prior to using.

  • OutputPaths: You can specify the output paths (i.e., paths to the molecules/ parameters for which outputs will be simulated) for each scenario separately (see Section Running scenarios). For more convenient access to the paths, you can specify all paths in the OutputPaths enum (an enum is just a named list) and easily access them by their alias names (e.g. Aciclovir_PVB for "Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood)").

  • TestParameters: During model development/fitting phase, you might want to test out parameter values before storing them in the Parameters excel files. You can define the paths of the parameters, their values and the units in the TestParameters file. Remember to source the file each time you change any values. You can turn setting test parameters on and off in the ScenarioConfiguration (see Section Running scenarios).

Running scenarios

Scenarios are executed by creating ScenarioConfiguration objects and calling the runScenarios()function. Though it is possible to create an empty ScenarioConfiguration and populate it by hand, we usually want to create scenario configurations from the excel files by calling the readScenarioConfigurationFromExcel() function. A ScenarioConfiguration is based on the ProjectConfiguration, which has to be provided as an argument to the function. To read the configuration for the ‘TestScenario’ scenario defined in the Scenarios.xlsx file, we call

# Create `ScenarioConfiguration` objects from excel files
scenarioConfigurations <- readScenarioConfigurationFromExcel(
  scenarioNames = "TestScenario",
  projectConfiguration = projectConfiguration
)

print(scenarioConfigurations$TestScenario)
#> ProjectConfiguration: 
#>    Model folder: ../Models/Simulations 
#>    Parameters folder: ../Parameters 
#>    Parameters file name: ModelParameters.xlsx 
#>    Individual parameters file name: IndividualParameters.xlsx 
#>    Individual physiology file name: IndividualPhysiology.xlsx 
#>    Population parameters file name: PopulationParameters.xlsx 
#>    Scenario definitions file name: Scenarios.xlsx 
#>    Scenario applications definitions file name: ApplicationParameters.xlsx 
#>    Experimental data folder: ../Data 
#>    Experimental data file: TestProject_TimeValuesData.xlsx 
#>    Data importer configuration: esqlabs_dataImporter_configuration.xml 
#>    Output folder: ../Results 
#>    Output device: 
#> ScenarioConfiguration: 
#>    Model file name: Aciclovir.pkml 
#>    Scenario name: TestScenario 
#>    Parameters sheets: Global 
#>    Individual Id: Indiv1 
#>    Application protocol: Aciclovir_iv_250mg 
#>    Simulation time: 1440 
#>    Points per minute: 1 
#>    Simulate steady-state: FALSE 
#>    Steady-state time: 1000 
#>    Set test parameters: FALSE

Before running the scenarios, we can modify ScenarioConfigurations by setting parameters that are currently not accessible through excel files. One the most common property is $outputPaths that define for which paths the results will be stored.

# Define the OutputPaths enum, if not done allready
OutputPaths <- enum(list(
  Aciclovir_PVB = "Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood)"
))

# Set output paths for each scenario
for (scenarioConfiguration in scenarioConfigurations) {
  scenarioConfiguration$outputPaths <- enumValues(OutputPaths)
}

In model development/fitting phase, we also might want to apply some test parameter values:

# Set output paths for each scenario
for (scenarioConfiguration in scenarioConfigurations) {
  scenarioConfiguration$setTestParameters <- TRUE
}

Make sure that you have sourced the TestParameters file in this case.

Once all scenario configurations are set up, we can simulate them by calling the runScenarios() function. We can specify to save the initialized simulation (i.e. the simulation with individual physiology and parametrization applied as defined by the scenario configuration). In such case, a folder with the current date and time will be created in the folder where the simulation pkml files are located.

simulatedScenarios <- runScenarios(
  scenarioConfigurations = scenarioConfigurations,
  customParams = NULL, saveSimulationsToPKML = FALSE
)

names(simulatedScenarios)
#> [1] "TestScenario"

The function returns results of the simulations. For each scenario, a Simulation object, a SimulationResults object, and vectors of output values (retrieved by the getOutputValues() function) are returned.

Troubleshooting

More detailed information on function signatures can be found in: