Introduction to ospsuite • ospsuite

The ospsuite R-package is part of the Open Systems Pharmacology Software (OSPS), an open-source suite of modeling and simulation tools for pharmaceutical and other life-sciences applications. This package provides the functionality of loading, manipulating, and simulating the simulations created in the software tools PK-Sim and MoBi. This document gives an overview of the general workflow and the most important methods.

General information

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. Unless otherwise stated, the examples shown in the vignettes are based on the Aciclovir example model. The model can be found in the PK-Sim examples folder of the OSPS installation.

The general workflow with the ospsuite package can be summarized in following steps:

Loading a simulation from .pkml file.
Accessing entities of the simulation, such as molecules, parameters, or containers, and reading information about them.
Changing simulation settings, parameter values, and molecules start values.
Retrieving the results and processing them.

The workflow steps are described in the following vignettes:

Some aspects of the ospsuite package may appear uncommon for the users not familiar with the object-oriented approach. It is recommended to read the following section to better understand some semantics and to get the most of the flexibility and efficiency of the package.

Object-oriented approach

The ospsuite R-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.

Most of the functions implemented in ospsuite return an instance (or an object) of a class. These objects can be used as inputs for other functions. Additionally, each object offers a set of properties (which can be themselves other objects) and functions, accessible by the $ sign:

object1           <- ClassName$new()
aProperty         <- object1$property1
resultOfAFunction <- object1$multiply(1,2)

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

The most important classes are:

Simulation: Representation of the simulation loaded from the *.pkml file.

SimulationRunOptions: An object defining the options of a simulation run. The options are: numberOfCores the maximal number of (logical) cores that can be used by the (population) simulation; checkForNegativeValues a boolean defining if an error if thrown if some variables become negative for which the "negativeValuesAllowed"-flag is set to FALSE (can be used to ignore numerical noise); showProgress a Boolean if a “progress bar” is shown in the console representing the progress of the simulation.

SolverSettings: Object defining the settings of the solver. Stored in SimulationSettings of a Simulation (accessibly by field $settings).

OutputSchema: Definition of the output intervals of the simulation. The OutputSchema defines the total simulation time and the time points at which results are generated. Can be accessed as property of a Simulation-object.

OutputSelections: List of quantities (parameters and molecules) for which the outputs will be generated. Can be accessed as property of a Simulation-object.

SimulationResults: Results of a simulation, either individual or population. Holds the simulated values for all quantities defined in the OutputSelections. See Running a simulation for more information.

Entity: Every accessible distinct part of the model. Most prominent entities are Molecule, Parameter, Container. Every Entity has properties $path representing the path within the model structure and $parentContainer being the container this entity is located in.

Container: A Container is an element of model structure that contains other entities (e.g., spatial containers, molecules, parameters). The most prominent containers are organs and compartments. A loaded Simulation is also a container.

Quantity: An Entity in the simulation that has a value - namely Molecule and Parameter. Every Quantity has a $value and a $dimension. Further important fields are $unit, which is the base unit of the dimension. See Dimensions and Units for more information.

Molecule: A molecule located in a Container. The $value-property refers to the initial value in the simulation. Inherits from Quantity.

Parameter: A parameter. The $value-property refers to the initial value in the simulation. Inherits from Quantity.

Formula: The value of each Quantity is described by a $formula-property. There are different types of formulae, see Changing parameter and molecule start values for more information.

IndividualCharacteristics: An object used for creating of individual parameter sets with the createIndividual-method. See Creating individuals for more information.

Population: An object describing a virtual population. Can be either loaded from a *.csv-file created by PK-Sim or created with the createPopulation-method. See Population simulations for more information.

PopulationCharacteristics: An object used for creating of population parameter sets with the createPopulation-method. See Population simulations for more information.

SimulationPKAnalyses: PK analyses for a simulations result.

QuantityPKParameter: A certain PK parameter for an output quantity. Has the fields $name which is the name of the PK parameter (e.g. “C_max”), $quantityPath the path of the output the parameter has been calculated for, and $values the value (or list of values for a population simulation).

SensitivityAnalysis: A class defining the analysis of which input parameters have most impact on the output curves of a simulation. See Sensitivity analysis for more information.

SensitivityAnalysisResults: Results of running the SensitivityAnalysis

PKParameterSensitivity: The sensitivity (field $value) of a PK-Parameter ($pkParameterName) for the output $outputPath calculated for the varied parameter $parameterName. See Sensitivity analysis for more information.