Calculating PK parameters of simulation outputs

Calculating PK parameters

The {ospsuite} package gives you access to the standard PK Parameters calculated by PK-Sim such as AUC, Cmax etc. For the complete list of PK Parameters supported out of the box, please refer to the online documentation.

PK parameters can be calculated for all outputs of a simulation. First, simulation results must be calculated, and the SimulationResults object is then passed to the method calculatePKAnalyses. For the list of calculated PK parameters and their description, please refer to OSPS documentation.

library(ospsuite)

# Load the simulation
simFilePath <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite")
sim <- loadSimulation(simFilePath)

# Run the simulation
simulationResults <- runSimulations(simulations = sim)[[1]]

# Calculate PK-analyses
pkAnalysis <- calculatePKAnalyses(results = simulationResults)

# Get the path of the simulated output
outputPath <- simulationResults$allQuantityPaths[[1]]
print(outputPath)

# Get all calculated PK parameters for the output path
allPkParams <- pkAnalysis$allPKParametersFor(outputPath)
print(allPkParams)

# Get C_max parameter
c_max <- pkAnalysis$pKParameterFor(quantityPath = outputPath, pkParameter = "C_max")
c_max

The function calculatePKAnalyses returns an object of the class SimulationPKAnalyses, which allows to retrieve either a certain PK parameter for an output path, or all calculated PK parameters for an output path.

The methods $allPKParametersFor() and $pKParameterFor() return a object (or a list of objects) of the class QuantityPKParameter, with 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).

# Get C_max parameter
c_max <- pkAnalysis$pKParameterFor(quantityPath = outputPath, pkParameter = "C_max")

print(c_max)

c_max$name
c_max$quantityPath
c_max$values

In case of a population simulation, $values return a list of values calculated for each individual.

Extracting a dataframe

Sometimes it is desirable to have the calculated parameters in a dataframe for working with them further in other workflows (e.g. data wrangling), and the package provides a convenient helper to extract it:

pkAnalysesToDataFrame(pkAnalysis)

Import and export of PK-analyses

Population analysis calculated in R can be exported to a *.csv file and loaded in PK-Sim, and vice versa.

# Load and run the simulation
simFilePath <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite")
sim <- loadSimulation(simFilePath)
simulationResults <- runSimulations(simulations = sim)[[1]]

# Calculate PK-analysis
pkAnalysis <- calculatePKAnalyses(results = simulationResults)

# Export to csv
csvPKAnalysisPath <- system.file("extdata", "PKAnalyses.csv", package = "ospsuite")
exportPKAnalysesToCSV(pkAnalyses = pkAnalysis, filePath = csvPKAnalysisPath)

# Load from csv
pkAnalysisLoaded <- importPKAnalysesFromCSV(filePath = csvPKAnalysisPath, simulation = sim)

User-Defined PK Parameters

The {ospsuite} package also supports user-defined PK Parameters, e.g. PK Parameter that can be tailored to specific project needs. This feature is useful when calculating PK Parameters for specific time intervals, or to apply PK Parameters for output not using the dimension Concentration.

A User-Defined PK Parameter is always based on an existing PK-Parameter and simply extends the way the output is calculated. It is not possible at the moment to define your own formula.

The utility addUserDefinedPKParameter creates and returns an instance of the UserDefinedPKParameter which can then be parameterized for specific requirements.

# Adds a user defined parameter named `MyAuc` that will calculate the value of AUC between t=50 min and t=80min only.

# Create a new parameter based on the standard AUC parameter
myAUC <- addUserDefinedPKParameter(
  name = "MyAUC",
  standardPKParameter = StandardPKParameter$AUC_tEnd
)

# Specifies start time and end time in minute
myAUC$startTime <- 50
myAUC$endTime <- 80

# Adds a user defined parameter named `MyCMax` that will calculate the value of Cmax between the 4th and 5th application

# Create a new parameter based on the standard C_max parameter
myCMax <- addUserDefinedPKParameter(
  name = "MyCMax",
  standardPKParameter = StandardPKParameter$C_max
)

# Specifies start application (4th) and end application (5th)
myCMax$startApplicationIndex <- 4
myCMax$endApplicationIndex <- 5

# Adds a user defined parameter named `MyCMax` that will calculate the value of Cmax between the 4th application start time + 10 min and
# the 5th application start time + 20min

# Create a new parameter based on the standard C_max parameter
myCMax <- addUserDefinedPKParameter(
  name = "MyCMax",
  standardPKParameter = StandardPKParameter$C_max
)

# Specifies start application (4th) and end application (5th)
myCMax$startApplicationIndex <- 4
myCMax$endApplicationIndex <- 5

# Specifies start time offset. The PK calculations will effectively start at StartTime of 4th Application + 10 min
myCMax$startTimeOffset <- 10

# Specifies end time offset. The PK calculations will effectively ends at StartTime of 5th Application + 20 min
myCMax$endTimeOffset <- 20

# Let's assume there is an observer called Q_observer in mg/m2 using the dimension Dose per body surface area.
# Simply using C_max would result in the parameter being shown in umol\l.
# To see the correct unit and dimension, the following can be done:

QMax <- addUserDefinedPKParameter(
  name = "Q_max",
  standardPKParameter = StandardPKParameter$C_max,
  displayName = "Q max",
  displayUnit = "mg/m²"
)