Introduction to esqlabsR

The esqlabsR R-package is designed to facilitate and standardize modeling and simulation (M&S) of PBPK and QSP models implemented in Open Systems Pharmacology Software (OSPS) and executed from R. The package provides functions to read and run scenarios, workflows and simulations and create plots and visualization based on no-code input from Excel files. The package is based on R functions in the ospsuite package.

Motivation

This package builds up on the functionality of the ospsuite package. It is strongly recommended to get familiar with the R Introduction. Functions reference for the ospsuite can be found here, while articles describing the usage of the package with examples are found here.

In order to load a simulation in R, it must be present in the *.pkml file format. Every simulation in PK-Sim or MoBi can be exported to the *.pkml file. The examples shown in this documentation are based on the Aciclovir example model, until stated otherwise. The model can be found in the GitHub repository as PK-Sim project. The pkml file can be downloaded from ospsuite-r repository.

The articles below cover several aspects of the software usage:

• Standard workflow
• Data handling
• Visualization and reporting
• Available Shiny apps

Object-oriented approach

The esqlabsR package utilizes the concept of object-oriented (OO) programming based on the R6 system. While the philosophy of the package is to offer a functional programming workflow more common for the R users, it is important to understand some basic concepts of the OO programming. Many of the functions implemented in esqlabsR return an instance (or an object) of a class. These objects can be used as inputs for other methods. Additionally, each object offers a set of properties (which can be other objects) and methods, which are accessible by the $ character:

# create an instance of an object
object1 <- ClassName$new()

# extract a property associated with this object
aProperty <- object1$property1

# apply a method associated with this object
resultOfAFunction <- object1$multiply(1,2)

Important information about the object can be printed out by calling print(object).

Configuring a project with no-code Excel files

To facilitate modeling activities in a team with diverse backgrounds, esqlabsR employs Excel configuration files that define every aspect of a modeling project. The modeling projects are expected to follow a strict folder structure:

• the Code/ProjectConfiguration.xlsx file is a cornerstone Excel file that stores relative paths to all project components, including modeling scenarios, data files and parameter files. This Excel file is expected to contain fields that populate an instance of a ProjectConfiguration class.
• by default, the Code folder contains R script files
• by default, the Data folder contains Excel files with observed data
• by default, the Parameters folder contains Excel files with global, population and individual model parameters, definitions of application protocols and modeling scenarios.

An exemplary project folder including the subfolders and files mentioned above can be found in the /tests/data/TestProject folder of the {esqlabsr} repository.