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: tlfGet 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
- Workflow and Tasks
- SimulationSets
- Data Sources
- Outputs
- Userdef PK Parameter
- PK Parameter
- SensitivityParameter
- tpDictionary
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
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".