SensitivityAnalysis WP6

[PavelBal]

Also read https://docs.open-systems-pharmacology.org/shared-tools-and-example-workflows/sensitivity-analysis for introduction of how sensitivity analysis (SA) is performed in OSPS.

A function (or a set of functions) for convenient execution of local sensitivity analysis on models developed with OSPS. As inputs, the user should be able to specify:

• A Simulation object
• Model output path(s) to analyze
  • e.g. "Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood)"
• Path(s) of model parameter(s) to be variated, e.g.

  parameterPaths <- c(
  "Aciclovir|Lipophilicity",
  "Applications|IV 250mg 10min|Application_1|ProtocolSchemaItem|Dose",
  "Neighborhoods|Kidney_pls_Kidney_ur|Aciclovir|Glomerular Filtration-GFR|GFR fraction"
  )

• Ranges within which parameter values should be varied (with some default vector)
  • The values are scaleFactors that are multiplied by the reference parameter value (i.e., the value as in the supplied Simulation
• PK parameters for which the sensitivity should be analyzed (see e.g. https://www.nuventra.com/resources/blog/pharmacokinetic-parameters/ for introduction to PK parameters)
  • List of names of PK-parameters that will be calculated. A default value should be

    pkParams = c("C_max", "t_max", "AUC_inf")

Sensitivity calculation

The first function, e.g. sensitivityCalculation, should perform the following:

• Run a simulation with parameter values as provided in the Simulation object and generate results for all outputs specified in the output paths argument. The values of parameters correspond to scale factor == 1, and results are considered as referenceResults.

• For each parameter to vary (== analyze how sensitive model outputs are to changing this parameter's value)

  • For each scale factor defined in the range
  • Set the value of the parameter to referenceValue * scaleFactor
  • Values of other parameters are at their referenceValue
  • Run simulation and save results

• For each simulation result (== for each combination of inputParameter and scaleFactor), calculate the PK-parameters for each output.

Results should be returned in a structure (data frame?) that can be passed to the functions that will create time-values profiles and sensitivity "spider plot" figures (definition below). Additionally, results should be saved in an excel file if the user specifies a path to the file (if the file with the specified name is already present, it will be overwritten). The excel file should have the following structure:

• Separate sheet for each defined output. E.g., the names of the sheets could be "Output_1" ... "Output_n" with n being the total number of defined model outputs to analyze. (Output paths cannot be used as sheet names as they can be very long).
• Each sheet contains following columns:
  • OutputPath: full path of the output. All entries will be equal for one sheet
  • ParameterPath: full path of the varied parameter
  • ParameterFactor: scale factor by which the parameter with ParameterPath has been multiplied for this particular simulatoin
  • ParameterValue: absolute value of the parameter used in the simulation
  • For each calculated PK-parameter:
    • Name of the PK-parameter (e.g. Cmax): calculated value of the PK-parameter
    • S_PKParamName (e.g. S_Cmax): denotes the "Sensitivity for PK parameter to the input parameter, and calculated as described in https://docs.open-systems-pharmacology.org/shared-tools-and-example-workflows/sensitivity-analysis#mathematical-background (NOT the average!)

Time profiles visualization

A second function, eg. sensivitityTimeProfiles, should create time-values profile figures for the output generated by sensitivityCalculation.

For each output defined in sensivitityTimeProfiles:

• Create a multi-panel figure, with one panel per varied model parameter
• Figure title: full output path (e.g., "Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood)")
• Panel title: Full path of the varied parameter (e.g., "Aciclovir|Lipophilicity")
• x-axis - time values of the simulated output in minutes, axis caption "Time [min]"
• y-axis - simulated values of the output in base units, axis caption "Dimension [unit]"
• Plotted are simulated values versus simulated time as curves for all parameter scale factors. The curve that corresponds to the simulation with scale factor = 1 is distinct (e.g., thicker and distinct color). All other curves are colored with a color gradient depicting parameter scaling. The legend shows a "heat map" corresponding to the coloring of the curves and denotes the color gradient ranging from lowest to highest parameter scale factor.
• Within one figure, all panels should have the same y axis limits for convenient comparison.
• The user should be able to change the scaling of the y-axis between linear and log via an argument of the function
• The user can specify if the figures are saved as files. If so, file naming should be TO BE SPECIFIED. Stick to counter for now...

Sensitivity spider plots

A third function, e.g. sensitivitySpiderPlot, generates a set of so-called sensitivity spider plots (example below. Be aware that the example shows % change on the y-axis, but the specification requires [% of reference]:)

For each output defined in sensivitityTimeProfiles:

• Create a multi-panel figure, with one panel per PK-parameter
• Figure title: full output path (e.g., "Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood)")
• Panel title: Name of the PK-parametr (e.g., Cmax)
• x-axis - scale factors of the parameters in %. Caption: "Input parameter value [% of reference]"
• y-axis - PK-parameter values in % of reference simulation. Caption: "PK-parameter value [% of reference]"
• A curve is created for each input parameter, showing the relationship between input parameter value (in % of reference) and simulated PK-parameter value (in % of reference). Therefore, 100% on the x-axis corresponds to 100% in the y-axis
• Values are represented as symbols connected by lines
• Legend denotes the different input parameters (full paths)
• The user should be able to change the scaling of the x and y-axes between linear and log via an argument of the function
• The user can specify if the figures are saved as files. If so, file naming should be TO BE SPECIFIED. Stick to counter for now... Alternative to figures as PNG: save as PDF per output.

Remarks

• Make sure that one simulation is run with "default" parameter values, i.e. scaling is 1
• Remove duplicated values from the variation range, if provided (also make sure 1 is simulated only once)
• Simulate in parallel for all provided parameters (create separate simulation batch - @PavelBal )

[PavelBal]

• Show % change from baseline (i.e., scale factor 1 = 0 on y axis), or better % from baseline (i.e., scale factor 1 = 100 on y axis)

[IndrajeetPatil]

Instead of

  pkParams = c(
    StandardPKParameter$C_max,
    StandardPKParameter$t_max,
    StandardPKParameter$AUC_tEnd
  )

I was thinking the default will be NULL, which would include all PK parameters. When not NULL, only those PK parameters will be retained in data and plots. Sounds reasonable?

[PavelBal]

Hmm no, not really, there are 22 standard PK parameters defined in PK sim and it would generate just too much output. Most of the time people are just interested in

    StandardPKParameter$C_max,
    StandardPKParameter$t_max,
    StandardPKParameter$AUC_inf

[IndrajeetPatil]

In that case, is it okay if the parameter actually takes in a vector of strings/character type specifying needed PK parameters? That is,

pkParams = c("C_max", "t_max", "AUC_inf")

And the documentation will make clear that the names of all available PK parameters can be found in names(StandardPKParameter)?

Those enums evaluate to numbers and are difficult to work with further, while with a character vector, I can just filter out the needed PK parameters.

[PavelBal]

Ah yes... No idea why the enum is defined that way.... Yes sure, it should be strings, I didn't realize these were integers in the enum.

[IndrajeetPatil]

We also have outputPath argument for sensitivityAnalysis(). What needs to happen if there are multiple output paths specified by the user? Do they need to be mapped to color or shape or etc.?

[PavelBal]

What needs to happen if there are multiple output paths specified by the user? Do they need to be mapped to color or shape or etc.?

No, let's keep it simple and create one figure per path.

[IndrajeetPatil]

Okay, I have implemented this, but can't find a dataset to play with that has multiple output paths. There is simple.pkml in the package, but that doesn't seem to be a realistic dataset to try this out.

Any suggestions?

Current example, which has only a single path:

simulation <- loadSimulation("Aciclovir.pkml")
outputPaths <- "Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood)"
parameterPaths <- c(
  "Aciclovir|Lipophilicity",
  "Applications|IV 250mg 10min|Application_1|ProtocolSchemaItem|Dose",
  "Neighborhoods|Kidney_pls_Kidney_ur|Aciclovir|Glomerular Filtration-GFR|GFR fraction"
)
variationRange <- c(seq(0.2, 1, by = 0.1), seq(2, 10, by = 1)) # c(0.1, 1, 2)

sensitivityAnalysis(
  simulation = simulation,
  outputPaths = outputPaths,
  parameterPaths = parameterPaths,
  variationRange = variationRange,
  pkParams = NULL
)

[msevestre]

Just add any other output from your model Organism|VenousBlood|Plasma|Aciclovir