In Open-Systems-Pharmacology/OSPSuite-R: R package to manipulate OSPSuite Models

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.showtext = TRUE
)

The models built with OSPS depend on a lot of input parameters which are based on literature values, measurements, databases, and assumptions. For a given set of input parameters, a number of output curves is computed in a simulation. To assess which input parameters have most impact on the output curves, a sensitivity analysis of the simulation can be performed. For more information about theoretical background, see OSPS documentation.

In brief, the values of the chosen parameters are changed by a certain percentage and the impact of these changes on PK parameters of model outputs is assessed.

Performing a sensitivity analysis

The first step of performing a sensitivity analysis is creating an object of the class SensitivityAnalysis. At this step, the user can define which parameters should be considered for the sensitivity analysis, in which range the values are varied, and how may steps are performed in one direction (plus and minus). If no parameters are specified, all constant and suitable for sensitivity calculations parameters of the simulation will be varied. The list of such parameters paths for a simulation can be accessed with the method potentialVariableParameterPathsFor(simulation).

library(ospsuite)

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

# Get the paths of parameters that will be considered by default.
potentialSAParameters <- potentialVariableParameterPathsFor(sim)
print(potentialSAParameters)

# Create a default `SensitivityAnalysis` for the simulation
sa <- SensitivityAnalysis$new(simulation = sim)
print(sa)

# Create a `SensitivityAnalysis` with specified parameters
sa <- SensitivityAnalysis$new(simulation = sim, parameterPaths = c("Organism|Q", "Organism|Volume"))
print(sa)

# Show which parameters will be varied
sa$parameterPaths

New parameters can be added to an existing SensitivityAnalysis by calling the method addParameterPaths().

NOTE: - If no parameters were specified during the creation of a SensitivityAnalysis, all constant and suitable for sensitivity calculation parameters are considered. - In such cases, calling addParameterPaths() will only vary the newly added parameters.

library(ospsuite)

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

# Create a `SensitivityAnalysis` with specified parameters
sa <- SensitivityAnalysis$new(simulation = sim, parameterPaths = c(
  "Organism|Q",
  "Organism|Volume"
))
# Add new parameter
sa$addParameterPaths("R1|k1")

# Show which parameters will be varied
sa$parameterPaths

To run the specified SensitivityAnalysis, call the method runSensitivityAnalysis(). The method returns an object of the class SensitivityAnalysisResults. The impact of the defined parameters is calculated for PK-Parameters (see PK Analysis for more information) of all model outputs.

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

# Create a `SensitivityAnalysis` with all constant and suitable for sensitivity calculations parameters and suitable for sensitivity calculations parameters
sa <- SensitivityAnalysis$new(simulation = sim)

# Run the sensitivity analysis
saResult <- runSensitivityAnalysis(sa)
print(saResult)

The method allPKParameterSensitivitiesFor() returns a list of PKParameterSensitivity objects. PKParameterSensitivity describes the sensitivity (field $value) of a PK-Parameter ($pkParameterName) for the output $outputPath calculated for the varied parameter $parameterPath. The argument totalSensitivityThreshold of the method allPKParameterSensitivitiesFor() is used to filter out the most impactful parameters. A threshold of 0.9 means that only parameters participating to a total of 90 percent of the sensitivity would be returned. A value of 1 would return the sensitivity for all parameters. If no value is provided, a default value is used.

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

# Default value of the threshold
getOSPSuiteSetting("sensitivityAnalysisConfig")$totalSensitivityThreshold

# Create a `SensitivityAnalysis` with all constant parameters and run it
sa <- SensitivityAnalysis$new(
  simulation = sim,
  parameterPaths = c(
    "Aciclovir|Lipophilicity",
    "Aciclovir|Fraction unbound (plasma)",
    "Organism|Age"
  )
)
saResult <- runSensitivityAnalysis(sa)
print(saResult)

# Get sensitivities for the parameter "AUC_inf" of the simulated output with a threshold of 0.8
outputPath <- sim$outputSelections$allOutputs[[1]]$path
sensitivities <- saResult$allPKParameterSensitivitiesFor(pkParameterName = "AUC_inf", outputPath = outputPath, totalSensitivityThreshold = 0.8)
print(sensitivities)

The value -1 for the sensitivity of "AUC_inf" of the output Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood) for the parameter Organism-Kidney-Volume means that increasing Organism-Kidney-Volume by 10% will decrease "AUC_inf" by 10%. Note that the list of sensitivities is ordered from largest to smallest with respect to magnitude.

Import and export of sensitivity analysis results

Sensitivity analysis calculated in R can be exported to a *.csv file, which can be loaded in another instance.

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

# Create a `SensitivityAnalysis` with all constant parameters and run it
sa <- SensitivityAnalysis$new(simulation = sim)
saResult <- runSensitivityAnalysis(sa)

# Export to csv
saResultPath <- system.file("extdata", "SAResult.csv", package = "ospsuite")
exportSensitivityAnalysisResultsToCSV(results = saResult, filePath = saResultPath)

# Load from csv
saResultLoaded <- importSensitivityAnalysisResultsFromCSV(filePaths = saResultPath, simulation = sim)