Skip to contents
require(ospsuite.reportingengine)
#> Loading required package: ospsuite.reportingengine
#> Loading required package: ospsuite
#> Loading required package: rSharp
#> 
#> Attaching package: 'ospsuite'
#> The following object is masked from 'package:base':
#> 
#>     %||%
#> Loading required package: tlf

Get started

What for ?

Creating and customizing your workflow using R can be challenging.

Leveraging Excel, you can define your workflow, all its elements, settings and options with a few clicks.

The Excel template was created so that users can design their own workflows by directly tuning a working example.

What is it ?

The Excel template is an xlsx document that defines all the relevant information of a working workflow.

The function createWorkflowFromExcelInput() converts such Excel document into an R script that defines your workflow in plain R code. Then, you can run your workflow by running the R script (e.g. using the function source()).

Where can I get the template ?

The Excel template is available through the following link WorkflowInput.xlsx.

Standard Excel Sheet Names

The Excel template includes a few standard Excel sheets that are required for the conversion into R code.

Documentation

The Excel sheet Documentation aims at documenting your R script. All of its content will be added as commented text (preceded by # character) in first lines of your R script.

Table : Documentation sheet
Purpose: Please fill in the purpose of the script
M&S activity: Please fill in the corresponding M&S activity
Validation level: Please fill in the Validation level

Workflow and Tasks

The Excel sheet Workflow and Tasks defines the main attributes of your workflow.

Table : Workflow and Tasks sheet
Code Identifier Description Value
Workflow Mode Mode of workflow.
- If set to MeanModelWorkflow: a mean model workflow is created
- If set to PopulationWorkflow: a population workflow is created
MeanModelWorkflow
Population Workflow type Relevant for population workflows only parallelComparison
workflowFolder Output folder of the workflow RELATIVE to workflow.R, e.g. Report or Report/Part1 (use slash! Not backslash) Report
reportTitle Title included on top of the report
reportFileName Name of the report file. Remember to include Markdown .md extension. Keep empty to use the default
createWordReport If activated: MS Word report will be created additionally to Markdown report Yes
simulationSetDescriptor Optional alternative name for ‘simulation set’, to be used in reports.
plotFormat Select plot format; keep empty to use the default
Active tasks
simulate Activate workflow task “simulate”? Yes
calculatePKParameters Activate workflow task “calculatePKParameters”? Yes
calculateSensitivity Activate workflow task “calculateSensitivity”? Yes
plotTimeProfilesAndResiduals Activate workflow task “plotTimeProfilesAndResiduals”? Yes
plotPKParameters Activate workflow task “plotPKParameters”? Yes
plotSensitivity Activate workflow task “plotSensitivity”? Yes
plotAbsorption Activate workflow task “plotAbsorption”? (relevant for mean model workflow only) Yes
plotMassBalance Activate workflow task “plotMassBalance”? (relevant for mean model workflow only) Yes
plotDemography Activate workflow task “plotDemography”? (relevant for population workflow only) Yes
Task-specific options
simulate: numberOfCores “simulate” task: number of cores to use. Relevant for POPULATION workflow only.
Leave empty to use the default value (=number of cores -1).
Setting to a non-empty value>1 requires MPI (use only when running on more than 1 physical machine (e.g. cloud etc.))
simulate: showProgress “simulate” task: show progress. Relevant for POPULATION workflow only. Yes
calculateSensitivity: numberOfCores “calculateSensitivity” task: number of cores to use.
Leave empty to use the default value (=number of cores -1).
Setting to a non-empty value>1 requires MPI. Use this option only when running on more than 1 physical machine (e.g. cloud etc.)
calculateSensitivity: showProgress “calculateSensitivity” task: show progress.
calculateSensitivity: quantileVec “calculateSensitivity” task: quantiles for sensitivity analysis. Relevant for POPULATION workflow only. c(0.05, 0.50, 0.95)
calculateSensitivity: variationRange “calculateSensitivity” task: Variation range (s. OSP documentation for details). Leave empty to use the default.
calculateSensitivity: variableParameterPaths “calculateSensitivity” task: paths of parameters to vary when performing sensitivity analysis.
- leave empty to calculate sensitivity of all suitable parameters (non-categorical, effectively used, non-zero, non-table, …)
- otherwise: provide sheet name with parameter paths
plotSensitivity: maximalParametersPerSensitivityPlot “plotSensitivity” task: maximal number of parameters to display in a sensitivity plot. Leave empty to use the default.
plotSensitivity: totalSensitivityThreshold “plotSensitivity” task: cut-off used for plots of the most sensitive parameters. Leave empty to use the default.
plotSensitivity: xAxisFontSize “plotSensitivity” task: font size for the X axis. Leave empty to use the default.
plotSensitivity: yAxisFontSize “plotSensitivity” task: font size for the Y axis. Leave empty to use the default.
Activity specific code
activitySpecificCode Leave empty if there is no activity specific code.
Otherwise: the name of the R function which will be called directly before workflow$runWorkflow() in the generated R code.
This function must be placed in the same directory as the generated R code and must have 1 argument of the type “workflow”.
It can modify the created workflow directly before execution (e.g. change options, add user-defined tasks, …)

SimulationSets

The Excel sheet SimulationSets defines the simulation sets and their properties of your workflow.

Table : SimulationSets sheet
Code Identifier Description SimulationSet1 SimulationSet2
simulationSetName Unique name of the simulation set (will appear in report)
simulationFile Path to the simulation file (pkml) RELATIVE to workflow.R, e.g. Lysergsäurediethylamid.pkml or Models/Lysergsäurediethylamid.pkml
outputs name of included outputs defined in Outputs sheet. Separate outputs with a coma to include multiple outputs Output1, Output2 Output1, Output2
dataSource name of included data sources defined in Data Sources sheet
dataSelection data selection filter for nonmem data file. Allowable inputs:
- ALL: all data selected
- NONE: no data selected
- If left empty, no data are selected
- R readable filter: data selection according to the filter
ALL ALL
dataDisplayName display name of the observed data in report. Will be concatenated with the output display name Study A StudyB
timeUnit display unit for time variable h min
timeOffset simulation start offset 0 0
All settings below are relevant for POPULATION workflows only
populationFile Path to the population file (csv) RELATIVE to workflow.R, e.g. Pop.csv or Populations/Pop.csv
populationName display name of population
referencePopulation Reference population used in Pediatric and Ratio Comparison workflows No No
plotReferenceObsData Observed data from reference population is plotted in a Simulation Set time profiles of Pediatric and Ratio Comparison workflows No No
StudyDesignType S. StudyDesignLocation for explanation FILE SHEET
StudyDesignLocation - If Empty: no study design
- If StudyDesignType is set to FILE: path to the StudyDesign file RELATIVE to workflow.R, e.g. StudyDesign.csv or Data/StudyDesign.csv
- If StudyDesignType is set to SHEET: name of the sheet for study design generation
StudyDesign
All settings below are relevant for MEANMODEL workflows only
massBalanceFile Path to the mass balance settings (json) RELATIVE to workflow.R, e.g. mass-balance-settings.json or Models/mass-balance-settings.json

Outputs

The Excel sheet Outputs defines the properties of each output paths.

Table : Outputs sheet
Code Identifier Description Output1 Output2
path output path Organism|PeripheralVenousBlood|C1|Plasma (Peripheral Venous Blood) Organism|Lumen|C1|Fraction of oral drug mass absorbed into mucosa
displayName label for report C1 plasma fraction absorbed
displayUnit time profile display unit µg/l %
groupID identifier for splitting outputs by the combination {displayUnit; groupID}. Each combination becomes then a separate plot
color display color for lines and points in time profiles and residual plots #5050FF
fill display color for ranges and histograms in time profiles and residual plots #5050FF
dataSelection data selection filter for nonmem data file (will be combined with SimSet data selection per & ). Allowable inputs:
- R readable filter
- ALL: all data selected
- NONE: no data selected
- If left empty, no data are selected
- R readable filter: data selection according to the filter
ALL ALL
dataDisplayName display name of the observed data in report. Will be appended to the observed data display name of parent simulation set Plasma Fraction Absorbed
dataUnit unit of corresponding observed data in dataset
pkParameters Sheet name with PK parameters definition for the given output PK Conc Single PK Fraction

Check section How to define Output objects ? for more details on how to set up observed data sets.

Data Sources

The Excel sheet Data Sources defines the observed data sets and their properties.

Table : Data Sources sheet
Code Identifier Description Source1 Source2
dataFile Path to the observed data file (nonmem format) RELATIVE to workflow.R, e.g. Raltegravir_PK.txt or Data/Raltegravir_PK.txt
DictionaryType S. DictionaryLocation for explanation FILE SHEET
DictionaryLocation - If DictionaryType is set to FILE: path to the dictionary file RELATIVE to workflow.R, e.g. tpDictionary.csv or Data/tpDictionary.csv
- If DictionaryType is set to SHEET: name of the sheet for dictionary generation
tpDictionary
caption Displayed data source caption in the report. The caption will be preceeded by Data source:

Check section How to define observed data sets ? for more details on how to set up observed data sets.

Userdef PK Parameter

This standard sheet is required when user-defined PK Parameters are calculated in your simulations.

Check section How to define PK Parameters ? for more details on how to set up user-defined PK Parameters.

SensitivityParameter

This standard sheet is a template that can be tuned to inform which specific input parameters you wish to vary in your sensitivity analysis.

Check section How to set up sensitivity analyses ? for more details on how to set up the input parameters.

tpDictionary

This standard sheet is a template that can be tuned to inform the meta data of your observed datasets.

Check section How to define observed datasets ? for more details on how to set up the dictionary of your datasets.

How to ?

How to define Output objects ?

To define and include Output objects in your Simulation Sets, users only need to

1- Define them in the standard Excel sheet Outputs

2- Declare the name of the created output(s) in the Excel sheet SimulationSets in the cell corresponding to outputs. A drop-down menu is available and allows you to select directly an output defined in the sheet Outputs. Users can also provide multiple outputs within the cell, however they need to be separated by a comma (character ,).

How to define PK Parameters ?

To define and include PK Parameters users need to

1- Define them in an Excel sheet using the Excel sheet PK Parameter as reference (PK Conc Single, PK Conc Multi and PK Fraction can also be used as reference)

Table : PK Parameter template sheet
Name Display name Unit
C_max C max µg/l
C_max_norm C max norm kg/l
t_max T max h
C_tEnd C End µg/l
AUC_tEnd AUC µg*h/l
AUC_tEnd_norm AUC norm kg*h/l
AUC_inf AUC inf µg*h/l
AUC_inf_norm AUC inf norm kg*h/l
MRT MRT h
Thalf Thalf h
CL CL ml/min/kg
Vss Vss ml/kg
Vd Vd ml/kg
C_max_tD1_tD2 C_max_t1_t2 µg/l
C_max_tD1_tD2_norm C_max_t1_t2_norm kg/l
C_max_tDLast_tEnd C_max_tLast_tEnd µg/l
C_max_tDLast_tEnd_norm C_max_tLast_tEnd_norm kg/l
t_max_tD1_tD2 t_max_t1_t2 h
t_max_tDLast_tEnd t_max_tLast_tEnd h
C_trough_tD2 C_trough_t2 µg/l
C_trough_tDLast C_trough_tLast µg/l
AUC_tD1_tD2 AUC_t1_t2 µg*h/l
AUC_tD1_tD2_norm AUC_t1_t2_norm kg*h/l
AUC_tDLast_minus_1_tDLast AUC_tLast_minus_1_tLast µg*h/l
AUC_tDLast_minus_1_tDLast_norm AUC_tLast_minus_1_tLast_norm kg*h/l
AUC_inf_tD1 AUC_inf_t1 µg*h/l
AUC_inf_tD1_norm AUC_inf_t1_norm kg*h/l
AUC_inf_tDLast AUC_inf_tLast µg*h/l
AUC_inf_tDLast_norm AUC_inf_tLast_norm kg*h/l
Thalf_tDLast_tEnd Thalf_tLast_tEnd h
F_tEnd F_tEnd %
F_max F_max %

2- Declare the name of the created sheet in the Excel sheet of your Output object in the cell corresponding to pkParameters

User-defined PK Parameters

One additional sheet is required for user-defined PK Parameters. Use the standard Excel sheet Userdef PK Parameter to define your own user-defined PK Parameter and include the names of the parameters in your PK Parameters sheet.

How to define observed data sets ?

Observed data sets are managed using DataSource objects.

To define and include observed data users need to

1- Define them in the standard Excel sheet Data Sources

2- Declare the name of the sources in the standard Excel sheet SimulationSet within the cell corresponding to dataSource. A drop-down menu is available and allows you to select directly a data source defined in the sheet Data Sources. Users can only provide a unique dataSource within the corresponding cell.

DataSource objects require a metaDataFile defining the content of the observed dataset. This meta data can be provided either by using an Excel sheet of your Excel document or by using a separate csv file.

  • If dictionary is defined as an Excel sheet:
    • Go to the standard Excel sheet Data Sources
    • Select the option SHEET in the cell corresponding to your DictionaryType
    • Include the name of the sheet in the cell corresponding to DictionaryLocation
      You can use the Excel sheet tpDictionary as reference
  • If dictionary is defined as a separate csv file:
    • Go to the standard Excel sheet Data Sources
    • Select the option FILE in the cell corresponding to your DictionaryType
    • Include the path of the file in the cell corresponding to DictionaryLocation
      You can download and use the template tpDictionary.csv as reference

How to set up sensitivity analyses ?

Because sensitivity analyses calculate and display the relative impact of selected - or all - input parameters on the PK parameters of those selected output curves, they can be performed and displayed in many ways

For such reason, workflows provide a lot of options and settings that will help you design the specific analysis you wish to perform.

To include a sensitivity analysis in your workflow report, you need to activate the following tasks: simulate, calculatePKParameters, calculateSensitivity, and plotSensitivity.

To activate these tasks, go to the standard Excel sheet Workflow and Tasks and set the Values of the corresponding cells to Yes.

In the same Excel sheet, you will find many options for your sensitivity analysis under the section Task-specific options.

The first set of options are related to the calculation of the sensitivity.

In these options, you can set up the variation range of all or selected input parameters. This range defines the amplitude of the variations/perturbations applied around the value in the simulation. For more details about the variation range, you can check the OSP Suite documentation on sensitivity analysis.

Another option is the selection of specific input parameters on which applying the variations. To include only selected input parameters users need to

1- Define them in an Excel sheet using the Excel sheet SensitivityParameter as reference

Table : SensitivityParameter template sheet
Path
C1|Lipophilicity
C1|Specific intestinal permeability (transcellular)

2- Declare the name of the created sheet in the standard Excel sheet Workflow and Tasks in the cell corresponding to calculateSensitivity: variableParameterPaths

The second set of options are related to the sensitivity plots and helps you defining how many input parameters are displayed and how they are displayed.

How add a Study Design table ?

It is possible to add a special parameters variation which is not exported in your initial population by including a StudyDesign table to your workflow.

To define Study Design tables users can either leverage an Excel sheet of the Excel document or they can use a separate csv file.

  • If the Study Design is defined as an Excel sheet:
    • Go to the standard Excel sheet SimulationSets
    • Select the option SHEET in the cell corresponding to your StudyDesignType
    • Include the name of the sheet in the cell corresponding to StudyDesignLocation
      You can use the Excel sheet StudyDesign as reference
  • If Study Design is defined as a separate csv file:
    • Go to the standard Excel sheet SimulationSets
    • Select the option FILE in the cell corresponding to your StudyDesignType
    • Include the path of the file in the cell corresponding to StudyDesignLocation
      You can download and use the template StudyDesign.csv as reference
Table : StudyDesign sheet
#> New names:
#>  `Organism|Weight` -> `Organism|Weight...1`
#>  `Organism|Weight` -> `Organism|Weight...2`
Organism|Weight…1 Organism|Weight…2 Gender Applications|IV Bolus|DrugMass
kg kg nmol
SOURCE_MIN SOURCE_MAX SOURCE_EQUALS TARGET
20 40 MALE 2
20 40 FEMALE 2.5
40 60 MALE 10
40 60 FEMALE 14
60 20

How to include your own code ?

Workflows can be updated by a user-defined function before execution (e.g. change options, add user-defined tasks, …) by including the function call before the line workflow$runWorkflow() in your R script.

To do so, in the standard Excel sheet Workflow and Tasks, you can include in the cell corresponding to activitySpecificCode the name of the R function.

Note that this function must be placed in the same directory as the generated R code and must have 1 argument of the type "workflow".