{esqlabsR} What ?

{esqlabsR} Why ?

• Simple functions to design, run and save simulations,
• Interact with the {ospsuite} features using Excel files,
• Generate standardized plots automatically.

{esqlabsR} Where ?

• Code repository: github.com/esqLABS/esqlabsR

• Documentation: esqlabs.github.io/esqlabsR/

• Get Started Tutorial

{esqlabsR} How ?

install.packages("pak")

pak::pak("esqLABS/esqlabsR*release")

{esqlabsR} How ?

Project Structure

library(esqlabsR)
initProject()

initProject() will create the expected simulation project’s folder structure.

Project Structure

Each one of these folders contains a series of .xlsx files with specific purpose.

my_project
├── ProjectConfiguration.xlsx
├── ProjectConfiguration.json
├── Configurations
│   ├── Applications.xlsx
│   ├── Individuals.xlsx
│   ├── ModelParameters.xlsx
│   ├── Plots.xlsx
│   ├── Populations.xlsx
│   ├── PopulationsCSV
│   │   └── TestPopulation.csv
│   └── Scenarios.xlsx
├── Data
├── Models
│   └── Simulations
│       └── Aciclovir.pkml
└── Results
    ├── Figures
    └── SimulationResults

Project Structure

Project’s files are linked by the ProjectConfiguration.xlsx file.

my_project
├── ProjectConfiguration.xlsx
├── ProjectConfiguration.json
├── Configurations
│   ├── Applications.xlsx
│   ├── Individuals.xlsx
│   ├── ModelParameters.xlsx
│   ├── Plots.xlsx
│   ├── Populations.xlsx
│   ├── PopulationsCSV
│   │   └── TestPopulation.csv
│   └── Scenarios.xlsx
├── Data
├── Models
│   └── Simulations
│       └── Aciclovir.pkml
└── Results
    ├── Figures
    └── SimulationResults

Project Structure

Everything is already configured !

ProjectConfiguration

• targets ProjectConfiguration.xlsx file,
• creates a ProjectConfiguration object,
• Needed for all next steps !

my_project_configuration <-
  createProjectConfiguration(path = "path/to/ProjectConfiguration.xlsx")

ProjectConfiguration

my_project_configuration

ProjectConfiguration:
Project Configuration File: TestProject/ProjectConfiguration.xlsx
Model folder: TestProject/Models/Simulations
Configurations folder: TestProject/Configurations
Model parameters file: TestProject/Configurations/ModelParameters.xlsx
Individuals file: TestProject/Configurations/Individuals.xlsx
...

Version Control & Project Sharing

JSON Snapshots for version control and team collaboration

# Create snapshot
snapshotProjectConfiguration("ProjectConfiguration.xlsx")

# Restore from snapshot
restoreProjectConfiguration("ProjectConfiguration.json")

• Text-based format (Git-friendly)
• Easy team collaboration
• Reproducible project setup

Scenarios

Simulations are defined by Scenarios.

Scenarios parameterization

• Model
• Model parameters
• Application protocol
• Time range
• Individual characteristics
• Population
• …

Parameters files

flowchart TD
    Scenarios["`**Scenarios.xlsx**
    • ModelFile
    • ModelParametersSheets
    • ApplicationProtocol
    • IndividualId
    • PopulationId`"]

    Models["`**Models/**
    • Model1.pkml
    • Model2.pkml`"]

    ModelParams["`**ModelParameters.xlsx**
    ModelParametersSheets...
    • ContainerPath
    • Parameter Name
    • Value
    • Units`"]

    Applications["`**Applications.xlsx**
    ApplicationProtocol...
    • ContainerPath
    • Parameter Name
    • Value
    • Units`"]

    Individuals["`**Individuals.xlsx**
    IndividualBiometrics
    IndividualId...
    • ContainerPath
    • Parameter Name
    • Value
    • Units`"]

    Populations["`**Populations.xlsx**
    Demographics
    PopulationId...
    • ContainerPath
    • Parameter Name
    • Mean
    • SD
    • Distribution`"]

    Scenarios -->|ModelFile| Models
    Scenarios -->|ModelParametersSheets| ModelParams
    Scenarios -->|ApplicationProtocol| Applications
    Scenarios -->|IndividualId| Individuals
    Scenarios -->|PopulationId| Populations

    style Scenarios fill:#e1f5e1,stroke:#4caf50,stroke-width:3px
    style Models fill:#fff9c4,stroke:#fbc02d,stroke-width:2px
    style ModelParams fill:#e1f5e1,stroke:#4caf50,stroke-width:2px
    style Applications fill:#e1f5e1,stroke:#4caf50,stroke-width:2px
    style Individuals fill:#e1f5e1,stroke:#4caf50,stroke-width:2px
    style Populations fill:#e1f5e1,stroke:#4caf50,stroke-width:2px

Read Scenarios

my_scenarios <- createScenarios(
  readScenarioConfigurationFromExcel(
    scenarioNames = "TestScenario",
    projectConfiguration = my_project_configuration
  )
)

Scenarios Recap

my_scenarios

<ScenarioConfiguration>

── Scenario configuration ──────────────────────────────────────────────────────
  • Scenario name: TestScenario
  • Model file name: Aciclovir.pkml
  • Application protocol: Aciclovir_iv_250mg
  • Simulation type: Individual
  • Individual Id: Indiv1
  • Population Id: NULL
  • Read population from csv file: FALSE
  • Parameters sheets: Global
  • Simulate steady-state: FALSE
  • Steady-state time: 1000

── Simulation time intervals ──

Interval 1:
  • Start: 0
  • End: 24
  • Resolution: 60
  • Simulation time intervals unit: h

Run Simulations

myScenarioResults <- runScenarios(my_scenarios)

{ospsuite} plotting functions

Simulation results are compatible with {ospsuite} plotting workflow.

my_datacombined <- DataCombined$new()

my_datacombined$addSimulationResults(myScenarioResults$TestScenario$results,
  names = "Simulated",
  groups = "Aciclovir"
)

{ospsuite} plotting functions

plotIndividualTimeProfile(my_datacombined)

Create Plots from Excel

plots <- createPlotsFromExcel(
  projectConfiguration = my_project_configuration
)

Help us improve esqlabsR